{"id":11273,"library":"mcp-framework","title":"MCP Framework","description":"MCP-Framework is a TypeScript-first development framework designed for building Model Context Protocol (MCP) servers with reduced boilerplate compared to the official SDK. Currently at version 0.2.22, the package maintains a rapid release cadence, with multiple minor versions published frequently, indicating active and ongoing development towards its 1.0 stable release. Key differentiators include CLI scaffolding for quick project setup, an elegant class-based approach for defining tools, resources, and prompts, and integrated Zod validation for schemas. It offers built-in authentication mechanisms (JWT, API Key, OAuth 2.1) and supports multiple transports like stdio, SSE, and HTTP Stream, with explicit support for serverless environments like AWS Lambda. The framework focuses on automatic discovery and loading of server components, providing full type inference and simplifying complex AI agent integrations.","status":"active","version":"0.2.22","language":"javascript","source_language":"en","source_url":"https://github.com/QuantGeekDev/mcp-framework","tags":["javascript","mcp","claude","anthropic","ai","framework","tools","modelcontextprotocol","model","typescript"],"install":[{"cmd":"npm install mcp-framework","lang":"bash","label":"npm"},{"cmd":"yarn add mcp-framework","lang":"bash","label":"yarn"},{"cmd":"pnpm add mcp-framework","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core SDK that MCP-Framework builds upon for Model Context Protocol interactions, providing the underlying protocol implementation.","package":"@modelcontextprotocol/sdk","optional":false},{"reason":"Used extensively for defining and validating schemas for tool inputs, outputs, and other data structures, ensuring robust type safety and data integrity.","package":"zod","optional":false}],"imports":[{"note":"The primary class for instantiating and configuring your MCP server. MCP-Framework is a TypeScript-first, modern Node.js framework primarily designed for ES Modules.","wrong":"const { McpServer } = require('mcp-framework')","symbol":"McpServer","correct":"import { McpServer } from 'mcp-framework'"},{"note":"The `Tool` base class for defining individual tools and the `@tool` decorator for attaching metadata (name, description, schemas). These core components are provided by the `@mcp-framework/core` sub-package.","wrong":"import Tool from 'mcp-framework/tool'","symbol":"Tool, tool","correct":"import { Tool, tool } from '@mcp-framework/core'"},{"note":"Utility function for adapting an MCP server instance to an AWS Lambda handler, facilitating deployment in serverless environments.","symbol":"createLambdaHandler","correct":"import { createLambdaHandler } from 'mcp-framework'"}],"quickstart":{"code":"npm install -g mcp-framework\n\n# Create a new MCP server project (default uses stdio transport)\nmcp create my-mcp-server\n\n# Navigate to your project directory\ncd my-mcp-server\n\n# Install project dependencies\nnpm install\n\n# Add a new tool to your project\nmcp add tool price-fetcher\n\n# Open src/tools/price-fetcher.ts and define your tool logic using Zod for schema validation:\n// import { Tool, tool } from '@mcp-framework/core';\n// import { z } from 'zod';\n//\n// @tool({\n//   name: 'fetchStockPrice',\n//   description: 'Fetches the current stock price for a given ticker symbol.',\n//   inputSchema: z.object({\n//     ticker: z.string().describe('The stock ticker symbol (e.g., AAPL).'),\n//   }),\n//   outputSchema: z.object({\n//     price: z.number().describe('The current stock price.'),\n//     currency: z.string().describe('The currency of the price.'),\n//   }),\n// })\n// export class PriceFetcherTool extends Tool<typeof PriceFetcherTool> {\n//   async execute({ ticker }: z.infer<typeof PriceFetcherTool.inputSchema>) {\n//     // In a real application, this would call an external API\n//     console.log(`Fetching price for ${ticker}...`);\n//     const price = Math.random() * 1000 + 10;\n//     return { price: parseFloat(price.toFixed(2)), currency: 'USD' };\n//   }\n// }\n\n# Build and run your server\nnpm run build\nnpm start\n","lang":"typescript","description":"Demonstrates how to install the global CLI, scaffold a new MCP server project, install dependencies, add a new class-based tool using the `@tool` decorator and Zod schemas, and then build and run the server."},"warnings":[{"fix":"Always pin exact versions (e.g., `\"mcp-framework\": \"0.2.22\"`) rather than using ranges (e.g., `^0.2.0`) to avoid unexpected behavior from new releases. Review release notes for each update to identify any necessary migration steps.","message":"The package is currently in a 0.x.x version series (0.2.22), indicating that the API may not yet be stable. While frequent updates are provided, users should be prepared for potential breaking changes between minor versions as the project evolves towards a 1.0 release.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"After creating a project with `--http --cors`, manually review and restrict the CORS `allowedOrigin` configuration in your server's entry point (e.g., `index.ts`) to only trusted domains or specific origins before deploying to production.","message":"When using `mcp create` with the `--http` and `--cors` flags for HTTP transport, the server defaults to setting `Access-Control-Allow-Origin: *`. This wildcard CORS policy is suitable for development but is a significant security risk in production environments as it allows any domain to make cross-origin requests.","severity":"gotcha","affected_versions":">=0.2.20"},{"fix":"Ensure that all Zod schemas for tool inputs and outputs have meaningful `.describe()` calls, providing clear explanations of each field's purpose. Address any validation errors reported during `npm run build` or `mcp validate` to ensure your tools are correctly exposed to AI agents.","message":"The framework includes comprehensive tool validation, which runs automatically during `npm run build` and can be run standalone via `mcp validate`. Skipping this validation (`MCP_SKIP_TOOL_VALIDATION=true`) is not recommended as it can lead to improperly documented or functionally incorrect tools, hindering AI agent interaction and potentially causing runtime errors.","severity":"gotcha","affected_versions":">=0.2.19"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Modify the Zod schema definition for the specified tool to include a `.describe()` call for every field, e.g., `z.string().describe('A description of what this field represents.')`.","cause":"A Zod schema property (e.g., in `inputSchema` or `outputSchema`) within a class-based tool lacks a `.describe('Your description here')` call, which is required for proper tool documentation and AI agent understanding.","error":"Error: Tool validation failed: Missing description for field 'fieldName' in tool 'toolName'."},{"fix":"Ensure your Node.js project is configured for ES Modules (by adding `\"type\": \"module\"` to `package.json` or using `.mjs` file extensions) and exclusively uses `import ... from 'mcp-framework'` syntax. If sticking with CommonJS, ensure compatibility or use an older version if available.","cause":"Attempting to import `mcp-framework` or its sub-packages using CommonJS `require()` syntax in a project that is configured for ES Modules, or trying to import an ESM-only module into a CommonJS environment.","error":"ERR_REQUIRE_ESM: require() of ES Module ... Not supported"}],"ecosystem":"npm"}