xmcp: A TypeScript Framework for Building and Publishing MCP Applications

xmcp is a TypeScript-based development framework designed for building and distributing MCP (Model Context Protocol) applications . It simplifies the development process by enabling developers to quickly create efficient tools and deploy them to the MCP ecosystem. xmcp focuses on the developer experience, providing file system routing, hot reloading, and flexible middleware support. Both novice and professional developers can get started quickly with its intuitive configuration and automation tools. It supports platforms such as Vercel and is easy to deploy and highly compatible. The official website provides detailed documentation for developers who want to explore MCP development.

Function List

• Automatic registration tool: fromtoolsdirectory automatically discovers and registers tool files.
• File System Routing: Simplifies development with file structure based routing management.
• Hot reloading: instant feedback after code changes to improve development efficiency.
• Middleware Support: Provides authentication and customized middleware to enhance functionality extension.
• Flexible configuration: throughxmcp.config.tsCustomize MCP server settings.
• Cross-platform deployment: supports platforms such as Vercel, easy to deploy and highly compatible.
• Next.js and Express adapters: Seamless integration with existing projects.
• Official Documentation Support: Provides detailed development and deployment guidelines.

Using Help

Installation process

The installation process of xmcp is simple and suitable for Windows, macOS and Linux. Below are the detailed steps:

1. Installing Node.js
   Ensure that Node.js is installed on your system (recommended version 18 or higher). Visit the official Node.js website to download and install it. After installation, run the following command to check the version:

   node -v
   npm -v
   

2. Create a project
   Select a directory in the terminal and run the following command to initialize the xmcp project:

   npx create-xmcp@latest my-project
   

   command generates a file namedmy-projectof the project folder containing the following structure:

   my-project/
   ├── src/
   │   ├── middleware.ts    # 中间件处理HTTP请求/响应
   │   └── tools/           # 工具文件自动注册
   │       ├── greet.ts
   │       ├── search.ts
   ├── dist/                # 编译输出目录
   ├── package.json
   ├── tsconfig.json
   └── xmcp.config.ts       # xmcp配置文件
   

3. Installation of dependencies
   Go to the project directory and install the dependencies:

   cd my-project
   npm install
   

4. Starting the Development Server
   Run the following command to start the local development server:

   npm run dev
   

   The server runs by default on thehttp://localhost:3000. Open browser access to view the application. The Hot Reload feature reflects code changes in real time.

Main Functions

1. Creation of tools

xmcp passedtoolsCatalog auto-registration tool. The developer just needs to add thesrc/tools/Create TypeScript files under. For example, create a greeting toolgreet.ts::

export default {
name: "greet",
description: "Returns a greeting message",
async handler(input: string) {
return `Hello, ${input}!`;
},
};

After saving, the tool will be automatically registered without manual configuration. Accesshttp://localhost:3000/mcp?name=greetcan be called.

2. Configuration middleware

Middleware is used to process HTTP requests and responses, such as authentication or logging. In thesrc/middleware.tsDefine the middleware in:

import { Middleware } from "xmcp";
export default function authMiddleware(): Middleware {
return async (req, res, next) => {
const authHeader = req.headers.authorization;
if (!authHeader) {
res.status(401).json({ error: "Unauthorized" });
return;
}
await next();
};
}

The middleware will run before the request is processed and is suitable for adding custom logic.

3. Customized configuration

pass (a bill or inspection etc)xmcp.config.tsAdjust server settings, such as ports or tool catalogs:

import { defineConfig } from "xmcp";
export default defineConfig({
port: 3001,
toolsDir: "src/tools",
middleware: ["authMiddleware"],
});

Modify and restart the server to apply the configuration.

4. Deployment to Vercel

xmcp supports Vercel one-click deployment. Make sure the project is pushed to the GitHub repository, then:

1. Log in to the official Vercel website and connect to the GitHub repository.
2. Select the xmcp project and Vercel will automatically detect the configuration.
3. Click the "Deploy" button and wait for the deployment to complete.
   Upon successful deployment, Vercel will provide a public URL, for examplehttps://my-project.vercel.appThe

Featured Function Operation

hot and heavy duty

In development mode, modify thetoolsFiles in the directory trigger an automatic reload. There is no need to manually restart the server, making it suitable for rapid iteration. For example, editing thegreet.tsin the return message, save it and immediately see the update in your browser.

File System Routing

xmcp according totoolsThe directory structure automatically generates routes. For example.src/tools/search.tswill generate/mcp?name=searchof routing. Developers do not need to manually configure routing tables, simplifying management.

Next.js Integration

If you already have a Next.js project, you can integrate xmcp via an adapter. install xmcp in the Next.js project:

npm install xmcp

after thatpages/api/mcp.tsAdd in:

import { createMcpHandler } from "xmcp/next";
export default createMcpHandler({
toolsDir: "src/tools",
});

Restart the Next.js application and the xmcp function can be used in the/api/mcppath to use.

application scenario

1. Rapid Prototyping
   Developers can leverage xmcp's hot reloading and filesystem routing to quickly build MCP tool prototypes. For example, to develop a search tool, simply add thetoolsCatalog Additionssearch.tsThe function can be tested in a few minutes.
2. API Service Development
   xmcp is suitable for developing MCP-based API services. Authentication and logging through middleware , combined with Vercel deployment , suitable for mobile or Web applications to provide back-end support .
3. Existing Project Integration
   For existing Next.js or Express projects, xmcp's adapters integrate seamlessly. Developers can add MCP functionality without refactoring existing code.
4. Education and learning
   Novice developers can learn TypeScript and MCP development with xmcp. Its intuitive configuration and documentation lowers the learning threshold for beginners to practice.

QA

1. What programming languages does xmcp support?
   xmcp is mainly developed using TypeScript , but the generated MCP application can be called via HTTP , compatible with any language that supports HTTP .
2. How to debug the tool?
   In development mode, runnpm run dev, view the terminal console log. Tool execution errors are output in detail, making it easy to locate the problem.
3. Does it support multi-user authentication?
   Yes, multi-user authentication can be achieved through middleware. The developer needs to add themiddleware.tsImplement authentication logic in, for example, checking JWT.
4. Is it feasible to deploy to a non-Vercel platform?
   feasible. xmcp supports cross-platform deployment by simply adding the compileddistThe catalog is uploaded to a platform that supports Node.js, such as AWS or Heroku.