按需MCP服务器

Name: 按需MCP服务器
Author: mfagerlund

作者：mfagerlund3 星标更新：2025-11-13

安装使用来源：spider==github.com

项目介绍

MCP 按需服务

一个轻量级的HTTP会话管理器，用于模型上下文协议（MCP）服务器。按需加载MCP服务器而不是永久保持在上下文中。不使用时零令牌开销。

对于人类用户

功能： 使用任何MCP服务器而不造成永久的上下文污染。

开始使用：

创建命令 - 构建使用MCP按需服务的/commands
创建技能 - 构建自动激活的技能，使用MCP按需服务

对于大语言模型（LLMs）

预备条件

需要Node.js 22+
用户系统上必须预安装MCP服务器
必须安装并配置MCP-on-demand

安装

重要提示： 本文档假设MCP服务器已经安装在系统上。

全局安装mcp-on-demand
```
npm install -g mcp-on-demand
```
安装过程会自动运行设置，创建~/.mcp-on-demand/installation.json，使CLI能够自我定位。这允许您从任何地方使用mcp-on-demand命令。
创建配置文件

创建~/.mcp-on-demand/mcp-configs.json，包含用户的MCP安装路径：
```
{
  "chrome-devtools-mcp": {
    "command": "node",
    "args": ["/绝对路径/to/chrome-devtools-mcp/build/src/index.js"]
  }
}
```
询问用户他们的MCP安装路径。 不要假设位置。
就这样！ 当您运行任何命令时，会话管理器会自动启动。

手动检查状态：
```
mcp-on-demand 状态
```
手动启动（仅用于故障排除）：
```
mcp-on-demand 管理器 &
```

配置格式

~/.mcp-on-demand/mcp-configs.json文件将MCP名称映射到它们的启动命令：

{
  "mcp-name": {
    "command": "可执行文件",
    "args": ["/绝对路径/to/mcp/入口点.js", "附加参数"]
  }
}

示例：

Node.js MCP：

{
  "chrome-devtools-mcp": {
    "command": "node",
    "args": ["C:/Dev/chrome-devtools-mcp/build/src/index.js"]
  }
}

Python MCP：

{
  "example-python-mcp": {
    "command": "python3",
    "args": ["/home/user/mcp-servers/example/main.py"]
  }
}

二进制MCP：

{
  "example-binary-mcp": {
    "command": "/usr/local/bin/example-mcp",
    "args": ["--flag", "值"]
  }
}

使用模式

使用mcp-on-demand CLI与MCP会话交互。CLI通过HTTP API与会话管理器通信，地址为http://127.0.0.1:9876。

检查状态：

mcp-on-demand 状态

启动MCP会话：

mcp-on-demand 启动 chrome-devtools-mcp

发现可用工具

当您启动一个MCP会话时，可用工具会自动显示，并带有完整的模式：

mcp-on-demand 启动 chrome-devtools-mcp

输出示例：

{
  "success": true,
  "mcpName": "chrome-devtools-mcp",
  "toolCount": 15,
  "message": "会话启动，包含15个工具",
  "tools": [
    {
      "name": "navigate_page",
      "description": "导航到一个URL",
      "inputSchema": { ... }
    },
    ...
  ]
}

最佳实践： 查看工具输出以了解MCP提供的能力，然后根据任务使用适当的工具。这确保您始终使用当前的工具集及其实际模式。

隐藏工具列表： 使用--no-show-tools来抑制工具输出：

mcp-on-demand 启动 chrome-devtools-mcp --no-show-tools

调用工具：

mcp-on-demand 调用 chrome-devtools-mcp navigate_page '{"url": "https://example.com"}'

批量调用：

mcp-on-demand 批处理 chrome-devtools-mcp '[
  {"tool": "navigate_page", "args": {"url": "https://example.com"}},
  {"tool": "take_screenshot", "args": {"format": "png"}}
]'

停止会话：

mcp-on-demand 停止 chrome-devtools-mc

列出活动会话：

mcp-on-demand 列表

关闭会话管理器：

mcp-on-demand 关闭

文件引用使用file://

会话管理器自动解析工具参数中的file://引用：

mcp-on-demand 调用 chrome-devtools-mcp evaluate_script '{
  "function": "file://./scripts/check-buttons.js"
}'

发生的过程：

会话管理器检测到file://前缀
从磁盘读取文件内容
将字符串替换为文件内容
使用解析后的内容执行工具调用

支持的路径：

相对路径：file://./script.js（相对于会话管理器的工作目录）
绝对路径：file:///绝对路径/to/script.js

适用于所有情况： 文件解析递归遍历参数中的所有对象和数组。

API参考

所有请求都是POST到http://127.0.0.1:9876，带有JSON负载。

操作：

