Katoshi MCP

加藤MCP服务器

一个模型上下文协议（MCP）服务器，它将现有的API转换为MCP工具，可部署在 铁路.

概述

该项目提供：

• MCP服务器实现：将API转换为MCP兼容工具
• HTTP服务器：通过HTTP使用JSON-RPC 2.0的长时间运行服务器（例如在Railway上）
• 轻松工具注册：添加新API工具的简单模式

建筑

AI Agent → Railway (HTTP) → MCP Server → Your APIs

MCP服务器通过HTTP实现JSON-RPC 2.0协议，使其与MCP客户端和AI代理兼容。

快速开始

先决条件

• Node.js 22+（使用 nvm use 选择正确的版本）

安装

1. 安装依赖项：

npm install

1. 构建项目：

npm run build

本地开发

在本地运行服务器进行测试：

npm run dev

这将启动本地开发服务器。您可以通过以下方式进行测试：

# Health check
curl http://localhost:3000/health

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

# Call a tool
curl -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_user_by_id",
      "arguments": {
        "userId": "123"
      }
    }
  }'

将您的API添加为MCP工具

步骤1：创建工具文件

在中创建新文件 src/ （例如。， src/user-apis.ts):

import type { Tool } from "@modelcontextprotocol/sdk/types.js";

// Your API function
async function getUserProfile(args: Record): Promise {
  const userId = args.userId as string;
  
  // Call your actual API
  const response = await fetch(`https://your-api.com/users/${userId}`, {
    headers: {
      "Authorization": `Bearer ${process.env.API_KEY}`,
    },
  });
  
  if (!response.ok) {
    throw new Error(`API error: ${response.statusText}`);
  }
  
  const data = await response.json();
  return JSON.stringify(data);
}

// Export as MCP tool
export const userApiTools: Tool[] = [
  {
    name: "get_user_profile",
    description: "Get user profile information by user ID",
    inputSchema: {
      type: "object",
      properties: {
        userId: {
          type: "string",
          description: "The unique identifier of the user",
        },
      },
      required: ["userId"],
    },
    handler: getUserProfile,
  },
];

步骤2：注册工具

将您的工具添加到 src/tools.ts:

import { userApiTools } from "./user-apis.js";

export const apiTools: Tool[] = [
  ...exampleApiTools,
  ...userApiTools, // Add your tools here
];

步骤3：重建和部署

npm run build
# Deploy via Railway (see below) or your own host

铁路部署

通过将GitHub仓库连接到Railway进行部署；推送到您选择的分支将触发自动构建和部署。不需要部署脚本。

1.将GitHub连接到铁路

1. 登录地址： railway应用程序 并创建一个新项目。
2. 点击 添加服务 → GitHub回购 并选择此存储库。
3. 选择要部署的分支（例如。 main).
4. Railway将检测Node.js并使用：

- 构建: npm run build - 开始: npm start （跑步 node dist/index.js)

服务器监听 PORT Railway自动设置的环境变量。

2.环境变量

在您的铁路服务中→ 变量，添加您的工具所需的任何环境变量，例如：

• API_KEY –如果您的工具调用外部API
• API_BASE_URL –API的基本URL
• 你的任何其他钥匙 src/tools 使用

3.获取您的URL

首次部署后，Railway会分配一个公共URL（例如。 https://your-app.up.railway.app).您可以在服务设置中添加自定义域。

4.从另一条铁路服务（同一项目）连接

当同一铁路项目中的另一个服务连接到此MCP服务器时，请使用 私有URL 和 包括端口:

• 在其他服务的变量中，设置例如。 KATOSHI_MCP_URL=https://katoshi-mcp.railway.internal:PORT 哪里 PORT 港口铁路公司是否分配这种MCP服务（通常 8080 或价值 PORT 在这项服务中）。例子： https://katoshi-mcp.railway.internal:8080/?id=USER_ID.
• 如果省略端口，客户端可能会连接到错误的端口并失败（连接错误、超时或“未返回响应”）。

API使用

MCP协议端点

替换 https://your-app.up.railway.app 使用您的铁路（或本地）URL。

列出可用工具：

POST https://your-app.up.railway.app/
Content-Type: application/json

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

调用工具：

POST https://your-app.up.railway.app/
Content-Type: application/json

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

健康检查：

GET https://your-app.up.railway.app/health

从Cursor IDE连接

