{"id":12689,"library":"xmcp","title":"xmcp: Model Context Protocol Framework","description":"xmcp is a TypeScript-first framework designed for building and deploying Model Context Protocol (MCP) servers. It aims to simplify the development experience for creating powerful tools within the MCP ecosystem, providing features like file system routing for automatic tool and prompt registration, hot reloading for rapid development, and a robust middleware system for authentication and custom logic. Currently at version 0.6.7, the project maintains an active development pace with frequent minor and patch releases (often weekly or bi-weekly), incorporating new features, security updates, and performance improvements. Key differentiators include its focus on developer experience, support for various deployment targets like Vercel and Cloudflare, and an 'elicit' mechanism within tool handlers for requesting structured user input.","status":"active","version":"0.6.7","language":"javascript","source_language":"en","source_url":"https://github.com/basementstudio/xmcp","tags":["javascript","mcp","modelcontextprotocol","http","stdio","typescript"],"install":[{"cmd":"npm install xmcp","lang":"bash","label":"npm"},{"cmd":"yarn add xmcp","lang":"bash","label":"yarn"},{"cmd":"pnpm add xmcp","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for UI-related components or adapters.","package":"react","optional":false},{"reason":"Peer dependency for UI-related components or adapters.","package":"react-dom","optional":false},{"reason":"Peer dependency for schema validation and type inference, commonly used for input/output schemas.","package":"zod","optional":false}],"imports":[{"note":"Used for defining the main xmcp server configuration. Primarily an ESM package, CommonJS `require` is not supported for core modules.","wrong":"const { defineConfig } = require('xmcp')","symbol":"defineConfig","correct":"import { defineConfig } from 'xmcp'"},{"note":"This is a TypeScript type representing the context object ('extra' in tool handlers) that provides utilities like `elicit`. Use `import type` for type-only imports to prevent bundling issues.","wrong":"import { ToolHandlerContext } from 'xmcp'","symbol":"ToolHandlerContext","correct":"import { type ToolHandlerContext } from 'xmcp'"},{"note":"`elicit` is a method available on the `extra` (ToolHandlerContext) object passed to tool handler functions, not a direct export from the `xmcp` package.","wrong":"import { elicit } from 'xmcp'","symbol":"elicit","correct":"const result = await extra.elicit({...});"}],"quickstart":{"code":"// First, initialize a new xmcp project:\n// npx create-xmcp-app@latest my-xmcp-app\n// cd my-xmcp-app\n\n// Then, create a tool file within your project, for example, at src/tools/deploy.ts.\n// xmcp automatically registers tools based on file system routing.\n\nimport { type ToolHandlerContext } from 'xmcp';\n\nexport default async function (\n  _args: Record<string, any>, // Arguments received by the tool\n  extra: ToolHandlerContext  // Context object providing utilities\n) {\n  console.log(\"Deployment tool invoked. Awaiting user input...\");\n\n  const result = await extra.elicit({\n    message: \"Please choose deployment parameters:\",\n    requestedSchema: {\n      type: \"object\",\n      properties: {\n        environment: {\n          type: \"string\",\n          title: \"Deployment Environment\",\n          enum: [\"staging\", \"production\"],\n          description: \"Target environment for deployment.\"\n        },\n        confirmAction: {\n          type: \"boolean\",\n          title: \"Confirm Deployment\",\n          description: \"Are you sure you want to proceed with deployment?\",\n          default: false\n        }\n      },\n      required: [\"environment\", \"confirmAction\"],\n    },\n  });\n\n  if (result.action !== \"accept\" || !result.content || !result.content.confirmAction) {\n    return \"Deployment action cancelled or not confirmed by the user.\";\n  }\n\n  const { environment } = result.content;\n  console.log(`Initiating deployment to ${environment}...`);\n  // In a real application, replace this with actual deployment logic\n  await new Promise(resolve => setTimeout(resolve, 3000)); // Simulate work\n\n  return `Deployment to ${environment} completed successfully!`;\n}\n\n// To run this tool, start your xmcp development server (e.g., `npm run dev`).\n// Then, interact with your MCP server via a compatible client or interface\n// to invoke the 'deploy' tool, which will trigger the elicitation flow.\n","lang":"typescript","description":"Initializes an xmcp project and demonstrates defining a tool that uses the `extra.elicit` function to prompt the user for structured input before proceeding with a simulated deployment."},"warnings":[{"fix":"Migrate to supported authentication plugins like `@xmcp-dev/auth0`, `@xmcp-dev/workos`, or `@xmcp-dev/clerk`, or implement custom authentication middleware.","message":"The experimental OAuth configuration and proxy were removed in version 0.6.0. Projects relying on these features will require refactoring to use alternative authentication plugins (e.g., Auth0, WorkOS, Clerk) or custom middleware.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Update your OAuth client configurations to use `audience` instead of `baseurl` when interacting with the xmcp OAuth authorization server.","message":"As of v0.6.0, the `resource` parameter for the OAuth authorization server changed from `baseurl` to `audience`. This change affects how OAuth clients should be configured.","severity":"breaking","affected_versions":">=0.6.1"},{"fix":"Ensure your project's `package.json` explicitly lists and installs compatible versions of `react`, `react-dom`, and `zod` that satisfy xmcp's peer dependency requirements.","message":"xmcp relies on peer dependencies `react`, `react-dom` (both `>=19.0.0`), and `zod` (`^3.25.76 || ^4.0.0`). Mismatched versions can lead to runtime errors or unexpected behavior.","severity":"gotcha","affected_versions":">=0.5.8"},{"fix":"Upgrade to xmcp v0.6.7 or newer to benefit from improved error handling. Ensure all tool files (`src/tools/*`) are valid TypeScript/JavaScript modules with a default export.","message":"Prior to v0.6.7, error handling for empty or malformed tool files was less robust, potentially leading to crashes or silent failures during server startup or tool invocation.","severity":"gotcha","affected_versions":"<0.6.7"},{"fix":"It is strongly recommended to update to the latest stable version of xmcp immediately to incorporate all critical security patches.","message":"Multiple security updates were released across versions 0.6.2 and 0.6.5. Running older versions exposes projects to known vulnerabilities.","severity":"breaking","affected_versions":"<0.6.6"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the required peer dependencies with `npm install react react-dom zod` and ensure their versions satisfy xmcp's peer dependency ranges (e.g., `react@'>=19.0.0'`, `zod@'^3.25.76 || ^4.0.0'`).","cause":"A peer dependency (e.g., React or Zod) is missing or has a version incompatible with xmcp's requirements.","error":"Error: Cannot find module 'react' or 'zod'"},{"fix":"Ensure your tool handler function is defined as `export default async function (_args, extra: ToolHandlerContext) { ... }` and that `extra` is correctly named and typed.","cause":"The `extra` object, which contains the `elicit` function, was not correctly destructured or provided to the tool handler, or the handler signature is incorrect.","error":"TypeError: Cannot read properties of undefined (reading 'elicit')"},{"fix":"Add `export default async function (...) { ... }` to your tool file, ensuring it exports a valid asynchronous function.","cause":"xmcp's file system routing requires each tool file to have a default export, which is treated as the tool handler function.","error":"Error: Tool file 'src/tools/my-tool.ts' must have a default export."},{"fix":"This is expected behavior. When using `extra.elicit()`, always check `result.action` and `result.content` to handle user cancellations or incomplete input gracefully. Provide clear feedback to the user on why an action was not taken.","cause":"The `elicit` function was invoked, but the user either explicitly declined the prompt (`result.action !== 'accept'`) or did not provide the necessary confirmations based on the `requestedSchema`.","error":"Deployment cancelled or not confirmed."}],"ecosystem":"npm"}