操作	参数	描述
`启动`	`mcpName`（必需），`showTools`（可选，默认：true）	启动MCP会话
`调用`	`mcpName`，`toolName`，`args`	调用单个工具
`批处理`	`mcpName`，`toolCalls`（数组）	顺序调用多个工具
`停止`	`mcpName`	停止MCP会话
`列表`	（无）	列出活动会话
`关闭`	（无）	关闭会话管理器

响应格式：

成功：

{"success": true, ...}

错误：

{"error": "错误信息"}

示例：Web调试工作流

# 启动chrome-devtools-mcp会话（如果需要，守护进程会自动启动）
mcp-on-demand 启动 chrome-devtools-mcp

# 执行调试工作流
mcp-on-demand 批处理 chrome-devtools-mcp '[
  {"tool": "navigate_page", "args": {"url": "https://example.com"}},
  {"tool": "evaluate_script", "args": {"function": "file://./check-buttons.js"}},
  {"tool": "take_screenshot", "args": {"filePath": "./screenshot.png"}}
]'

# 完成后停止会话
mcp-on-demand 停止 chrome-devtools-mcp

令牌经济学

原生MCP：每个MCP永久在上下文中有5000+令牌
MCP按需服务：不使用时0令牌，会话激活时约5000令牌
每次调用开销：相同（约30令牌）
价值：使用10+ MCP而无需永久上下文成本

错误处理

常见错误：

错误	原因	解决方案
`未知MCP: xyz`	MCP不在配置中	添加到`~/.mcp-on-demand/mcp-configs.json`
`会话xyz已运行`	重复启动	使用现有会话或先停止
`没有活动的xyz会话`	会话未启动	先调用`启动`动作
`无法读取文件: ENOENT`	文件未找到	检查`file://`路径
连接被拒绝	会话管理器未运行	启动会话管理器

会话韧性：

错误的请求不会破坏会话
工具调用失败不会使会话失效
会话是独立的，可以重新启动

架构

┌─────────────────┐
│   客户端/LLM    │ (Claude Code, mcp-on-demand CLI)
└────────┬────────┘
         │ HTTP POST :9876
         │
┌────────▼────────────────────┐
│  会话管理器                │
│  - 加载 ~/.mcp-on-demand/  │
│    mcp-configs.json         │
│  - 管理会话                │
│  - 路由工具调用            │
│  - 解析file://引用         │
└────────┬────────────────────┘
         │ 标准IO传输
         │
┌────────▼────────────────────┐
│  MCP服务器                  │
│  (chrome-devtools-mcp, 等)  │
└─────────────────────────────┘

文件结构

mcp-on-demand/
├── src/
│   └── session-manager.js         # 主HTTP服务器及MCP客户端
├── bin/
│   └── mcp-on-demand.js           # CLI可执行文件
├── scripts/
│   ├── mcp-call.js                # 工具调用辅助脚本
│   └── setup.js                   # 安装脚本，生成installation.json
├── mcp-configs.example.json       # 示例配置
├── package.json
└── README.md

用户配置：

~/.mcp-on-demand/
├── installation.json              # CLI自定位（由npm run setup自动生成）
├── mcp-configs.json               # 用户的MCP路径（必需）
└── session.json                   # 运行时状态（自动生成）

平台说明

Windows（MSYS/Git Bash）：

使用正斜杠：C:/Dev/chrome-devtools-mcp/...
在MSYS/Git Bash环境中正确工作

macOS/Linux：

标准Unix路径
考虑使用nohup在后台运行会话管理器

故障排除

检查守护进程状态：

mcp-on-demand 状态

会话管理器无响应？

# 守护进程会自动启动，但如果有问题：
mcp-on-demand 关闭  # 停止任何现有的守护进程
rm ~/.mcp-on-demand/session.json  # 清理过期的会话文件
mcp-on-demand 启动 <mcp-name>  # 将会自动启动新的守护进程

MCP无法启动？

检查配置是否存在：cat ~/.mcp-on-demand/mcp-configs.json
验证MCP路径：ls /path/to/mcp/index.js
检查Node.js版本：node --version（需要v22+）
直接测试MCP：node /path/to/mcp/index.js

端口9876已被占用？

更改src/session-manager.js:12中的PORT常量

工具调用超时？

会话仍然有效 - 重试调用
如果持续存在，考虑重启会话

设计理念

关注分离：

MCP-on-demand不安装或管理MCP服务器
用户维护自己的MCP安装
会话管理器仅提供运行时编排

通用适配器模式：

任何MCP服务器的标准HTTP API
无需更改客户端代码即可交换MCP服务器
适用于任何基于标准IO的MCP实现

零开销：

会话不活跃时无令牌成本
按需启动/停止会话
支持多个并发会话

许可证

MIT