simple

Simple MCP is a lightweight TypeScript library for creating MCP (Model Context Protocol) servers. It provides a minimal API to spin up an MCP server, register tools, define parameters with Zod validation, and run the server over stdio or other transports. You create a McpServer instance, register one or more tools with a name, a set of validated parameters, and an execute function that returns the MCP content to send back to clients. The library emphasizes type safety and easy integration with TypeScript, making it straightforward to build domain-specific tools that conform to the MCP specification. To run, you typically start the server with a transport type (stdio is shown in the examples) so it can communicate via standard input/output with the MCP runtime or orchestrator.

Using the library involves these core steps: install the package, create a McpServer instance with a server name, define and register tools (either via a simple object literal or via a class implementing McpTool), and finally start the server. Tools expose a name, a parameters object describing each argument with Zod validators, and an execute function that returns content (e.g., text, tables, or other structured content) in the MCP format. The TypeScript examples show a greet tool that accepts a name and returns a text greeting, illustrating how parameters are defined and how the response is shaped. The class-based example demonstrates how to implement tools as classes to leverage static typing and reusability across tools. The typical deployment pattern is to run the server as a node process in a container or directly in a Node environment where you can feed it the appropriate transport (stdio in the examples).

If you plan to build multiple tools, you can create a single server instance and register each tool with server.tool(toolOrInstance), then start the server with server.start({ transportType: 'stdio' }). The MCP server will handle validation using Zod schemas, ensuring inputs conform to the defined shapes before execution. While the README focuses on a simple greeting example, this library supports more complex tool definitions and parameter schemas, enabling robust MCP implementations.

Prerequisites:

• Node.js (14.x or newer) and npm or pnpm
• Basic TypeScript setup if you plan to write TypeScript tooling

Installation steps:

1. Install the MCP library from npm:

npm install simple-mcp

2. (Optional) If using TypeScript, ensure your tsconfig is set up for ESModuleInterop if needed and that module resolution supports node for imports.

3. Create a project file (e.g., src/server.ts) to initialize and run the MCP server as shown in the Quickstart examples.

4. Compile and run your server (depending on your setup, e.g., tsc && node dist/server.js or use ts-node in development).

5. If you plan to run in a container or via a process manager, ensure the entrypoint appropriately starts the server and wires the stdio transport (or another transport you configure).

Notes:

• The library relies on Zod for parameter validation, so install zod if you plan to define complex schemas.
• For production deployments, consider how you expose tooling APIs, logging, and error handling to MCP clients.

Tips and notes:

• Transport: The examples use transportType: 'stdio'. You can adapt to other transports as supported by your runtime or MCP host.
• Validation: Leverage Zod schemas to validate tool parameters before execution; this provides strong type-safety and early error reporting.
• Tools: You can define tools inline when registering with server.tool({ ... }) or implement a class that extends McpTool for more structured code and reuse.
• Type safety: The library emphasizes TypeScript integration. Use zod.infer and generic tool parameter types to maximize type checking.
• Error handling: Ensure your execute functions properly handle errors and return MCP-compliant content structures to avoid runtime failures.
• Deployment: Since there is no single executable like a CLI, your deployment strategy will typically bundle your Node project and run it as a Node process with the appropriate entry script.