MCP Reference

MCP参考服务器

一个最小的、自包含的模型上下文协议（MCP）HTTP服务器，您可以将其复制到其他Node.js项目中。

它暴露了一个 /mcp 通过Express实现端点，并实现了三个参考工具：

• ping --健康检查返回时间戳。
• echo --回应提供的信息。
• get_time --返回当前时间（UTC）和指定的IANA时区（可选）。

先决条件

• Node.js 18+

快速启动

# From this folder
npm install
npm start
# Server starts on http://localhost:3002

使用MCP检查器进行测试（HTTP传输）：

# GUI mode (may open a browser window)
npx @modelcontextprotocol/inspector --transport http --server-url http://localhost:3002/mcp

项目结构

mcp-reference/
├── package.json
├── README.md
├── .gitignore
├── mcp-inspector.config.json
└── src/
    └── index.js

运作原理

• src/index.js 从创建Express应用程序和MCP服务器 @modelcontextprotocol/sdk.
• 这 /mcp 路线用途 StreamableHTTPServerTransport 将HTTP请求桥接到MCP服务器并支持 POST （JSON-RPC）， GET （苏格兰和南方能源公司），以及 DELETE （会话关闭）根据流式HTTP传输。
• 工具通过注册 server.registerTool(name, {title, description, inputSchema}, handler).
• 工具处理程序解析为 { content: [{ type: 'text', text: string }] }，MCP客户端将显示哪些内容。

环境变量

• PORT （可选）：服务器端口。默认为 3002.
• MCP_AUTH_CODE （可选）：如果设置，服务器需要 mcp-auth-code: 在所有 /mcp 路线。

融入另一个项目

1. 复制 src/index.js 和 package.json 依赖于你的项目。
2. 安装 /mcp 在现有的Express服务器中路由（或将此文件用作单独的服务）。
3. 使用注册您自己的工具 registerTool 图案如所示 src/index.js.

工具注册示例

server.registerTool(
  'hello_name',
  {
    title: 'Hello Name',
    description: 'Returns a personalized greeting.',
    inputSchema: { name: z.string().describe('Name to greet') }
  },
  async ({ name }) => ({
    content: [{ type: 'text', text: JSON.stringify({ greeting: `Hello, ${name}!` }, null, 2) }]
  })
);

备注

• 此引用有意避免使用任何数据库、外部API或身份验证。根据需要将这些添加到您自己的项目中。
• 有关完整功能和协议详细信息，请参阅MCP SDK文档。

MCP检查员故障排除

• 如果Inspector试图启动演示STDIO服务器（例如。， mcp-server-everything)或者连接到错误的端口（例如。， 3001)，强制HTTP传输和URL:

  npx @modelcontextprotocol/inspector --transport http --server-url http://localhost:3002/mcp

• 如果你遇到代理/UI端口冲突，比如 Proxy Server PORT IS IN USE at port 6277，关闭所有以前的检查器实例。在macOS上，您可以找到并终止该进程：

  lsof -i :6277
  kill -9 

注意：Inspector CLI目前需要本地命令的stdio传输，因此更喜欢具有以下功能的GUI --transport http 和 --server-url 在测试HTTP服务器时。

启用MCP服务器的基本身份验证

通过设置环境变量，可以在MCP路由上启用简单的共享密钥检查。启用后，请求 POST /mcp, GET /mcp （苏格兰和南方能源公司），以及 DELETE /mcp 必须包含具有确切机密值的此标头：

• mcp-auth-code:

设置密码并启动服务器：

export MCP_AUTH_CODE="my-secret-123"
npm start

卷曲测试：

# Initialize (example JSON-RPC payload), passing the header
curl -sS \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-auth-code: my-secret-123" \
  -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":"2025-03-26"}}' \
  http://localhost:3002/mcp

使用标题运行MCP检查器：

# Option 1: pass the header inline
npx @modelcontextprotocol/inspector \
  --transport http \
  --server-url http://localhost:3002/mcp \
  --header "mcp-auth-code: my-secret-123"

# Option 2: use env var with the npm script
export MCP_AUTH_CODE="my-secret-123"
npm run mcp:debug:auth