Dead Simple MCP Server

MCP工具演示

A. 模型上下文协议（MCP） 展示干净、模块化工具架构的实现 本地和远程工具 支持和交互式浏览器客户端。

🌟 特性

• 🏗️ 清洁建筑：模块化工具设计 MCPToolsManager
• 🔧 8演示工具：4个本地工具+4个远程工具无缝协作
• 🌐 远程工具支持：从外部API动态加载工具
• 🌐 浏览器客户端：用于测试所有工具的交互式web界面
• 🔧 管理面板：功能强大的基于网络的工具管理，带有开/关开关
• ⚡ 工具配置：基于JSON的工具状态管理，具有持久性
• 📡 多种服务器选项：Stdio、简单HTTP和远程工具服务器
• 🔒 类型安全：带Zod验证的完整TypeScript实现

🚀 快速开始

1.安装

git clone 
cd mcp-hello-world
npm install

2.完整演示（本地+远程工具）

启动两台服务器以获得完整体验：

# Terminal 1: Start remote tools server (4 remote tools)
npm run start:remote

# Terminal 2: Start HTTP server (4 local + 4 remote = 8 total tools)
npm run start:http

然后打开：

• 客户端接口: http://localhost:3000/examples/client.html
• 管理面板: http://localhost:3000/examples/admin.html

3.仅限本地工具

# Just local tools (4 tools)
REMOTE_TOOLS_ENABLED=false npm run start:http

4.命令行用法（光标/Claude）

npm run build
node dist/index.js  # Stdio MCP server

🏗️ 建筑

模块化结构

mcp-hello-world/
├── src/
│   ├── index.ts                 # Main MCP stdio server
│   ├── mcp-tools-manager.ts     # Generic tools manager (local + remote)
│   ├── simple-http-server.ts    # HTTP wrapper with remote tools support
│   ├── tool-config.ts          # 🔧 Tool configuration manager
│   ├── tools/                   # 🏠 Local tools directory
│   │   ├── index.ts            # Tools exports and registry
│   │   ├── greg-test-tool.ts   # Mood testing tool
│   │   ├── http-post-tool.ts   # Generic HTTP POST
│   │   ├── weather-tool.ts     # Weather API integration
│   │   └── create-post-tool.ts # JSONPlaceholder posts
│   └── types/mcp.ts            # TypeScript definitions
├── examples/
│   ├── client.html             # 🌐 Interactive browser client
│   ├── admin.html              # 🔧 Admin panel for tool management
│   ├── remote-tools-api-example.json      # Remote tools definition
│   └── remote-tool-server-example.js     # 🌐 Remote tools server
├── tool-config.json            # ⚡ Tool configuration state
└── dist/                       # Compiled JavaScript

关键设计原则

• 单一真相来源：本地工具 src/tools/，通过API的远程工具
• 通用经理: MCPToolsManager 自动加载所有工具
• 工具配置：基于JSON的持久工具状态管理
• 可热加载：无需重新启动即可添加/更新远程工具
• 多个接口：同样的工具适用于stdio、HTTP和浏览器
• 管理员控制：基于Web的工具管理，具有实时切换功能

🔧 可用工具

🏠 本地工具（4）

1. 🎭 格雷格测试 (greg-test)-情绪测试工具
2. 🌐 HTTP POST (http_post)-通用HTTP请求
3. 🌤️ 天气 (get_weather)-天气API与OpenWeatherMap
4. 📄 创建帖子 (create_post)-JSON占位符集成

🌐 远程工具（4）

1. 🧮 计算税款 (calculate_tax)-税务计算
2. 📧 发送电子邮件 (send_email)-模拟电子邮件发送
3. 🖼️ 图像OCR (image_ocr)-模拟文本提取
4. 🗄️ 数据库查询 (database_query)-模拟SQL查询

🌐 远程工具支持

从外部API与本地工具一起动态加载工具。

快速配置

const toolsManager = new MCPToolsManager({
  enabled: true,
  toolsUrl: 'http://localhost:3001/mcp/tools',
  timeout: 5000,
  retryAttempts: 2,
});

await toolsManager.initialize();

远程工具API格式

您的远程API应返回：

{
  "tools": [
    {
      "name": "calculate_tax",
      "description": "Calculate tax for given amount",
      "executeUrl": "https://api.example.com/tools/calculate-tax",
      "method": "POST",
      "inputSchema": {
        "type": "object",
        "properties": {
          "amount": { "type": "number" },
          "rate": { "type": "number" }
        },
        "required": ["amount", "rate"]
      }
    }
  ]
}

环境配置

export REMOTE_TOOLS_ENABLED=true              # Enable/disable remote tools
export REMOTE_TOOLS_URL=http://localhost:3001/mcp/tools
export REMOTE_TOOLS_TIMEOUT=5000
export REMOTE_TOOLS_RETRY_ATTEMPTS=2

🔧 管理面板

强大的基于web的工具管理界面 用于控制工具可用性：

特性

