{"_id":"@au-re/mcp-sdk","name":"@au-re/mcp-sdk","dist-tags":{"latest":"1.4.1"},"versions":{"1.4.1":{"name":"@au-re/mcp-sdk","version":"1.4.1","description":"Model Context Protocol implementation for TypeScript","license":"MIT","author":{"name":"Anthropic, PBC","url":"https://anthropic.com"},"homepage":"https://modelcontextprotocol.io","bugs":{"url":"https://github.com/modelcontextprotocol/typescript-sdk/issues"},"type":"module","repository":{"type":"git","url":"git+https://github.com/modelcontextprotocol/typescript-sdk.git"},"engines":{"node":">=18"},"keywords":["modelcontextprotocol","mcp"],"exports":{"./*":{"import":"./dist/esm/*","require":"./dist/cjs/*"}},"typesVersions":{"*":{"*":["./dist/esm/*"]}},"scripts":{"build":"npm run build:esm && npm run build:cjs","build:esm":"tsc -p tsconfig.prod.json && echo '{\"type\": \"module\"}' > dist/esm/package.json","build:cjs":"tsc -p tsconfig.cjs.json && echo '{\"type\": \"commonjs\"}' > dist/cjs/package.json","prepack":"npm run build:esm && npm run build:cjs","lint":"eslint src/","test":"jest","start":"npm run server","server":"tsx watch --clear-screen=false src/cli.ts server","client":"tsx src/cli.ts client"},"dependencies":{"content-type":"^1.0.5","eventsource":"^3.0.2","raw-body":"^3.0.0","zod":"^3.23.8","zod-to-json-schema":"^3.24.1"},"devDependencies":{"@eslint/js":"^9.8.0","@types/content-type":"^1.1.8","@types/eslint__js":"^8.42.3","@types/eventsource":"^1.1.15","@types/express":"^4.17.21","@types/jest":"^29.5.12","@types/node":"^22.0.2","@types/ws":"^8.5.12","eslint":"^9.8.0","express":"^4.19.2","jest":"^29.7.0","ts-jest":"^29.2.4","tsx":"^4.16.5","typescript":"^5.5.4","typescript-eslint":"^8.0.0","ws":"^8.18.0"},"resolutions":{"strip-ansi":"6.0.1"},"_id":"@au-re/mcp-sdk@1.4.1","gitHead":"ac58bd4cfa0c4a77ba68cf22a63af4c5c08e6f00","_nodeVersion":"22.11.0","_npmVersion":"11.1.0","dist":{"integrity":"sha512-jRc+7A+5eq60XW3pYnf657c3O/UxkNERFWtLbz0Vb6+FpBbb6nu0QJnChaVo3h7efjVTp5ll0Ta4bEpdK9Deng==","shasum":"d5d8d452a5acceccb2b3aeeb9e144cd27a5b277c","tarball":"https://registry.npmjs.org/@au-re/mcp-sdk/-/mcp-sdk-1.4.1.tgz","fileCount":133,"unpackedSize":3353094,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBvoXBFn6X14Y8t3Sc/XqPdcRIq0TnKMi+sDUbpixsugAiEAnmBuFOlXwuhHKfKVjbbHFH62st6G29LXwZ0k94wPH1M="}]},"_npmUser":{"name":"au-re","email":"aurelienhf@hotmail.com"},"directories":{},"maintainers":[{"name":"au-re","email":"aurelienhf@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-sdk_1.4.1_1739209468601_0.367635263439513"},"_hasShrinkwrap":false}},"time":{"created":"2025-02-10T17:44:28.217Z","1.4.1":"2025-02-10T17:44:29.118Z","modified":"2025-02-10T17:44:29.368Z"},"maintainers":[{"name":"au-re","email":"aurelienhf@hotmail.com"}],"description":"Model Context Protocol implementation for TypeScript","homepage":"https://modelcontextprotocol.io","keywords":["modelcontextprotocol","mcp"],"repository":{"type":"git","url":"git+https://github.com/modelcontextprotocol/typescript-sdk.git"},"author":{"name":"Anthropic, PBC","url":"https://anthropic.com"},"bugs":{"url":"https://github.com/modelcontextprotocol/typescript-sdk/issues"},"license":"MIT","readme":"# MCP TypeScript SDK ![NPM Version](https://img.shields.io/npm/v/%40modelcontextprotocol%2Fsdk) ![MIT licensed](https://img.shields.io/npm/l/%40modelcontextprotocol%2Fsdk)\n\n## Table of Contents\n- [Overview](#overview)\n- [Installation](#installation)\n- [Quickstart](#quickstart)\n- [What is MCP?](#what-is-mcp)\n- [Core Concepts](#core-concepts)\n  - [Server](#server)\n  - [Resources](#resources)\n  - [Tools](#tools)\n  - [Prompts](#prompts)\n- [Running Your Server](#running-your-server)\n  - [stdio](#stdio)\n  - [HTTP with SSE](#http-with-sse)\n  - [Testing and Debugging](#testing-and-debugging)\n- [Examples](#examples)\n  - [Echo Server](#echo-server)\n  - [SQLite Explorer](#sqlite-explorer)\n- [Advanced Usage](#advanced-usage)\n  - [Low-Level Server](#low-level-server)\n  - [Writing MCP Clients](#writing-mcp-clients)\n  - [Server Capabilities](#server-capabilities)\n\n## Overview\n\nThe Model Context Protocol allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction. This TypeScript SDK implements the full MCP specification, making it easy to:\n\n- Build MCP clients that can connect to any MCP server\n- Create MCP servers that expose resources, prompts and tools\n- Use standard transports like stdio and SSE\n- Handle all MCP protocol messages and lifecycle events\n\n## Installation\n\n```bash\nnpm install @modelcontextprotocol/sdk\n```\n\n## Quick Start\n\nLet's create a simple MCP server that exposes a calculator tool and some data:\n\n```typescript\nimport { McpServer, ResourceTemplate } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport { z } from \"zod\";\n\n// Create an MCP server\nconst server = new McpServer({\n  name: \"Demo\",\n  version: \"1.0.0\"\n});\n\n// Add an addition tool\nserver.tool(\"add\",\n  { a: z.number(), b: z.number() },\n  async ({ a, b }) => ({\n    content: [{ type: \"text\", text: String(a + b) }]\n  })\n);\n\n// Add a dynamic greeting resource\nserver.resource(\n  \"greeting\",\n  new ResourceTemplate(\"greeting://{name}\", { list: undefined }),\n  async (uri, { name }) => ({\n    contents: [{\n      uri: uri.href,\n      text: `Hello, ${name}!`\n    }]\n  })\n);\n\n// Start receiving messages on stdin and sending messages on stdout\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n```\n\n## What is MCP?\n\nThe [Model Context Protocol (MCP)](https://modelcontextprotocol.io) lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. Think of it like a web API, but specifically designed for LLM interactions. MCP servers can:\n\n- Expose data through **Resources** (think of these sort of like GET endpoints; they are used to load information into the LLM's context)\n- Provide functionality through **Tools** (sort of like POST endpoints; they are used to execute code or otherwise produce a side effect)\n- Define interaction patterns through **Prompts** (reusable templates for LLM interactions)\n- And more!\n\n## Core Concepts\n\n### Server\n\nThe McpServer is your core interface to the MCP protocol. It handles connection management, protocol compliance, and message routing:\n\n```typescript\nconst server = new McpServer({\n  name: \"My App\",\n  version: \"1.0.0\"\n});\n```\n\n### Resources\n\nResources are how you expose data to LLMs. They're similar to GET endpoints in a REST API - they provide data but shouldn't perform significant computation or have side effects:\n\n```typescript\n// Static resource\nserver.resource(\n  \"config\",\n  \"config://app\",\n  async (uri) => ({\n    contents: [{\n      uri: uri.href,\n      text: \"App configuration here\"\n    }]\n  })\n);\n\n// Dynamic resource with parameters\nserver.resource(\n  \"user-profile\",\n  new ResourceTemplate(\"users://{userId}/profile\", { list: undefined }),\n  async (uri, { userId }) => ({\n    contents: [{\n      uri: uri.href,\n      text: `Profile data for user ${userId}`\n    }]\n  })\n);\n```\n\n### Tools\n\nTools let LLMs take actions through your server. Unlike resources, tools are expected to perform computation and have side effects:\n\n```typescript\n// Simple tool with parameters\nserver.tool(\n  \"calculate-bmi\",\n  {\n    weightKg: z.number(),\n    heightM: z.number()\n  },\n  async ({ weightKg, heightM }) => ({\n    content: [{\n      type: \"text\",\n      text: String(weightKg / (heightM * heightM))\n    }]\n  })\n);\n\n// Async tool with external API call\nserver.tool(\n  \"fetch-weather\",\n  { city: z.string() },\n  async ({ city }) => {\n    const response = await fetch(`https://api.weather.com/${city}`);\n    const data = await response.text();\n    return {\n      content: [{ type: \"text\", text: data }]\n    };\n  }\n);\n```\n\n### Prompts\n\nPrompts are reusable templates that help LLMs interact with your server effectively:\n\n```typescript\nserver.prompt(\n  \"review-code\",\n  { code: z.string() },\n  ({ code }) => ({\n    messages: [{\n      role: \"user\",\n      content: {\n        type: \"text\",\n        text: `Please review this code:\\n\\n${code}`\n      }\n    }]\n  })\n);\n```\n\n## Running Your Server\n\nMCP servers in TypeScript need to be connected to a transport to communicate with clients. How you start the server depends on the choice of transport:\n\n### stdio\n\nFor command-line tools and direct integrations:\n\n```typescript\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\n\nconst server = new McpServer({\n  name: \"example-server\",\n  version: \"1.0.0\"\n});\n\n// ... set up server resources, tools, and prompts ...\n\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n```\n\n### HTTP with SSE\n\nFor remote servers, start a web server with a Server-Sent Events (SSE) endpoint, and a separate endpoint for the client to send its messages to:\n\n```typescript\nimport express from \"express\";\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { SSEServerTransport } from \"@modelcontextprotocol/sdk/server/sse.js\";\n\nconst server = new McpServer({\n  name: \"example-server\",\n  version: \"1.0.0\"\n});\n\n// ... set up server resources, tools, and prompts ...\n\nconst app = express();\n\napp.get(\"/sse\", async (req, res) => {\n  const transport = new SSEServerTransport(\"/messages\", res);\n  await server.connect(transport);\n});\n\napp.post(\"/messages\", async (req, res) => {\n  // Note: to support multiple simultaneous connections, these messages will\n  // need to be routed to a specific matching transport. (This logic isn't\n  // implemented here, for simplicity.)\n  await transport.handlePostMessage(req, res);\n});\n\napp.listen(3001);\n```\n\n### Testing and Debugging\n\nTo test your server, you can use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector). See its README for more information.\n\n## Examples\n\n### Echo Server\n\nA simple server demonstrating resources, tools, and prompts:\n\n```typescript\nimport { McpServer, ResourceTemplate } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { z } from \"zod\";\n\nconst server = new McpServer({\n  name: \"Echo\",\n  version: \"1.0.0\"\n});\n\nserver.resource(\n  \"echo\",\n  new ResourceTemplate(\"echo://{message}\", { list: undefined }),\n  async (uri, { message }) => ({\n    contents: [{\n      uri: uri.href,\n      text: `Resource echo: ${message}`\n    }]\n  })\n);\n\nserver.tool(\n  \"echo\",\n  { message: z.string() },\n  async ({ message }) => ({\n    content: [{ type: \"text\", text: `Tool echo: ${message}` }]\n  })\n);\n\nserver.prompt(\n  \"echo\",\n  { message: z.string() },\n  ({ message }) => ({\n    messages: [{\n      role: \"user\",\n      content: {\n        type: \"text\",\n        text: `Please process this message: ${message}`\n      }\n    }]\n  })\n);\n```\n\n### SQLite Explorer\n\nA more complex example showing database integration:\n\n```typescript\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport sqlite3 from \"sqlite3\";\nimport { promisify } from \"util\";\nimport { z } from \"zod\";\n\nconst server = new McpServer({\n  name: \"SQLite Explorer\",\n  version: \"1.0.0\"\n});\n\n// Helper to create DB connection\nconst getDb = () => {\n  const db = new sqlite3.Database(\"database.db\");\n  return {\n    all: promisify<string, any[]>(db.all.bind(db)),\n    close: promisify(db.close.bind(db))\n  };\n};\n\nserver.resource(\n  \"schema\",\n  \"schema://main\",\n  async (uri) => {\n    const db = getDb();\n    try {\n      const tables = await db.all(\n        \"SELECT sql FROM sqlite_master WHERE type='table'\"\n      );\n      return {\n        contents: [{\n          uri: uri.href,\n          text: tables.map((t: {sql: string}) => t.sql).join(\"\\n\")\n        }]\n      };\n    } finally {\n      await db.close();\n    }\n  }\n);\n\nserver.tool(\n  \"query\",\n  { sql: z.string() },\n  async ({ sql }) => {\n    const db = getDb();\n    try {\n      const results = await db.all(sql);\n      return {\n        content: [{\n          type: \"text\",\n          text: JSON.stringify(results, null, 2)\n        }]\n      };\n    } catch (err: unknown) {\n      const error = err as Error;\n      return {\n        content: [{\n          type: \"text\",\n          text: `Error: ${error.message}`\n        }],\n        isError: true\n      };\n    } finally {\n      await db.close();\n    }\n  }\n);\n```\n\n## Advanced Usage\n\n### Low-Level Server\n\nFor more control, you can use the low-level Server class directly:\n\n```typescript\nimport { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport {\n  ListPromptsRequestSchema,\n  GetPromptRequestSchema\n} from \"@modelcontextprotocol/sdk/types.js\";\n\nconst server = new Server(\n  {\n    name: \"example-server\",\n    version: \"1.0.0\"\n  },\n  {\n    capabilities: {\n      prompts: {}\n    }\n  }\n);\n\nserver.setRequestHandler(ListPromptsRequestSchema, async () => {\n  return {\n    prompts: [{\n      name: \"example-prompt\",\n      description: \"An example prompt template\",\n      arguments: [{\n        name: \"arg1\",\n        description: \"Example argument\",\n        required: true\n      }]\n    }]\n  };\n});\n\nserver.setRequestHandler(GetPromptRequestSchema, async (request) => {\n  if (request.params.name !== \"example-prompt\") {\n    throw new Error(\"Unknown prompt\");\n  }\n  return {\n    description: \"Example prompt\",\n    messages: [{\n      role: \"user\",\n      content: {\n        type: \"text\",\n        text: \"Example prompt text\"\n      }\n    }]\n  };\n});\n\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n```\n\n### Writing MCP Clients\n\nThe SDK provides a high-level client interface:\n\n```typescript\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { StdioClientTransport } from \"@modelcontextprotocol/sdk/client/stdio.js\";\n\nconst transport = new StdioClientTransport({\n  command: \"node\",\n  args: [\"server.js\"]\n});\n\nconst client = new Client(\n  {\n    name: \"example-client\",\n    version: \"1.0.0\"\n  },\n  {\n    capabilities: {\n      prompts: {},\n      resources: {},\n      tools: {}\n    }\n  }\n);\n\nawait client.connect(transport);\n\n// List prompts\nconst prompts = await client.listPrompts();\n\n// Get a prompt\nconst prompt = await client.getPrompt(\"example-prompt\", {\n  arg1: \"value\"\n});\n\n// List resources\nconst resources = await client.listResources();\n\n// Read a resource\nconst resource = await client.readResource(\"file:///example.txt\");\n\n// Call a tool\nconst result = await client.callTool({\n  name: \"example-tool\",\n  arguments: {\n    arg1: \"value\"\n  }\n});\n```\n\n## Documentation\n\n- [Model Context Protocol documentation](https://modelcontextprotocol.io)\n- [MCP Specification](https://spec.modelcontextprotocol.io)\n- [Example Servers](https://github.com/modelcontextprotocol/servers)\n\n## Contributing\n\nIssues and pull requests are welcome on GitHub at https://github.com/modelcontextprotocol/typescript-sdk.\n\n## License\n\nThis project is licensed under the MIT License—see the [LICENSE](LICENSE) file for details.\n","readmeFilename":"README.md"}