MCP Kit MCP server
Commit Nov 7, 2026Build spec-compliant MCP servers quickly using Python type hints to automatically generate JSON Schemas for tools, resources, and prompts.
Also known as aiplusplus360/mcp-server-kit
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 7, 2026
- License
- MIT
What is MCP Kit MCP?
MCP Kit builds spec-compliant MCP servers quickly using Python type hints to automatically generate JSON Schemas for tools, resources, and prompts.
Summary generated from the project's README
Automated checks
Ran Nov 16, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableaiplusplus360/mcp-server-kit is public and reachablegithub.com/aiplusplus360/mcp-server-kit ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-07github.com/aiplusplus360/mcp-server-kit ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmcp-server-kit
Write a correct MCP server in a few lines. Typed tools, JSON Schema generated from your type hints, JSON-RPC 2.0 over stdio — no dependencies, no framework.
from mcpserver import Server, StdioTransport
server = Server("demo", "0.1.0")
@server.tool
def add(a: int, b: int) -> int:
"""Add two integers and return the sum."""
return a + b
StdioTransport(server).serve_forever()
That is a complete, spec-compliant MCP server. The inputSchema is derived from a: int, b: int; the description comes from the docstring.
$ mcp-server-kit describe add
{
"name": "add",
"description": "Add two integers and return the sum.",
"inputSchema": {
"type": "object",
"properties": { "a": { "type": "integer" }, "b": { "type": "integer" } },
"required": [ "a", "b" ]
}
}
Why this exists
The MCP spec is short and the failure modes are subtle. Writing a server from scratch means getting all of these right, and each one breaks a real client in a way that is hard to trace:
| Footgun | What happens |
|---|---|
| Replying to a notification | Client hangs waiting for a real response |
Coercing "1" to 1 |
Request correlation breaks silently |
| Returning a JSON-RPC error for a tool failure | Client retries an expected failure forever |
A print() inside a tool |
Corrupts the stdout wire; parse error points nowhere near the cause |
Hand-written inputSchema |
Drifts from the function; client sends arguments the server rejects |
This library handles all five, and each one has a test that fails if it regresses.
Install
No dependencies.
pip install git+https://github.com/aiplusplus360/mcp-server-kit
Usage
Tools
@server.tool
def search(query: str, limit: int = 10, tags: list[str] | None = None) -> str:
"""Search the index.
The docstring becomes the tool description the model reads.
"""
return f"results for {query}"
Schema is generated from the annotations: limit is optional with a default, tags accepts null, query is required.
Resources
@server.resource("app://config", mime_type="application/json")
def config() -> str:
"""Server configuration, readable by the client."""
return json.dumps({"region": "eu-west-1"})
Prompts
@server.prompt("review", description="Ask for a code review")
def review(language: str = "python") -> str:
return f"Review this {language} code for correctness and clarity."
Debugging without a client
mcp-server-kit list # tool catalogue
mcp-server-kit describe add # generated JSON Schema
mcp-server-kit call add --args '{"a":19,"b":23}' # invoke directly
mcp-server-kit serve # run the demo server on stdio
describe is the useful one: the schema is generated, so looking at it is how you confirm the generation is right.
Protocol behaviour
Verified against a real stdio exchange:
→ initialize ← protocolVersion, capabilities, serverInfo
→ notifications/initialized (no response — correct)
→ tools/list ← tools with generated inputSchema
→ tools/call ← content blocks, isError absent on success
→ nope/nope ← {"code": -32601, "message": "method not found"}
| Situation | Response |
|---|---|
| Successful tool | result: {content: [...], } |
| Tool raises | result: {content: [...], isError: true} |
| Bad arguments | result: {content: [...], isError: true} |
| Unknown tool | JSON-RPC error -32602 |
| Unknown method | JSON-RPC error -32601 |
| Malformed JSON | JSON-RPC error -32700, id null |
| Notification | no response at all |
The distinction that matters
A tool that fails returns a successful JSON-RPC response with isError: true. It does not return a JSON-RPC error.
That is not cosmetic. A JSON-RPC error means "the call did not happen" — clients treat it as infrastructure failure, retry, and alert. isError: true means "the call happened and the tool said no", which the model can read and correct. Returning the wrong one turns every expected failure — file not found, invalid input, quota exceeded — into a retry storm.
Reserved for real transport problems: unknown method, malformed request, unknown tool.
Type support
| Annotation | Schema |
|---|---|
str int float bool |
string integer number boolean |
Optional[T] |
type: [T, "null"], not required |
list[T] |
array with items |
dict[str, T] |
object with additionalProperties |
Literal["a","b"] |
enum |
Enum subclass |
enum of values |
@dataclass |
nested object with properties |
| anything else | {} — permissive, never blocks startup |
bool is emitted as boolean, not integer, despite subclassing int in Python — and true is rejected for an integer parameter rather than coerced to 1. Both are tested.
Design notes
stdout is the wire. During a tool call, stdout is captured and redirected to stderr. A tool that calls print() would otherwise inject a non-JSON line into the protocol stream, and the client's error would point at the JSON parser rather than at your tool.
if request_id: is wrong. An id of 0 or "" is falsy but perfectly valid. Notifications are identified by the absence of the key, not by falsiness of its value. Both are tested.
Version negotiation is lenient. An unknown protocolVersion gets the server's version rather than a rejection — refusing outright breaks clients that would have worked fine.
A batch of notifications produces no response at all, not an empty array. Clients that receive [] treat it as a protocol violation.
Errors never kill the loop. Any exception in dispatch becomes an error response and the server keeps reading. A stdio server that exits on one bad message takes the whole session down.
*args / **kwargs are rejected at registration, not at call time, because MCP passes arguments by name and a variadic handler has no discoverable schema.
Development
python -m unittest discover -s tests -v # 54 tests
CI runs on Python 3.9, 3.11 and 3.13, and drives a real JSON-RPC session through the stdio transport — asserting that the notification produced no response and that every output line parses as JSON.
License
MCP Kit MCP questions
How do I generate the JSON Schema for my tools?
The library automatically derives the inputSchema from your Python type hints and the tool description from your function's docstring.
Does this library have any dependencies?
No, the library is designed to be zero-dependency.
How can I test my server without an MCP client?
You can use the built-in CLI commands to list tools, describe schemas, call tools directly, or run the server on stdio.
What happens if my tool raises an error?
The server returns a successful JSON-RPC response with isError: true, allowing the model to read and correct the error rather than triggering a client-side retry storm.