@mcpdotdirect/template-mcp-server

@mcpdotdirect/template-mcp-server

使用 FastMCP 快速开始构建你自己的 MCP（Model Context Protocol）服务的命令行工具

📋 用法

# with npx
npx @mcpdotdirect/create-mcp-server

# Or with npm
npm init @mcpdotdirect/mcp-server

🔭 包含内容

该模板包含：

• 使用 FastMCP 的基础服务设置，支持 stdio 和 HTTP 两种传输方式
• 用于定义 MCP 工具、资源和提示词的结构
• TypeScript 配置
• 开发脚本和配置

✨ 特性

• FastMCP：基于 FastMCP 框架构建，实现更简单
• 双传输支持：通过 stdio 或 HTTP 运行 MCP 服务
• TypeScript：全面支持 TypeScript，确保类型安全
• 可扩展：轻松添加自定义工具、资源和提示词

🚀 开始使用

创建项目后：

1. 使用你偏好的包管理器安装依赖：

   # Using npm
   npm install
   
   # Using yarn
   yarn
   
   # Using pnpm
   pnpm install
   
   # Using bun
   bun install
   

2. 启动服务：

   # Start the stdio server
   npm start
   
   # Or start the HTTP server
   npm run start:http
   

3. 使用自动重新加载进行开发：

   # Development mode with stdio
   npm run dev
   
   # Development mode with 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 Web 模式）：

   • 可在本地或远程运行
   • 由你管理和运行
   • 通过网络通信
   • 可在多台计算机之间共享
   • 适合团队协作和共享工具

在本地运行服务

stdio 传输（CLI 模式）

以 stdio 模式启动服务，供 CLI 工具使用：

# Start the stdio server
npm start
# or with other package managers
yarn start
pnpm start
bun start

# Start the server in development mode with auto-reload
npm run dev
# or
yarn dev
pnpm dev
bun dev

HTTP 传输（Web 模式）

以 HTTP 模式启动服务，供 Web 应用使用：

# Start the HTTP server
npm run start:http
# or
yarn start:http
pnpm start:http
bun start:http

# Start the HTTP server in development mode with auto-reload
npm run dev:http
# or
yarn dev:http
pnpm dev:http
bun dev:http

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

# Start the HTTP server on a custom port
PORT=8080 npm run start:http

连接到服务

从 Cursor 连接

要从 Cursor 连接到你的 MCP 服务：

1. 打开 Cursor，然后进入 Settings（左下角的齿轮图标）
2. 点击左侧边栏中的 “Features”
3. 向下滚动到 “MCP Servers” 部分
4. 点击 “Add new MCP server”
5. 输入以下详细信息：
   • 服务名称：my-mcp-server（或任何你喜欢的名称）
   • 对于 stdio 模式：
     • 类型：command
     • 命令：服务可执行文件的路径，例如 npm start
   • 对于 SSE 模式：
     • 类型：url
     • URL：http://localhost:3001/sse
6. 点击 “Save”

在 Cursor 中使用 mcp.json

如需更便于移植的配置，请在项目根目录下创建 .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 工作区都能使用你的 MCP 服务。

注意：

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

使用 CLI 工具测试服务

FastMCP 提供了用于测试服务的内置工具：

# Test with mcp-cli
npx fastmcp dev server.js

# Inspect with MCP Inspector
npx fastmcp inspect server.ts

使用环境变量

你可以使用环境变量自定义服务：

# Change the HTTP port (default is 3001)
PORT=8080 npm run start:http

# Change the host binding (default is 0.0.0.0)
HOST=127.0.0.1 npm run start:http

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

向 FastMCP 服务添加自定义工具、资源或提示词时：

工具

server.addTool({
  name: "hello_world",
  description: "A simple hello world tool",
  parameters: z.object({
    name: z.string().describe("Name to greet")
  }),
  execute: async (params) => {
    return `Hello, ${params.name}!`;
  }
});

资源

server.addResourceTemplate({
  uriTemplate: "example://{id}",
  name: "Example Resource",
  mimeType: "text/plain",
  arguments: [
    {
      name: "id",
      description: "Resource ID",
      required: true,
    },
  ],
  async load({ id }) {
    return {
      text: `This is an example resource with ID: ${id}`
    };
  }
});

提示词

server.addPrompt({
  name: "greeting",
  description: "A simple greeting prompt",
  arguments: [
    {
      name: "name",
      description: "Name to greet",
      required: true,
    },
  ],
  load: async ({ name }) => {
    return `Hello, ${name}! How can I help you today?`;
  }
});

📚 文档

如需了解 FastMCP 的更多信息，请访问 FastMCP GitHub 仓库。

如需了解 Model Context Protocol 的更多信息，请访问 MCP 文档。

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。