@mcpdotdirect/template-mcp-server

一个命令行工具，用于快速开始构建您自己的MCP（模型上下文协议）服务器，使用FastMCP。

📋 使用方法

# 使用npx
npx @mcpdotdirect/create-mcp-server

# 或者使用npm
npm init @mcpdotdirect/mcp-server

🔭 包含内容

模板包括：

• 使用FastMCP的基本服务器设置，支持stdio和HTTP传输选项
• 定义MCP工具、资源和提示的结构
• TypeScript配置
• 开发脚本和配置

✨ 特性

• FastMCP：使用FastMCP框架进行更简单的实现
• 双传输支持：通过stdio或HTTP运行您的MCP服务器
• TypeScript：完全支持TypeScript以确保类型安全
• 可扩展性：轻松添加自定义工具、资源和提示

🚀 快速开始

创建项目后：

1. 使用您喜欢的包管理器安装依赖项：

   # 使用npm
   npm install
   
   # 使用yarn
   yarn
   
   # 使用pnpm
   pnpm install
   
   # 使用bun
   bun install
   

2. 启动服务器：

   # 启动stdio服务器
   npm start
   
   # 或启动HTTP服务器
   npm run start:http
   

3. 开发模式下自动重载：

   # 使用stdio的开发模式
   npm run dev
   
   # 使用HTTP的开发模式
   npm run dev:http
   

注意：package.json中的默认脚本使用Bun作为运行时（例如，bun run src/index.ts）。如果您希望使用不同的包管理器或运行时，可以修改package.json文件中的这些脚本，以使用Node.js或其他您选择的运行时。

📖 详细用法

传输方式

MCP服务器支持两种传输方式：

1. stdio传输（命令行模式）：

   • 在您的本地机器上运行
   • 由Cursor自动管理
   • 直接通过stdout通信
   • 只能本地访问
   • 适合个人开发和工具

2. SSE传输（HTTP网络模式）：

   • 可以在本地或远程运行
   • 由您管理和运行
   • 通过网络通信
   • 可以跨机器共享
   • 适合团队协作和共享工具

在本地运行服务器

stdio传输（CLI模式）

以stdio模式启动CLI工具的服务器：

# 启动stdio服务器
npm start
# 或使用其他包管理器
yarn start
pnpm start
bun start

# 在开发模式下启动服务器并自动重载
npm run dev
# 或
yarn dev
pnpm dev
bun dev

HTTP传输（Web模式）

以HTTP模式启动web应用的服务器：

# 启动HTTP服务器
npm run start:http
# 或
yarn start:http
pnpm start:http
bun start:http

# 在开发模式下启动HTTP服务器并自动重载
npm run dev:http
# 或
yarn dev:http
pnpm dev:http
bun dev:http

默认情况下，HTTP服务器运行在3001端口。您可以通过设置PORT环境变量来更改此端口：

# 在自定义端口上启动HTTP服务器
PORT=8080 npm run start:http

连接到服务器

从Cursor连接

要从Cursor连接到您的MCP服务器：

1. 打开Cursor并转到设置（左下角的齿轮图标）
2. 点击左侧边栏中的“功能”
3. 滚动到“MCP服务器”部分
4. 点击“添加新MCP服务器”
5. 输入以下详细信息：
   • 服务器名称：my-mcp-server（或您喜欢的任何名称）
   • 对于stdio模式：
     • 类型：command
     • 命令：服务器可执行文件的路径，例如npm start
   • 对于SSE模式：
     • 类型：url
     • URL：http://localhost:3001/sse
6. 点击“保存”

使用mcp.json与Cursor

为了更方便地配置，可以在项目的根目录中创建一个.cursor/mcp.json文件：

{
  "mcpServers": {
    "my-mcp-stdio": {
      "command": "npm",
      "args": [
        "start"
      ],
      "env": {
        "NODE_ENV": "development"
      }
    },
    "my-mcp-sse": {
      "url": "http://localhost:3001/sse"
    }
  }
}

您也可以在~/.cursor/mcp.json中创建全局配置，以便在所有Cursor工作区中都可用。

注意：

• command类型的条目以stdio模式运行服务器
• url类型的条目通过SSE传输连接到HTTP服务器
• 您可以使用env字段提供环境变量
• 当通过SSE连接到FastMCP时，请使用包含/sse路径的完整URL：http://localhost:3001/sse

使用CLI工具测试您的服务器

FastMCP提供了内置工具来测试您的服务器：

# 使用mcp-cli测试
npx fastmcp dev server.js

# 使用MCP Inspector检查
npx fastmcp inspect server.ts

使用环境变量

您可以使用环境变量来自定义服务器：

# 更改HTTP端口（默认是3001）
PORT=8080 npm run start:http

# 更改主机绑定（默认是0.0.0.0）
HOST=127.0.0.1 npm run start:http

🛠️ 添加自定义工具和资源

当向您的FastMCP服务器添加自定义工具、资源或提示时：

工具

server.addTool({
  name: "hello_world",
  description: "一个简单的hello world工具",
  parameters: z.object({
    name: z.string().describe("要问候的名字")
  }),
  execute: async (params) => {
    return `Hello, ${params.name}!`;
  }
});

资源

server.addResourceTemplate({
  uriTemplate: "example://{id}",
  name: "示例资源",
  mimeType: "text/plain",
  arguments: [
    {
      name: "id",
      description: "资源ID",
      required: true,
    },
  ],
  async load({ id }) {
    return {
      text: `这是一个具有ID的示例资源：${id}`
    };
  }
});

提示

server.addPrompt({
  name: "greeting",
  description: "一个简单的问候提示",
  arguments: [
    {
      name: "name",
      description: "要问候的名字",
      required: true,
    },
  ],
  load: async ({ name }) => {
    return `Hello, ${name}! 今天我能为您做些什么？`;
  }
});

📚 文档

有关FastMCP的更多信息，请访问FastMCP GitHub仓库。

有关模型上下文协议的更多信息，请访问MCP文档。

📄 许可证

本项目采用MIT许可证 - 查看LICENSE文件获取详情。