How instructa/mcp-starter works
Main Components
a. CLI Entrypoint
• Location: bin/cli.mjs
• Responsibility: Parses flags (--stdio, --http, --sse, --port, --endpoint), boots the server.
b. Transport Layer Adapters
• stdio adapter (default)
• HTTP/Streamable HTTP adapter (--http)
• SSE adapter (--sse, deprecated)
• Location: instantiated in src/server.ts based on CLI args.
c. MCP Server Core
• Location: src/server.ts + src/index.ts
• Responsibility: Implements the MCP protocol loop: receive request, parse, route to tools, send response.
d. Tool Registry & Execution
• Location: src/tools/*.ts (e.g., mytool.ts)
• Responsibility: Define one or more “tools” that the server can invoke.
e. Shared Types & Utilities
• Location: src/types.ts, src/utils.ts
• Responsibility: Type definitions for MCP messages, helper functions (e.g., JSON parsing, error handling).
f. External Clients
• Examples: Cursor AI, Claude GI, any MCP-compatible client
• Interaction: Connect to server via chosen transport, send/receive MCP messages.
g. Configuration & Metadata
• .cursor/mcp.json: example client config
• package.json, build.config.ts, vite.config.ts: build and publish settings
Relationships and Data Flows
• CLI Entrypoint → parses flags → selects Transport Adapter
• Transport Adapter ↔ (listens for) MCP Client requests
• Transport Adapter → forwards raw message → MCP Server Core
• MCP Server Core → parses message → dispatches to appropriate Tool
• Tool → processes logic → returns result to Core
• MCP Server Core → serializes result → hands back to Transport
• Transport Adapter → sends message → External Client
Architectural Patterns
• Modular Transport Strategy: Each transport (stdio, HTTP, SSE) implements the same interface—swapable at startup.
• Plugin-style Tools: You drop new .ts tool files into src/tools and register them in the core.
• Single Responsibility & Separation of Concerns:
• CLI: argument handling
• Transports: I/O concerns
• Core: protocol logic
• Tools: domain logic
• Utils/Types: shared helpers
Technologies
• Node.js + TypeScript (ts-node or build via Vite)
• MCP Protocol standard
• Vite / ESBuild for bundling (vite.config.ts, build.config.ts)
• Testing with Vitest/Jest (tests/server.test.ts)
• pnpm (lockfile present), Docker (optional containerization)
Detailed Elements to Capture
• CLI flags and how they instantiate the correct transport
• Configuration file .cursor/mcp.json as a bootstrap for local development
• Test harness (tests/server.test.ts) to illustrate quality assurance
Putting It All Together:
– Off to the side, place “Shared Types / Utils” as a resource that Core and Tools both import.