Cursor IDE支持使用以下方式连接到远程MCP服务器 mcp-remote 包裹。这允许您直接在Cursor中使用部署的MCP服务器。

步骤1：创建MCP配置

创建或编辑MCP配置文件。光标在以下位置查找MCP配置：

• 全球: ~/.cursor/mcp.json （适用于所有工作区）
• 工作区: .cursor/mcp.json 在项目根目录中（特定于工作区）

步骤2：添加服务器配置

将以下配置添加到您的 mcp.json 文件：

{
  "mcpServers": {
    "katoshi": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://YOUR_RAILWAY_URL?id=USER_ID&api_key=API_KEY"
      ]
    }
  }
}

替换占位符：

• USER_ID：您的用户ID
• API_KEY：您的API密钥

注： 这 mcp-remote 软件包将通过以下方式自动安装 npx 当Cursor连接时，您不需要全局安装它。

步骤3：重新启动游标

添加配置后，重新启动Cursor IDE以加载MCP服务器连接。

配置文件示例

复制示例配置并使用您的凭据进行自定义：

# For workspace-specific configuration
mkdir -p .cursor
cat > .cursor/mcp.json  ~/.cursor/mcp.json << 'EOF'
{
  "mcpServers": {
    "katoshi": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://YOUR_RAILWAY_URL?id=YOUR_USER_ID&api_key=YOUR_API_KEY"
      ]
    }
  }
}
EOF

替换 YOUR_USER_ID 和 YOUR_API_KEY 凭你的真实证件。

从其他AI代理连接

大多数MCP客户端支持HTTP传输。使用以下配置您的客户端：

• 统一资源定位符：您的铁路（或其他）端点URL
• 运输：HTTP
• 协议：JSON-RPC 2.0

Claude Desktop示例（如果支持）：

{
  "mcpServers": {
    "katoshi": {
      "url": "https://your-app.up.railway.app/",
      "transport": "http"
    }
  }
}

项目结构

katoshi-mcp/
├── index.ts                 # HTTP server entry (Railway / local)
├── src/
│   ├── tools.ts             # Tool types + registry (combines all tools)
│   ├── mcp-server.ts        # MCP server implementation
│   ├── katoshi-tools.ts     # Katoshi trading tools
│   ├── hyperliquid-tools.ts # Hyperliquid API tools (optional)
│   ├── request-context.ts   # Request context (apiKey, userId)
│   └── utils.ts             # Logging and helpers
├── mcp.json.example         # Example Cursor MCP configuration
├── package.json
└── tsconfig.json

故障排除

游标中的MCP连接问题

如果在Cursor中连接到MCP服务器时遇到错误（例如 Cannot find module 'math-intrinsics/abs')，这通常是由于Node.js版本不匹配。这 mcp-remote 包需要Node.js 22或更高版本。

解决方案：更新Node.js版本

1. 确保已安装Node.js 22+并将其设置为默认值：

# Using nvm (recommended)
nvm install 22
nvm use 22
nvm alias default 22

# Or download from https://nodejs.org/

1. 清除npx缓存以从较旧的Node版本中删除缓存的包：

rm -rf ~/.npm/_npx

1. 重新启动游标IDE

验证Node.js版本

检查你的Node.js版本：

node -v  # Should show v22.x.x or higher

如果您使用的是nvm，请确保它已加载到您的shell配置文件中(.zshrc, .bashrc等等）：

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

CORS问题

默认情况下，服务器发送允许的CORS标头。限制生产来源，改变 CORS_HEADERS 在 index.ts （例如设置 Access-Control-Allow-Origin 到您的前端源）。

铁路原木

在铁路仪表板中，打开您的服务→ 部署 → 选择部署→ 查看日志 查看stdout/stderr。

安全

1. API密钥：存储在铁路变量（或其他机密管理器）中；永远不要提交密钥。
2. 跨域资源共享：限制生产中允许的来源（见上文）。
3. 认证：MCP请求需要API密钥，通过 Authorization: Bearer, X-Api-Key，或 api_key 查询参数；后端在第一次工具调用时进行验证。

后续步骤

• \[\]用实际的API替换示例API
• \[\]根据需要添加身份验证/授权
• \[\]添加监控和警报（例如铁路指标或外部APM）
• \[\]在Railway中配置自定义域

资源

• MCP规范
• 铁路文件

许可证

麻省理工学院