MCP Framework

Common errors

• Error: Tool validation failed: Missing description for field 'fieldName' in tool 'toolName'.

  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.
  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.')`.

• ERR_REQUIRE_ESM: require() of ES Module ... Not supported

  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.
  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.

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install mcp-framework npm
• yarn add mcp-framework yarn
• pnpm add mcp-framework pnpm

Imports

• McpServer
  wrong:

  const { McpServer } = require('mcp-framework')

  correct:

  import { McpServer } from 'mcp-framework'

  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.
• Tool, tool
  wrong:

  import Tool from 'mcp-framework/tool'

  correct:

  import { Tool, tool } from '@mcp-framework/core'

  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.
• createLambdaHandler

  import { createLambdaHandler } from 'mcp-framework'

  Utility function for adapting an MCP server instance to an AWS Lambda handler, facilitating deployment in serverless environments.

Quickstart

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.

npm install -g mcp-framework

# Create a new MCP server project (default uses stdio transport)
mcp create my-mcp-server

# Navigate to your project directory
cd my-mcp-server

# Install project dependencies
npm install

# Add a new tool to your project
mcp add tool price-fetcher

# Open src/tools/price-fetcher.ts and define your tool logic using Zod for schema validation:
// import { Tool, tool } from '@mcp-framework/core';
// import { z } from 'zod';
//
// @tool({
//   name: 'fetchStockPrice',
//   description: 'Fetches the current stock price for a given ticker symbol.',
//   inputSchema: z.object({
//     ticker: z.string().describe('The stock ticker symbol (e.g., AAPL).'),
//   }),
//   outputSchema: z.object({
//     price: z.number().describe('The current stock price.'),
//     currency: z.string().describe('The currency of the price.'),
//   }),
// })
// export class PriceFetcherTool extends Tool<typeof PriceFetcherTool> {
//   async execute({ ticker }: z.infer<typeof PriceFetcherTool.inputSchema>) {
//     // In a real application, this would call an external API
//     console.log(`Fetching price for ${ticker}...`);
//     const price = Math.random() * 1000 + 10;
//     return { price: parseFloat(price.toFixed(2)), currency: 'USD' };
//   }
// }

# Build and run your server
npm run build
npm start