内容
# Intervals.icu 中间服务器
Intervals.icu 的最小本地标准输入输出中间服务器，由官方 OpenAPI 规范生成。暴露所有 API 操作作为中间工具。与 Claude Desktop、mcphost（Ollama / OpenRouter）、Cline 和任何其他支持标准输入输出的中间客户端配合使用；此仓库完全自成体系。
## 文件
```bash
|____spec/intervals-openapi-spec.json # Intervals.ICU API 规范
|____README.md # 就是这个！
|____config.js.example # 示例 config.js 文件
|____package.json # npm 依赖包文件
|____mcp-stdio.mjs # 中间服务器
```
## 要求
- Node.js ≥ 18
- Intervals.icu API 密钥 — 从 <https://intervals.icu/settings> 获取（页面底部，“开发者设置”）
## 安装
克隆仓库并存储在机器的任意位置。复制 `config.js.example` 到 `config.js` 并设置 `INTERVALS_TOKEN` 为您的 Intervals.icu API 密钥。
```bash
cp config.js.example config.js
npm install
```
## 测试
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node mcp-stdio.mjs | python3 -mjson.tool | grep "name\"" | head
```
您应该在标准错误输出中看到：
```bash
[intervals-mcp] ready · 147 tools loaded
"name": "updateLastSeenMessageId",
"name": "updateMessage",
"name": "deleteMessage",
"name": "showWorkout",
"name": "updateWorkout",
"name": "deleteWorkout",
"name": "getRecord",
"name": "updateWellness",
"name": "updateWellnessBulk",
"name": "uploadWellness",
```
按 Ctrl-C 退出。服务器现在已准备好接受中间客户端的驱动。
## 缩小工具范围（适用于小型/本地模型）
完整规范生成了 147 个工具。较小的模型（`qwen2.5:7b`、`llama3.1:8b`，...）难以从这么多工具中选择。编辑 `config.js` 进行筛选：
```js
export const METHODS = ["GET"]; // 只读服务器
export const TAGS = ["Activity", "Wellness"]; // 仅限这些 OpenAPI 标签
export const INCLUDE = ["getActivities", "getWellness"]; // 精确允许列表
export const EXCLUDE = ["someNoisyTool"];
export const DESCRIPTION_STYLE = "short"; // 简洁的单行描述（vs "full"）
```
筛选器按顺序应用：`METHODS` → `TAGS` → `INCLUDE` → `EXCLUDE`。编辑后重启服务器。Claude 可以轻松处理所有 147 个工具；对于 Ollama/mcphost/Tome 的小型模型，请保持在 ~20 个工具以下。
## Claude Desktop
编辑 Claude Desktop 配置文件（如果不存在，请创建）：
- MacOS - `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux - `~/.config/Claude/claude_desktop_config.json`
- Windows - `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"intervals-icu": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/local/mcp-stdio.mjs"],
"env": { "INTERVALS_TOKEN": "your_api_key_here" }
}
}
}
```
如果您已经在 `config.js` 中设置了 `INTERVALS_TOKEN`，则 `env` 块是可选的。重启 Claude Desktop。现在 Intervals.icu 工具已可用。
## Ollama / OpenRouter（通过 mcphost）
[mcphost](https://github.com/mark3labs/mcphost) 是一个小型 CLI 工具，可以桥接任意中间服务器到 Ollama 或 OpenRouter 模型。
> Ollama 模型建议：
- qwen3 或 qwen2.5-coder:32b（如果您的机器可以运行）
- llama3.1:8b — 在工具调用方面出乎意料地稳健
- mistral-small3.1 / mistral-nemo — 为函数调用训练过
> OpenRouter 模型建议：
- anthropic/claude-3.5-sonnet，openai/gpt-4o-mini，google/gemini-2.0-flash
```bash
# 安装
go install github.com/mark3labs/mcphost@latest
# 配置：~/.config/mcphost.intervals.json
{
"mcpServers": {
"intervals-icu": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/local/mcp-stdio.mjs"],
"env": { "INTERVALS_TOKEN": "your_api_key_here" }
}
}
}
# 使用 Ollama 运行
mcphost -m ollama:qwen2.5 --config ~/.config/mcphost.intervals.json
# 或使用 OpenRouter
mcphost -m openrouter:anthropic/claude-3.5-sonnet
```
> 如果您更喜欢桌面应用程序而不是 CLI，您可以使用 [Tome](https://github.com/runebookai/tome)，它提供了添加中间服务器的直接配置。
## 身份验证
Intervals.icu 使用 HTTP 基本身份验证。服务器发送：
```
Authorization: Basic base64("API_KEY:${INTERVALS_TOKEN}")
```
这与官方的 `curl -u "API_KEY:TOKEN"` 样式匹配。如果您的令牌已经包含冒号（例如 `myuser:mytoken`），则原样使用。
## 故障排除
- **`INTERVALS_TOKEN 未设置`** — 在 `config.js` 中设置或将其导出为环境变量。
- **`HTTP 401`** — 令牌错误或过期。在 <https://intervals.icu/settings> 处重新生成。
- **Claude 中找不到工具** — 编辑配置文件后完全重启 Claude Desktop。
