mcp-server-builder

# MCP Server Builder Build production-ready MCP servers with proper tool schemas, resources, and transport configuration. ## Quick Start ### Python (FastMCP) ```python from mcp.server.fastmcp import FastMCP mcp = FastMCP("my-server") @mcp.tool() async def greet(name: str) -> str: """Greet someone by name.""" return f"Hello, {name}!" if __name__ == "__main__": mcp.run() ``` ### JavaScript ```javascript import { Server } from "@modelcontextprotocol/sdk/server/index.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; const server = new Server({ name: "my-server", version: "1.0.0" }, { capabilities: { tools: {} } }); server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [{ name: "greet", description: "Greet someone", inputSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] } }] })); server.setRequestHandler(CallToolRequestSchema, async (request) => { if (request.params.name === "greet") { return { content: [{ type: "text", text: `Hello, ${request.params.arguments.name}!` }] }; } }); const transport = new StdioServerTransport(); await server.connect(transport); ``` ## Language Selection | Criterion | Python (FastMCP) | JavaScript/TypeScript | |-----------|------------------|----------------------| | Rapid prototyping | Best | Good | | Type safety | Via Pydantic | Native (TS) | | Async I/O | Native | Native | | Package ecosystem | pip/uv | npm | | Production deploy | Container Apps | Container Apps | ## Project Structure ### Python ``` my-mcp/ ├── pyproject.toml ├── src/ │ └── my_mcp/ │ ├── __init__.py │ ├── server.py # FastMCP instance │ └── tools/ # Tool implementations ├── data/ # Persistent storage └── .env.example ``` ### JavaScript/TypeScript ``` my-mcp/ ├── package.json ├── src/ │ ├── index.js # Server entry │ └── tools/ # Tool handlers ├── data/ # Persistent storage └── .env.example ``` ## Tool Patterns ### Structured Output (Python) ```python from pydantic import BaseModel, Field class SearchResult(BaseModel): id: str title: str score: float = Field(ge=0, le=1) @mcp.tool() async def search(query: str, limit: int = 10) -> list[SearchResult]: """Search documents by query.""" # Implementation... return [SearchResult(id="1", title="Result", score=0.95)] ``` ### Context for Logging (Python) ```python from mcp.server.fastmcp import Context @mcp.tool() async def process(data: str, ctx: Context) -> str: """Process data with progress reporting.""" await ctx.info(f"Processing {len(data)} chars") await ctx.report_progress(0, 100, "Starting...") # Work... await ctx.report_progress(100, 100, "Done") return result ``` ### Resources (Python) ```python @mcp.resource("memory://overview") async def memory_overview() -> str: """Current memory state summary.""" return json.dumps({"total": 100, "active": 85}) @mcp.resource("file://{path}") # Dynamic URI template async def read_file(path: str) -> str: """Read file contents.""" return Path(path).read_text() ``` ## Transport Configuration ### Stdio (Local - Claude Desktop) **Python**: `mcp.run()` (default) **JavaScript**: `new StdioServerTransport()` **Claude Desktop config** (`claude_desktop_config.json`): ```json { "mcpServers": { "my-server": { "command": "python", "args": ["-m", "my_mcp.server"] } } } ``` ### HTTP (Remote - Azure/Cloud) **Python**: ```python mcp.run(transport="streamable-http", host="0.0.0.0", port=8000) ``` **For ASGI mounting**: ```python app = mcp.streamable_http_app() # Mount to FastAPI/Starlette ``` ## Testing ### MCP Inspector ```bash # Python uv run mcp dev server.py # JavaScript npx @modelcontextprotocol/inspector node src/index.js ``` Opens `http://localhost:6274` for interactive testing. ### Programmatic Testing ```python import pytest from my_mcp.server import mcp @pytest.mark.asyncio async def test_greet(): result = await mcp.call_tool("greet", {"name": "World"}) assert "Hello, World" in result ``` ## Common Patterns ### Memory/CRUD Server See `references/memory-patterns.md` for episodic/semantic memory implementations. ### API Wrapper Server See `references/api-patterns.md` for wrapping external APIs as MCP tools. ### File Processing Server See `references/file-patterns.md` for document processing workflows. ## Checklist - [ ] Tools return `content: [{ type: "text", text: ... }]` format - [ ] All logging uses stderr (`console.error` in JS, `ctx.info` in Python) - [ ] Docstrings describe tool purpose (become protocol descriptions) - [ ] Type hints drive schema generation - [ ] Environment variables for secrets (never hardcoded) - [ ] `.env.example` documents required config - [ ] Test with MCP Inspector before Claude integration