MCP-OS · Model Context Protocol Orchestration System

MCP-OS · Model Context Protocol 编排系统

让你的大模型专注于解决任务，而不是在 MCP 的海洋中摸索。

👉 查看中文版 README

---

✨ 项目愿景

随着 Model Context Protocol（MCP） 生态蓬勃发展，数百个 MCP 服务带来了三个常见难题：

痛点	描述
提示词膨胀	冗长的 MCP 描述挤占上下文窗口；模型花在挑选工具上的 token 比花在规划／分析上的还多。
连接管理	我们必须持续跟踪哪些 MCP 服务处于活动状态，以及它们是否满足当前任务的需求。
资源与安全	始终运行的 MCP 服务会占用内存并暴露接口，从而扩大攻击面。

MCP-OS 的目标是：

“像操作系统管理进程那样管理 MCP——按需加载，空闲时卸载。”

---

🌟 当前阶段：MCP-Retriever（已完成 ✅）

1. 向量检索 — 嵌入任务描述，并从向量索引中检索 Top-k 个 MCP。
2. 精简提示词模板 — 仅注入 Top-k 个 MCP 描述，平均节省约 70 % 的提示词 token。
3. 可插拔后端 — 默认使用 openai/embeddings；可替换为 FAISS、Qdrant、Milvus 等。

📖 详情请参阅 /packages/retriever。

---

🛣️ 路线图

里程碑	功能	状态
v0.1	MCP-Retriever – 向量搜索	✅ 已发布
v0.2	MCP-Retriever - 轻量版	⏳ 进行中
v0.3	健康检查守护进程 – 自动心跳与清理	⏳ 进行中
v0.4	运行时管理器 – 按需启动／停止 MCP	🗓 计划中
v1.0	策略沙箱 – 精细化授权、速率与成本控制	🗓 计划中

---

⚙️ 快速开始

1. 克隆并安装

git clone https://github.com/your-org/mcp-os.git
cd mcp-os
npm install      # or npm / yarn

2. 构建向量索引

# Scan local / remote MCP metadata and create an index
npm run build:index --src ./mcp_list.json --out ./index

3. 启动检索器服务

npm run start:retriever
# Default listens on 127.0.0.1:5500 (HTTP + SSE)

4. 将其接入你的大模型／Agent

// Example: Claude Desktop
{
  "mcpServers": {
    "mcp-os": {
      "command": "/absolute/path/to/mcp-os/bin/retriever.js"
    }
  }
}

或者调用 REST 端点：

curl -X POST http://localhost:5500/match \
  -H "Content-Type: application/json" \
  -d '{"task": "Scrape a web page and extract its title"}'

示例响应：

{
  "matches": [
    {
      "id": "web-scraper",
      "score": 0.89,
      "functions": ["fetchHtml", "querySelector"]
    }
  ]
}

---

📂 仓库结构

mcp-os/
├─ packages/
│  ├─ retriever/        # Phase 1: vector retrieval
│  ├─ health-check/     # Phase 2: heartbeat daemon (WIP)
│  └─ runtime-manager/  # Phase 3: load/unload (planned)
├─ scripts/             # CLI helpers
├─ examples/            # Usage demos
└─ docs/                # Architecture & deep dives

---

🧩 MCP 列表格式

mcp_list.json 描述 MCP 元数据：

{
  "web-scraper": {
    "name": "Web Scraper MCP",
    "description": "Fetches HTML and parses DOM.",
    "functions": ["fetchHtml", "querySelector"]
  },
  "calc": { ... }
}

---

❓ 常见问题

检索效果不佳——如何调整？

• 提高 topK 以提升召回率。
• 换用更强大的嵌入模型。
• 优化任务文本规范化规则。

如何接入我自己的向量存储？

实现 VectorStore 接口：src/store/yourStore.ts。

---

🤝 参与贡献

1. Fork 此仓库
2. 创建分支 feature/awesome-stuff
3. 提交 PR 并关联相关问题
4. 等待 CI 和评审 🎉

---

📜 许可证

Apache License v2

---

🙏 致谢

• 感谢 Model Context Protocol 社区制定开放规范
• 感谢 MCP Inspector 提供调试工具
• 感谢所有提交问题或 PR 的人！❤️