内容
# 铁路MCP模板
可复刻的TypeScript MCP服务器模板，采用与邻近MCP存储库相同的实现模式。
## 包含内容
- 基于`stdio`的本地MCP
- 在`POST /mcp`上通过Streamable HTTP托管MCP
- 用于Claude自定义连接器的共享客户端OAuth
- 受密码保护的`/authorize`登录流程
- 用于持久化铁路卷的基于文件的OAuth状态
- 基于zod的工具工厂
- Docker和铁路部署配置
- 一个纯粹的`template-echo`工具和一个基于API的`template-api-get`示例工具
## 复刻检查清单
在复刻或复制此模板用于新的MCP时：
1. 重命名包和服务器标识：
- `railway-mcp-template`
- `Template MCP`
- `template-*`
- `TEMPLATE_*`
2. 用目标API客户端替换`src/clients/template-client.ts`。
3. 用特定于产品的工具组替换`src/tools/example/*`。
4. 在`src/tools/tool-factory.ts`中注册新组。
5. 更新`.env.example`和此README文件与目标服务变量。
6. 除非连接器需要不同的身份验证策略，否则保留共享的HTTP/OAuth文件。
## 环境
示例基于API的工具所需：
- `TEMPLATE_API_KEY`
可选：
- `TEMPLATE_API_BASE_URL`，默认为 `https://api.example.com`
- `TEMPLATE_REQUEST_TIMEOUT_MS`，默认为 `30000`
托管HTTP/OAuth：
- `PUBLIC_BASE_URL`
- `MCP_OAUTH_CLIENT_ID`
- `MCP_OAUTH_CLIENT_SECRET`
- `MCP_LOGIN_USERNAME`
- `MCP_LOGIN_PASSWORD`
- `MCP_OAUTH_STATE_FILE`（推荐的铁路部署所需）
## 本地stdio
```bash
npm install
npm run build
npm run start:stdio
```
`template-echo`工具无需外部凭证即可工作。示例`template-api-get`工具需要 `TEMPLATE_API_KEY`。
## 本地托管HTTP
```bash
PUBLIC_BASE_URL=http://127.0.0.1:3000/ \
MCP_OAUTH_CLIENT_ID=your_shared_client_id \
MCP_OAUTH_CLIENT_SECRET=your_shared_client_secret \
MCP_LOGIN_USERNAME=admin \
MCP_LOGIN_PASSWORD=change_me \
MCP_OAUTH_STATE_FILE=/tmp/template-mcp-oauth-state.json \
npm run build && npm run start:http
```
该服务器公开：
- `POST /mcp`
- `GET /health`
- OAuth元数据和身份验证端点在应用程序根目录
- 在 `GET /authorize` 上受密码保护的授权
## 铁路
使用包含的`Dockerfile`和`railway.json`。此模板旨在与Railway睡眠功能启用一起运行，并且`railway.json`默认启用它。
### 铁路部署设置
用于持久化连接器身份验证：
1. 将Railway卷附加到服务。
2. 在 `/data` 处挂载卷。
3. 设置 `MCP_OAUTH_STATE_FILE=/data/oauth-state.json`。
配置这些Railway变量：
- `PUBLIC_BASE_URL`
- `MCP_OAUTH_CLIENT_ID`
- `MCP_OAUTH_CLIENT_SECRET`
- `MCP_LOGIN_USERNAME`
- `MCP_LOGIN_PASSWORD`
- 特定于服务的API凭证，例如 `TEMPLATE_API_KEY`
- `MCP_OAUTH_STATE_FILE=/data/oauth-state.json`
这是预期的Railway部署配置。卷在睡眠、唤醒、重启和重新部署之间保留OAuth状态。
## 源布局
```text
src/
clients/ 工具处理程序的API客户端
helpers/ 共享格式和实用程序帮助程序
server/ MCP服务器工厂和OAuth支持
tools/
example/ 用产品特定工具组替换
responses.ts 常见的text/json MCP响应
tool-factory.ts 注册每个工具组
types.ts 共享工具定义类型
http.ts Streamable HTTP入口点
index.ts stdio入口点
```
## 工具模式
每个工具模块导出一个工厂：
```ts
export function exampleTool(): TemplateToolDefinition<typeof exampleSchema> {
return {
name: "service-resource-action",
description: "清晰的用户友好型工具描述。",
schema: exampleSchema,
handler: async (args) => {
// 调用客户端并返回 textResponse/jsonResponse
},
};
}
```
工具组从 `index.ts` 导出数组，并且 `src/tools/tool-factory.ts` 将它们注册到MCP服务器。
