# JSON Mapping & Context MCP Servers
This repo hosts two small MCP servers that showcase schema-aware JSON exploration and live data retrieval:
- **JSON Mapping Finder** (`json_mapping_server.py`): Upload any JSON sample, flatten its schema, and use heuristic search (token overlap + fuzzy matching) to find paths for target field names. Great for accelerating ETL/API onboarding.
It is intentionally lightweight and fully HTTP-based for easy inspection with the MCP Inspector or Copilot Chat.
## Highlights
- **Schema-aware parsing**: Flattens nested JSON, captures types/examples, and tracks depth.
- **Heuristic mapping**: Token overlap, substring checks, and fuzzy matching to suggest likely field paths.
- **Plug-and-play MCP**: Uses `StreamableHTTPSessionManager` for modern MCP HTTP transport.
- **Portable**: Pure Python, no external services beyond Open-Meteo.
## Quick Start
Prereqs: Python 3.12+ and a virtual environment (`.venv` recommended).
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r <(python - <<'PY'
import tomllib, sys
deps = tomllib.load(open("pyproject.toml","rb"))["project"]["dependencies"]
print("\n".join(deps))
PY)
```
### Run the JSON Mapping Finder (port 3004)
```bash
.venv/bin/python json_mapping_server.py
```
Then inspect with:
```bash
npx -y @modelcontextprotocol/inspector http://localhost:3004
```
Exposed tools:
- `upload_json_sample(json_data)`: load a JSON sample (e.g., `sample_json.json`) and build the schema index.
- `list_schema(limit=200)`: view flattened paths with type + example values.
- `search_fields(query, top_k=10)`: find likely paths for a single query.
- `map_targets(targets, top_k=5)`: bulk mapping suggestions for multiple field names.
- `clear_samples()`: reset the index.
## Sample Data
- `sample_json.json`: a non-medical, nested sample for testing the JSON Mapping Finder.
## Configuration
If you want to wire these into Copilot Chat, add entries like:
```json
{
"mcpServers": {
"json-mapping": { "url": "http://localhost:3004" }
}
}
```
## How it works (JSON Mapping Finder)
1. **Indexing**: Walks objects/arrays, records paths (`$.foo.bar[*]`), types, example values, and depth.
2. **Scoring**: Combines exact/substring boosts, Jaccard token overlap, and fuzzy ratio; lightly penalizes deep paths.
3. **Suggestions**: Returns top matches with scores so you can review/accept quickly.
## Notes
- No API keys required.
- All code is ASCII-only and dependency-light.
