metadata

title: MedCodeMCP
emoji: 💬
colorFrom: yellow
colorTo: purple
sdk: gradio
sdk_version: 5.32.1
app_file: app.py
pinned: false
license: apache-2.0
short_description: an MCP Tool for Symptom-to-ICD Diagnosis Mapping.
tags:
  - mcp-server-track

A chatbot using Gradio, huggingface_hub, and my local RTX 2060 instead of Cloud APIs

MedCodeMCP – an MCP Tool for Symptom-to-ICD Diagnosis Mapping

MVP Scope

Accept a patient’s symptom description (free-text input).
Output a structured JSON with a list of probable diagnoses, each including:
- ICD-10 code
- Diagnosis name
- Confidence score
Handle a subset of common symptoms and return the top 3–5 likely diagnoses.

How It Works

Input Interface

Gradio-based demo UI for testing:
- Single text box for symptoms (e.g., “chest pain and shortness of breath”).
- Primary interface is programmatic (MCP client calls the server).

Processing Logic

Leverage an LLM (e.g., OpenAI GPT-4 or Anthropic Claude) to parse symptoms and suggest diagnoses.
Prompt example:

“The patient reports: {symptoms}. Provide a JSON list of up to 5 possible diagnoses, each with an ICD-10 code and a confidence score between 0 and 1. Use official ICD-10 names and codes.”
Recent experiments with medical foundation models (e.g., Google’s Med-PaLM/MedGEMMA) show they can identify relevant diagnosis codes via prompt-based reasoning (medium.com).
Using GPT-4/Claude in the loop ensures rapid development and high-quality suggestions (publish0x.com).

Confidence Scoring

Instruct the LLM to assign a subjective probability (0–1) for each diagnosis.
Accept approximate confidences for MVP.
Alternative: rank by output order (first = highest confidence).

ICD-10 Code Mapping

Trust LLM’s knowledge of common ICD-10 codes (e.g., chest pain → R07.9, heart attack → I21.x).
Sanity-check:
- Maintain a small dictionary of common ICD-10 codes.
- Use regex to verify code format.
- Flag or adjust codes that don’t match known patterns.
Future improvement: integrate a full ICD-10 lookup list for validation.

Alternate Approach

Use an open model fine-tuned for ICD coding (e.g., Clinical BERT on Hugging Face) to predict top ICD-10 codes from clinical text.
Requires more coding and possibly a GPU, but feasible.
For hackathon MVP, prioritize API-based approach with GPT/Claude (huggingface.co).

Output Format

JSON structure for easy agent parsing. Example:

{
  "diagnoses": [
    {
      "icd_code": "I20.0",
      "diagnosis": "Unstable angina",
      "confidence": 0.85
    },
    {
      "icd_code": "J18.9",
      "diagnosis": "Pneumonia, unspecified organism",
      "confidence": 0.60
    }
  ]
}


* Input: “chest pain and shortness of breath”
* Output: Cardiac-related issues (e.g., angina/MI) and respiratory causes, each with confidence estimates.
* Structured output aligns with MCP tool requirements for downstream agent reasoning.

## Gradio MCP Integration

* Implement logic in `app.py` of a Gradio Space.
* Tag README with `mcp-server-track` as required by hackathon.
* Follow “Building an MCP Server with Gradio” guide:

  * Use Gradio SDK 5.x.
  * Define a tool function with metadata for agent discovery.
  * Expose a prediction endpoint.

### Example Gradio Definition (simplified)

```python
import gradio as gr
import openai
def symptom_to_diagnosis(symptoms: str) -> dict:
    prompt = f"""The patient reports: {symptoms}. Provide a JSON list of up to 5 possible diagnoses, each with an ICD-10 code and a confidence score between 0 and 1. Use official ICD-10 names and codes."""
    response = openai.ChatCompletion.create(
        model="gpt-4",
        messages=[{"role": "system", "content": prompt}],
        temperature=0.2
    )
    # Parse response content as JSON
    return response.choices[0].message.content
demo = gr.Interface(
    fn=symptom_to_diagnosis,
    inputs=gr.Textbox(placeholder="Enter symptoms here..."),
    outputs=gr.JSON(),
    title="MedCodeMCP Symptom-to-ICD Mapper",
)
demo.launch()
```

* Ensure MCP metadata is included so an external agent can discover and call `symptom_to_diagnosis`.

## User Demo (Client App)

* Create a separate Gradio Space or local script that:

  * Calls the MCP server endpoint.
  * Renders JSON result in a user-friendly format.
* Optionally record a video demonstration:

  * Show an agent (e.g., Claude-2 chatbot) calling the MCP tool.
  * Verify end-to-end functionality.

## MVP Development Steps

1. **Set Up Gradio Space**

   * Initialize a new Hugging Face Space with Gradio SDK 5.x.
   * Tag README with `mcp-server-track`.

2. **Implement Symptom-to-Diagnosis Function**

   * Write a Python function to:

     * Accept symptom text.
     * Call GPT-4/Claude API with JSON-output prompt.
     * Parse the model’s JSON response into a Python dictionary.
     * Sanitize and validate JSON output.
   * Fallback: rule-based approach or offline model for demo cases if API limits are reached.

3. **Testing**

   * Input various symptom combinations.
   * Verify sensibility of diagnoses and correctness of ICD-10 codes.
   * Tweak prompt to improve specificity.
   * Ensure JSON structure is valid.

4. **Confidence Calibration**

   * Define how confidence scores are assigned:

     * Use LLM’s self-reported confidences, or
     * Rank by output order.
   * Document confidence methodology in README.

5. **Integrate with Gradio Blocks**

   * Wrap the function in a Gradio interface (`gr.Interface` or `gr.ChatInterface`).
   * Expose function as an MCP tool with appropriate metadata.
   * Test via `gradio.Client` or HTTP requests.

6. **Build a Quick Client (Optional)**

   * Option A: Second Gradio Space as MCP client showing how an LLM calls the tool.
   * Option B: Local script using `requests` to call the deployed Space’s prediction API.
   * Prepare a screen recording illustrating agent invocation.

7. **Polish Documentation**

   * In README:

     * Explain tool functionality and usage.
     * Include hackathon requirements: track tag, demo video or client link.
     * List technologies used (e.g., “Uses OpenAI GPT-4 via API to map symptoms to diagnoses”).
     * Provide example usage and sample inputs/outputs.

*By completing these steps, the MVP will demonstrate end-to-end functionality: input symptoms → structured diagnostic insights with ICD-10 codes and confidence scores via an MCP server.*