• 🎛️ 工具切换：使用可视开关启用/禁用单个工具
• 📊 实时统计：显示启用/禁用计数的实时仪表板
• ⚡ 批量操作：一次启用所有/禁用所有工具
• 🔄 自动刷新：每30秒自动与服务器同步一次
• 🎨 现代用户界面：美观、响应迅速的界面，带有视觉反馈
• 💾 持久状态：工具配置已保存到 tool-config.json

默认行为

默认情况下禁用所有工具 -您必须通过管理面板启用它们。

用法

1. 启动服务器： npm run start:http
2. 打开管理面板：http://localhost:3000/examples/admin.html
3. 根据需要打开/关闭工具
4. 使用客户端界面进行测试：http://localhost:3000/examples/client.html

工具配置文件

管理面板管理 tool-config.json 采用这种结构：

[
  {
    "toolName": "greg-test",
    "enabled": true
  },
  {
    "toolName": "http_post",
    "enabled": false
  }
]

🌐 浏览器客户端

交互式web客户端动态加载和显示 仅启用工具:

特性

• 🔍 自动发现：从服务器加载已启用的工具（本地+远程）
• 🎯 快速测试：一键测试已启用的工具
• 📊 工具统计：显示本地与远程故障
• ✅ 健康监测：实时服务器状态
• 🔄 动态更新：实时反映工具可用性

用法

1. 启动服务器： npm run start:remote && npm run start:http
2. 在管理面板中启用工具：http://localhost:3000/examples/admin.html
3. 使用客户端界面：http://localhost:3000/examples/client.html
4. 点击“加载可用工具”查看已启用的工具
5. 使用快速测试按钮或详细的工具信息

🚀 运行服务器

HTTP服务器（浏览器演示）

npm run start:http      # Local tools only
# OR with remote tools:
npm run start:remote    # Terminal 1: Remote tools server
npm run start:http      # Terminal 2: HTTP server (8 tools total)

Stdio服务器（游标/克劳德集成）

npm run build
node dist/index.js

然后添加到MCP配置中：

{
  "mcpServers": {
    "demo-tools": {
      "command": "node",
      "args": ["path/to/mcp-server-remote-architecture/dist/index.js"]
    }
  }
}

对Cursor/Claude很重要:

• 默认情况下禁用所有工具 -您最初将看到0个工具
• 先启用工具：使用管理面板启用所需的工具

1. 运行： npm run start:http 1. 打开：http://localhost:3000/examples/admin.html 1. 启用要使用的工具 1. 重新启动Cursor的MCP连接以查看工具

• 工具状态持续存在 跨服务器重启

🔧 管理员API端点

服务器为工具管理提供了专用的管理端点：

获取 /admin/tools

获取所有工具配置（启用和禁用）：

{
  "success": true,
  "tools": [
    {
      "toolName": "greg-test",
      "enabled": true,
      "type": "local",
      "description": "amazing tool"
    }
  ],
  "count": 4
}

发布 /admin/tools/:toolName/toggle

切换工具的启用/禁用状态：

curl -X POST http://localhost:3000/admin/tools/greg-test/toggle \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

答复：

{
  "success": true,
  "message": "Tool 'greg-test' enabled",
  "toolName": "greg-test",
  "enabled": true,
  "timestamp": "2025-06-21T18:29:38.323Z"
}

🔧 故障排除

光标/Claude显示0个工具

问题：MCP服务器在光标中显示红点和0个工具 解决方案:

1. 默认情况下禁用工具-通过管理面板启用它们
2. 确保项目目录中存在工具配置文件
3. 启用工具后重新启动Cursor的MCP连接

未找到工具配置

问题：服务器在禁用所有工具的情况下创建新配置 解决方案：工具配置使用绝对路径-无论工作目录如何，都能正常工作

🧪 测试

API快速测试

# Test tool endpoints
curl http://localhost:3000/mcp/tools          # Enabled tools only
curl http://localhost:3000/mcp/tools/local    # Enabled local tools only
curl http://localhost:3000/mcp/tools/remote   # Enabled remote tools only

# Test admin endpoints
curl http://localhost:3000/admin/tools         # All tool configurations
curl -X POST http://localhost:3000/admin/tools/greg-test/toggle \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'                       # Enable a tool

# Test specific tools (only if enabled)
curl http://localhost:3000/mcp/test/greg-test
curl http://localhost:3000/mcp/test/calculate_tax  # Remote tool

工具调用

# Note: Tools must be enabled first via admin panel
curl -X POST http://localhost:3000/mcp/call-tool \
  -H "Content-Type: application/json" \
  -d '{"tool": "calculate_tax", "parameters": {"amount": 100, "rate": 0.08}}'

🔧 添加新工具

本地工具

1. 创建 src/tools/my-tool.ts
2. 出口自 src/tools/index.ts
3. 重新启动服务器以加载新工具
4. 通过管理面板启用该工具 （默认情况下禁用）

远程工具

1. 将工具定义添加到远程API
2. 实现执行端点
3. 刷新远程工具或重新启动服务器
4. 通过管理面板启用该工具 （默认情况下禁用）

工具状态管理

• 默认情况下禁用所有新工具
• 使用管理面板启用/禁用工具
• 工具状态持续存在 tool-config.json
• 只有启用的工具才会显示在 /mcp/tools 端点

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。