mcp-framework

library0.1.51jsnpmunverified

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.

llm-agents web-framework auth-security aws

npm install mcp-framework

github ↗package ↗

INSTALL

IMPORT

SIG · MCP-FRAMEWORK

mcp-framework

llm-agentsjavascriptv0.1.51

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

McpServer

✓ import { McpServer } from 'mcp-framework'

✗ const { McpServer } = require('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

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

✗ import Tool from 'mcp-framework/tool'

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.

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

mcp --version

Debug

Known issues

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

affects: >=0.0.1

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

affects: >=0.2.20

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

affects: >=0.2.19

Errors

Common errors & fixes

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

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

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.

Upgrade

Version history

0.1.51latest on npm

Audit

Dependencies

@modelcontextprotocol/sdkrequiredCore SDK that MCP-Framework builds upon for Model Context Protocol interactions, providing the underlying protocol implementation.

zodrequiredUsed extensively for defining and validating schemas for tool inputs, outputs, and other data structures, ensuring robust type safety and data integrity.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/QuantGeekDev/mcp-framework ↗

packagehttps://www.npmjs.com/package/mcp-framework ↗