MCP On Demand

MCP按需

](https://www.npmjs.com/package/mcp-on-demand) ](https://www.npmjs.com/package/mcp-on-demand) 

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

对于人类

这有什么作用： 使用任何没有永久上下文污染的MCP服务器。

开始：

• 创建命令 -构建 /commands 使用MCP按需
• 创造技能 -培养使用MCP On Demand的自动激活技能

对于LLMs

先决条件

1. Node.js 22+ 是必需的
2. MCP服务器 必须预先安装在用户的系统上
3. MCP按需 必须安装和配置

安装

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

1. 在全球范围内按需安装mcp

   npm install -g mcp-on-demand

安装程序会自动运行安装程序，该程序会创建 ~/.mcp-on-demand/installation.json 使CLI自动定位。这允许您使用 mcp-on-demand 来自任何地方的命令。

1. 创建配置文件

创建 ~/.mcp-on-demand/mcp-configs.json 用户的MCP安装路径：

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

向用户询问他们的MCP安装路径。 不要假设地点。

1. 就是这样！ 当您运行任何命令时，会话管理器会自动启动。

要手动检查状态，请执行以下操作：

   mcp-on-demand status

手动启动（仅用于故障排除）：

   mcp-on-demand manager &

配置格式

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

{
  "mcp-name": {
    "command": "executable",
    "args": ["/absolute/path/to/mcp/entrypoint.js", "additional", "args"]
  }
}

示例：

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", "value"]
  }
}

使用模式

使用 mcp-on-demand CLI与MCP会话交互。CLI通过上的HTTP API与会话管理器通信 http://127.0.0.1:9876.

检查状态：

mcp-on-demand status

启动MCP会话：

mcp-on-demand start chrome-devtools-mcp

发现可用工具

当您启动MCP会话时，可用的工具会自动显示其完整模式：

mcp-on-demand start chrome-devtools-mcp

输出示例：

{
  "success": true,
  "mcpName": "chrome-devtools-mcp",
  "toolCount": 15,
  "message": "Session started with 15 tools",
  "tools": [
    {
      "name": "navigate_page",
      "description": "Navigate to a URL",
      "inputSchema": { ... }
    },
    ...
  ]
}

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

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

mcp-on-demand start chrome-devtools-mcp --no-show-tools

呼叫工具：

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

批量呼叫：

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

停止会话：

mcp-on-demand stop chrome-devtools-mcp

列出活动会话：

mcp-on-demand list

关闭会话管理器：

mcp-on-demand shutdown

文件引用与文件：//

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

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

发生了什么：

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

支持的路径：

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

适用于所有地方： 文件解析递归遍历args中的所有对象和数组。

API 参考

所有请求都是POST到 http://127.0.0.1:9876 使用JSON有效载荷。

行动：

响应格式：

成功：

{"success": true, ...}

错误：

{"error": "error message"}

示例：Web调试工作流

# Start chrome-devtools-mcp session (daemon auto-starts if needed)
mcp-on-demand start chrome-devtools-mcp

# Execute debugging workflow
mcp-on-demand batch 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"}}
]'

# Stop session when done
mcp-on-demand stop chrome-devtools-mcp

代币管制

• 本地MCP：每个MCP在上下文中永久拥有5000多个令牌
• MCP按需：不使用时为0个令牌，会话活动时仅为~5000个令牌
• 每次通话开销：相同（约30个令牌）
• 价值：使用10+MCP，无永久上下文成本

错误处理

常见错误：

会话弹性：

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

建筑

┌─────────────────┐
│   Client/LLM    │ (Claude Code, mcp-on-demand CLI)
└────────┬────────┘
         │ HTTP POST :9876
         │
┌────────▼────────────────────┐
│  Session Manager            │
│  - Loads ~/.mcp-on-demand/  │
│    mcp-configs.json         │
│  - Manages MCP sessions     │
│  - Routes tool calls        │
│  - Resolves file:// refs    │
└────────┬────────────────────┘
         │ stdio transport
         │
┌────────▼────────────────────┐
│  MCP Server(s)              │
│  (chrome-devtools-mcp, etc) │
└─────────────────────────────┘

文件结构

mcp-on-demand/
├── src/
│   └── session-manager.js         # Main HTTP server & MCP client
├── bin/
│   └── mcp-on-demand.js           # CLI executable
├── scripts/
│   ├── mcp-call.js                # Helper script for tool calls
│   └── setup.js                   # Setup script for installation.json
├── mcp-configs.example.json       # Example configuration
├── package.json
└── README.md

用户配置：

~/.mcp-on-demand/
├── installation.json              # CLI self-location (auto-generated by npm run setup)
├── mcp-configs.json               # User's MCP paths (required)
└── session.json                   # Runtime state (auto-generated)

平台说明

Windows（MSYS/Git Bash）：

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

macOS/Linux：

• 标准Unix路径
• 考虑 nohup 用于后台会话管理器

故障排除

检查守护进程状态：

mcp-on-demand status

会话管理器没有响应？

# The daemon auto-starts, but if you have issues:
mcp-on-demand shutdown  # Stop any existing daemon
rm ~/.mcp-on-demand/session.json  # Clean up stale session file
mcp-on-demand start   # Will auto-start fresh daemon

MCP无法启动？

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

端口9876正在使用中？

• 改变 PORT 常数in src/session-manager.js:12

工具调用超时？

• 会话仍能正常工作-重试调用
• 如果持续存在，请考虑重新启动会话

设计理念

关注点分离：

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

通用适配器模式：

• 适用于任何MCP服务器的标准化HTTP API
• 在不更改客户端代码的情况下交换MCP服务器
• 适用于任何基于stdio的MCP实现

零开销：

• 会话不活动时无令牌成本
• 会话根据需要启动/停止
• 支持多个并发会话

许可证

麻省理工学院

相关项目

• 模型上下文协议
• Chrome开发工具MCP
• MCP-SDK