使用说明

自定义MCP服务器🤖

使用Next.js构建的模型上下文协议（MCP）服务器，通过HTTP和服务器发送事件（SSE）传输提供有用的工具和实用程序。

🚀 特性

🔧 可用工具

回声 -回显任何消息（非常适合测试）
获取当前时间 -获取当前时间戳和ISO日期
计算 -安全地执行基本的数学计算

🌐 运输方式

HTTP传输 (/mcp)-无状态HTTP请求（在没有Redis的情况下工作）
苏格兰和南方能源公司运输 (/sse)-使用Redis进行状态管理的服务器发送事件

🔒 安全功能

速率限制（每分钟100个请求）
安全数学表达式评估
输入净化和验证

🏃‍♂️ 快速开始

先决条件

Node.js 18+
npm或纱线
Docker（可选，用于本地Redis）

设置

克隆和安装依赖关系：
```
npm install
```
运行自动安装程序：
```
npm run setup
```
这将：
- 创建环境配置
- 设置Redis（Docker）（如果可用）
- 自动启动开发服务器
手动启动（可选）：
```
npm run dev
```

服务器将在以下时间可用 http://localhost:3000

🧪 测试

快速测试

# Test HTTP transport
npm run test:http

# Test SSE transport (requires Redis)
npm run test:sse

# Test with Claude Desktop protocol
npm run test:stdio

# Comprehensive tool testing
npm run test:tools

手动测试

您可以使用curl手动测试MCP服务器：

# List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

# Call the echo tool
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "echo",
      "arguments": {
        "message": "Hello World!"
      }
    }
  }'

# Calculate an expression
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "calculate",
      "arguments": {
        "expression": "15 * 4 + 10"
      }
    }
  }'

🔧 配置

环境变量

创建一个 .env.local 文件：

# Local Redis (Docker)
REDIS_URL=redis://localhost:6379

# Upstash Redis (Production)
UPSTASH_REDIS_REST_URL=your-upstash-url
UPSTASH_REDIS_REST_TOKEN=your-upstash-token

Redis设置

服务器会自动检测并按照以下优先级顺序使用Redis：

升级Redis （如果 UPSTASH_REDIS_REST_URL 和 UPSTASH_REDIS_REST_TOKEN 已设置）
本地Redis （如果 REDIS_URL 已设置）
没有Redis （仅限HTTP传输）

使用Docker的本地Redis

# The setup script handles this automatically, but you can also run manually:
docker run -d --name redis-mcp -p 6379:6379 redis:alpine

Uptash Redis（推荐用于生产环境）

在以下位置创建Uptash Redis数据库 upush.com
将连接详细信息添加到您的 .env.local
服务器将自动检测并使用它

🖥️ 与AI工具集成

克劳德桌面

添加到您的Claude Desktop配置(claude_desktop_config.json):

{
  "mcpServers": {
    "custom-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3000/mcp"
      ]
    }
  }
}

配置文件位置：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %APPDATA%\Claude\claude_desktop_config.json

光标IDE

对于Cursor 0.48.0或更高版本（直接SSE支持）：

{
  "mcpServers": {
    "custom-mcp": {
      "url": "http://localhost:3000/sse"
    }
  }
}

对于较旧的Cursor版本：

{
  "mcpServers": {
    "custom-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3000/mcp"
      ]
    }
  }
}

🛠️ 发展

项目结构

custom-mcp-server/
├── app/
│   ├── [transport]/
│   │   └── route.ts          # Main MCP server logic
│   ├── layout.tsx            # Root layout
│   └── page.tsx              # Home page
├── lib/
│   └── redis.ts              # Redis utilities
├── scripts/
│   ├── setup.mjs             # Automated setup
│   ├── test-http-client.mjs  # HTTP transport tests
│   ├── test-sse-client.mjs   # SSE transport tests
│   └── test-tools.mjs        # Comprehensive tool tests
├── package.json
├── next.config.ts
└── README.md

添加新工具

定义工具 在……里面 app/[transport]/route.ts:

const tools = {
  // ... existing tools
  myNewTool: {
    name: "my-new-tool",
    description: "Description of what your tool does",
    inputSchema: {
      type: "object",
      properties: {
        param1: {
          type: "string",
          description: "Description of parameter"
        }
      },
      required: ["param1"]
    }
  }
};

添加处理程序:

const toolHandlers = {
  // ... existing handlers
  "my-new-tool": async ({ param1 }: { param1: string }) => {
    // Your tool logic here
    return {
      content: [
        {
          type: "text",
          text: `Result: ${param1}`
        }
      ]
    };
  }
};

测试您的更改

# Run all tests
npm run test:tools

# Test specific functionality
npm run test:http
npm run test:sse

📝 api参考

工具/列表

获取所有可用工具：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

工具/电话

调用特定工具：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "tool-name",
    "arguments": {
      "param": "value"
    }
  }
}

🚀 部署

Vercel（推荐）

部署到Vercel：
```
vercel
```
在Vercel仪表板中添加环境变量：
- UPSTASH_REDIS_REST_URL
- UPSTASH_REDIS_REST_TOKEN
更新您的AI工具配置 要使用已部署的URL，请执行以下操作：
```
https://your-app.vercel.app/mcp
https://your-app.vercel.app/sse
```

其他平台

服务器是一个标准的Next.js应用程序，可以部署到任何支持Node.js的平台：

Netlify
铁路
渲染
数字海洋应用平台

🤝 贡献

分叉存储库
创建要素分支： git checkout -b feature/my-new-feature
进行更改并添加测试
运行测试套件： npm run test:tools
提交您的更改： git commit -am 'Add some feature'
推到分支： git push origin feature/my-new-feature
提交拉取请求

📄 许可证

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

🆘 故障排除

常见问题

服务器未启动：

检查端口3000是否可用
确保安装了所有依赖项： npm install

Redis连接问题：

验证Docker是否正在运行： docker ps
检查Redis容器状态： docker ps -a | grep redis-mcp
重新启动Redis： docker restart redis-mcp

AI工具未检测到服务器：

确保服务器正在运行且可访问
检查配置文件语法（有效的JSON）
配置更改后重新启动AI工具
验证服务器URL是否正确

工具调用失败：

检查服务器日志中的错误消息
手动测试工具 npm run test:tools
验证工具参数是否与预期架构匹配

调试模式

通过设置环境变量启用调试日志记录：

DEBUG=1 npm run dev

📞 支持

在GitHub上创建一个bug报告问题
检查现有问题是否存在常见问题
查看测试脚本中的使用示例