AI导哈

模型上下文协议服务器

一个基于Node.js和TypeScript的模型上下文协议(MCP)服务器实现，用于与Claude Desktop集成，提供工具发现、安全执行和扩展功能。

  • by Ranjith63812
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Ranjith63812/MCP-SERVER

使用说明

MCP服务器示例

Node.js+TypeScript中的完整模型上下文协议（MCP）服务器实现，作为本地工具与Claude Desktop集成。

什么是MCP？

这 模型上下文协议（MCP） 是一种标准化协议，使大型语言模型（如Claude）能够安全地与外部工具和数据源交互。MCP服务器公开了Claude可以在对话期间实时发现和调用的功能（工具）。

MCP的主要特征：

  • 工具发现：Claude可以查询可用的工具及其参数
  • 安全执行：带验证的结构化JSON-RPC消息
  • 标准运输：用于与Claude Desktop的本地集成
  • 可扩展：易于添加具有标准化界面的新工具

项目结构

example-mcp-server/
├── src/
│   ├── mcp/
│   │   └── server.ts          # MCP server with stdio transport
│   ├── tools/
│   │   ├── index.ts           # Tool registry & dispatcher
│   │   ├── ping.ts            # Ping tool (health check)
│   │   └── system_info.ts     # System info tool
│   └── types/
│       └── index.ts           # Type definitions
├── package.json               # Dependencies & scripts
├── tsconfig.json              # TypeScript config
├── mcp.json                   # Claude Desktop manifest
└── README.md                  # This file

入门指南

先决条件

  • Node.js 18+（LTS）
  • npm或纱线
  • 克劳德桌面（用于测试）

安装

  1. 克隆或导航到项目目录：
cd example-mcp-server
  1. 安装依赖项：
npm install
  1. 构建TypeScript代码：
npm run build

这将编译所有 .ts 文件在 src/ JavaScript在 dist/ 文件夹。

运行MCP服务器

npm start

服务器将开始监听stdin/stdout，准备接收JSON-RPC消息。

在本地测试服务器

使用curl和echo（Windows PowerShell）

测试 tools/list 端点：

$message = @{
    jsonrpc = "2.0"
    id = 1
    method = "tools/list"
} | ConvertTo-Json -Compress
"$message" | node dist/mcp/server.js

使用Node.js测试脚本

创建 test.js:

import { spawn } from "child_process";

const server = spawn("node", ["dist/mcp/server.js"]);

let output = "";

server.stdout.on("data", (data) => {
  const line = data.toString().trim();
  if (line) {
    console.log("Response:", JSON.parse(line));
    server.kill();
  }
});

server.on("close", () => {
  console.log("Server closed");
});

// Send initialize request
const initMsg = {
  jsonrpc: "2.0",
  id: 1,
  method: "initialize",
  params: {
    protocolVersion: "2024-11-05",
    capabilities: {},
    clientInfo: { name: "test-client", version: "1.0.0" },
  },
};

server.stdin.write(JSON.stringify(initMsg) + "\n");

// Wait a moment, then send tools/list
setTimeout(() => {
  const listMsg = { jsonrpc: "2.0", id: 2, method: "tools/list" };
  server.stdin.write(JSON.stringify(listMsg) + "\n");
}, 100);

运行方式：

npm run build && node test.js

可用工具

1. ping

一个简单的健康检查工具。

请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ping",
    "arguments": {}
  }
}

答复：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "output": "pong"
  }
}

2. system_info

返回系统和平台信息。

请求：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "system_info",
    "arguments": {}
  }
}

答复：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "output": {
      "platform": "win32",
      "arch": "x64",
      "nodeVersion": "v20.10.0",
      "osType": "Windows_NT",
      "osRelease": "10.0.22621",
      "totalMemory": "16384 MB",
      "freeMemory": "8192 MB",
      "cpuCount": 8,
      "uptime": "24 hours"
    }
  }
}

在Claude Desktop注册

要使此MCP服务器在Claude Desktop中可用，请执行以下操作：

视窗

  1. 打开 %APPDATA%\Claude\claude_desktop_config.json
  2. 添加此服务器配置：
{
  "mcpServers": {
    "example-mcp-server": {
      "command": "node",
      "args": ["C:\\path\\to\\example-mcp-server\\dist\\mcp\\server.js"]
    }
  }
}

替换 C:\path\to\example-mcp-server 了解项目的实际完整路径。

macOS

  1. 打开 ~/Library/Application Support/Claude/claude_desktop_config.json
  2. 添加服务器配置（使用POSIX路径）

Linux

  1. 打开 ~/.config/Claude/claude_desktop_config.json
  2. 添加服务器配置

配置示例

{
  "mcpServers": {
    "example-mcp-server": {
      "command": "node",
      "args": ["C:\\Users\\YourUsername\\projects\\example-mcp-server\\dist\\mcp\\server.js"]
    }
  }
}
  1. 重新启动克劳德桌面 使更改生效
  2. 在Claude中，查找工具图标或提及“使用ping工具”或“检查系统信息”

添加新工具

要添加新工具，请执行以下操作：

  1. 创建工具文件 在 src/tools/ （例如。， src/tools/my_tool.ts):
import { ToolHandler } from "../types/index.js";

export const myToolHandler: ToolHandler = async (args) => {
  // Implement your tool logic
  return { result: "Your result here" };
};

export const myToolDefinition = {
  name: "my_tool",
  description: "Description of what your tool does",
  inputSchema: {
    type: "object",
    properties: {
      param1: { type: "string", description: "First parameter" },
      param2: { type: "number", description: "Second parameter" },
    },
    required: ["param1"],
  },
};
  1. 在中注册 src/tools/index.ts:
import { myToolHandler, myToolDefinition } from "./my_tool.js";

const registry: ToolRegistry = {
  // ... existing tools
  my_tool: {
    definition: myToolDefinition,
    handler: myToolHandler,
  },
};
  1. 重建并重新启动:
npm run build
npm start

MCP协议概述

服务器实现了MCP规范，支持：

  • 初始化：与客户握手
  • 工具/列表：返回可用的工具和模式
  • 工具/调用：使用提供的参数执行工具

所有通信用途 JSON-RPC 2.0 具有结构化错误处理的格式。

故障排除

服务器无法启动

  • 确保已安装Node.js 18+： node --version
  • 检查TypeScript是否正确编译： npm run build
  • 验证 dist/mcp/server.js 存在

Claude Desktop看不到服务器

  • 仔细检查路径 claude_desktop_config.json 是正确和绝对的
  • 更新配置后重新启动Claude Desktop
  • 检查服务器是否在本地运行： npm start

工具调用失败

  • 确保工具名称完全匹配（区分大小写）
  • 验证是否提供了所需的参数
  • 检查JSON-RPC响应中的错误消息

脚本

npm run build    # Compile TypeScript to dist/
npm start        # Run the MCP server
npm run dev      # Build and run in one command

许可证

麻省理工学院

参考文献

相关 MCP