modelcontextprotocol / modelcontextprotocol/python-sdk
Inline $ref in tool inputSchema for LLM consumption (parity with typescript-sdk)
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 24.3k
- Forks
- 4k
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 31
Description
tools/base.py:76 uses raw model_json_schema() which emits $ref/$defs for nested Pydantic models. LLM clients consuming tools/list often can't resolve $ref, leading to params being passed as stringified JSON instead of structured objects.
Repro / demand: anthropics/claude-code#18260 (Notion MCP server, $ref params get stringified by the model).
typescript-sdk addresses this in modelcontextprotocol/typescript-sdk#1563 by adding a dereferenceLocalRefs() step that inlines local $ref and throws on cycles (matching go-sdk precedent). Python should do the equivalent in the tool schema pipeline so all SDKs emit LLM-consumable schemas.
Relevant file: src/mcp/server/mcpserver/tools/base.py:76
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start at src/mcp/server/mcpserver/tools/base.py:76, where model_json_schema() feeds the tool schema pipeline. Compare the TypeScript SDK's dereferenceLocalRefs approach with the stated Go SDK precedent. Done means local $ref/$defs are inlined for tool schemas and cycles produce an error.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100