README.md

---
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](https://gradio.app), [`huggingface_hub`](https://huggingface.co/docs/huggingface_hub/v0.22.2/en/index), 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](https://medium.com)).
- Using GPT-4/Claude in the loop ensures rapid development and high-quality suggestions ([publish0x.com](https://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](https://huggingface.co)).

### Output Format
- JSON structure for easy agent parsing. Example:
  ```json
  {
    "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.*