xmcp

Automatically discovers and registers MCP tools, prompts, and resources by scanning the file system directory structure, eliminating manual route registration. The framework uses a convention-over-configuration approach where files in designated directories (e.g., src/tools/, src/prompts/, src/resources/) are automatically compiled into MCP-compatible handlers without explicit routing declarations. This pattern reduces boilerplate and enables hot-reloading during development by watching file changes and recompiling affected routes.

Monitors source files for changes and automatically recompiles and reloads MCP handlers without requiring server restart, enabling rapid iteration during development. The framework watches designated directories (tools, prompts, resources) and triggers incremental compilation via webpack, then hot-swaps handler modules in the running process. This is implemented through a development-mode transport layer that intercepts file system events and coordinates recompilation with the MCP server lifecycle.

Maintains a collection of 20+ example projects (in examples/ directory) demonstrating xmcp patterns, middleware implementations, transport configurations, and integrations with external services. Each example is a complete, runnable project that showcases specific xmcp features (e.g., authentication, custom middleware, serverless deployment). Examples serve as both learning resources and starting points for developers building similar applications.

Provides a plugin architecture (packages/plugins/*) that allows third-party developers to extend xmcp with additional functionality without modifying the core framework. Plugins can add new middleware, authentication providers, transport adapters, or tool integrations. The plugin system uses a standard interface that plugins implement, and the framework automatically discovers and loads plugins from the node_modules directory or explicit configuration.

Organizes the xmcp project as a pnpm monorepo with separate packages for the core framework (packages/xmcp), CLI tools (packages/create-xmcp-app, packages/init-xmcp), plugins (packages/plugins/*), documentation website (apps/website), and examples (examples/*). This structure enables independent versioning and publishing of each package while maintaining shared dependencies and coordinated development. pnpm workspaces handle dependency resolution and linking, reducing duplication and ensuring consistency across packages.

Abstracts MCP server implementation from transport protocol, allowing the same tool/prompt/resource definitions to be deployed via HTTP, STDIO, or serverless platforms (AWS Lambda, Vercel Functions) without code changes. The framework defines a transport interface that handles protocol-specific serialization, request routing, and response formatting. Each transport (http.ts, stdio.ts, adapters/) implements this interface, and the core framework compiles tools into a transport-agnostic handler registry that each transport consumes.

Provides a middleware pipeline architecture that intercepts MCP requests before they reach tool handlers, enabling authentication, logging, rate-limiting, and request transformation. Middleware is implemented as composable functions that receive the request context (including authentication state) and can modify or reject requests before handler execution. The framework includes built-in middleware for API key validation (api-key.ts) and JWT verification (jwt.ts), and allows custom middleware to be registered globally or per-tool via configuration.

Provides TypeScript interfaces and type definitions that enable compile-time validation of MCP tool signatures, parameter schemas, and response types. The framework exports core types (Tool, Prompt, Resource, etc.) that developers use to define MCP artifacts with full IDE autocomplete and type checking. Tool parameters are defined as TypeScript types, which are automatically converted to JSON Schema for MCP protocol compliance, ensuring type safety from development through runtime.

Provides two CLI tools for bootstrapping MCP projects: create-xmcp-app generates a new project from templates with pre-configured tools, prompts, and resources; init-xmcp integrates xmcp into existing projects (Next.js, Express) by adding necessary dependencies and configuration. Both tools use template files (in packages/create-xmcp-app/templates/) to generate starter code, tsconfig.json, and package.json with appropriate dependencies. The CLIs handle dependency installation and provide interactive prompts to customize project setup.

Uses webpack as the build system to compile TypeScript tools, prompts, and resources into optimized bundles for each transport target. The compilation pipeline (packages/xmcp/src/compiler) handles TypeScript transpilation, module bundling, and transport-specific code generation. Incremental builds are supported through webpack's caching mechanism, allowing only changed files to be recompiled during development. The compiler also generates type definitions and JSON Schema from TypeScript types, ensuring MCP protocol compliance.

Provides adapters and middleware that allow xmcp servers to run as part of Next.js API routes or Express applications, rather than as standalone processes. The framework exports adapters that wrap MCP handlers in Next.js request/response handlers or Express middleware, enabling MCP tools to coexist with other API endpoints in the same application. This allows developers to gradually adopt MCP without migrating their entire backend infrastructure.

Implements the core MCP protocol server that receives requests from Claude and other MCP clients, routes them to appropriate tool/prompt/resource handlers, and returns responses in MCP format. The execution engine maintains a registry of available tools, prompts, and resources (populated by the file-based routing system), validates incoming requests against tool schemas, and coordinates handler execution with middleware and authentication. The engine handles MCP protocol details (request/response serialization, error handling, capability negotiation) transparently.

Hosts a Next.js-based documentation site (apps/website) with integrated AI chat powered by Claude, full-text search, and interactive examples. The site is built with Next.js and includes a custom search implementation and an AI chat feature that allows users to ask questions about xmcp and get contextual answers. The documentation is sourced from markdown files and indexed for search, and the site includes a showcase of example projects built with xmcp.