MCP-OS · 模型上下文协议编排系统

让大型语言模型专注于解决问题，而不是在MCP的海洋中挣扎。

👉 查看中文版 README

---

✨ 项目愿景

随着**模型上下文协议（MCP）**生态系统的发展，数百个MCP服务器带来了三个熟悉的痛点：

痛点	描述
提示膨胀	长篇的MCP描述占据了上下文窗口；模型花费更多的令牌来选择工具而不是进行规划/分析。
连接卫生	我们必须不断追踪哪些MCP是活跃的以及它们是否满足当前任务。
资源与安全	始终在线的MCP服务器消耗内存并暴露接口，增加了攻击面。

MCP-OS旨在：

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

---

🌟 当前阶段：MCP检索器（已完成 ✅）

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

📖 详情见/packages/retriever。

---

🛣️ 发展路线图

里程碑	特性	状态
v0.1	MCP检索器 – 向量搜索	✅ 已发布
v0.2	MCP检索器 - 轻量版本	⏳ 进行中
v0.3	健康检查守护程序 – 自动心跳及修剪	⏳ 进行中
v0.4	运行时管理器 – 按需启动/停止MCP	🗓 计划中
v1.0	策略沙箱 – 细粒度认证、速率限制、成本控制	🗓 计划中

---

⚙️ 快速开始

1. 克隆并安装

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

2. 构建向量索引

# 扫描本地/远程MCP元数据并创建索引
npm run build:index --src ./mcp_list.json --out ./index

3. 启动检索器服务器

npm run start:retriever
# 默认监听127.0.0.1:5500（HTTP + SSE）

4. 将其集成到您的LLM/代理中

// 示例：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": "抓取网页并提取标题"}'

示例响应：

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

---

📂 仓库布局

mcp-os/
├─ packages/
│  ├─ retriever/        # 第一阶段：向量检索
│  ├─ health-check/     # 第二阶段：心跳守护程序（进行中）
│  └─ runtime-manager/  # 第三阶段：加载/卸载（计划中）
├─ scripts/             # CLI辅助工具
├─ examples/            # 使用示例
└─ docs/                # 架构及深入探讨

---

🧩 MCP列表格式

mcp_list.json描述了MCP元数据：

{
  "web-scraper": {
    "name": "Web Scraper MCP",
    "description": "抓取HTML并解析DOM。",
    "functions": ["fetchHtml", "querySelector"]
  },
  "calc": { ... }
}

---

❓ 常见问题

<details> <summary>检索质量差，如何调整？</summary>

• 提高topK以获得更高的召回率。
• 切换到更强的嵌入模型。
• 优化任务文本规范化规则。

</details> <details> <summary>如何插入自己的向量存储？</summary>

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

</details>

---

🤝 贡献指南

1. 分叉此仓库
2. 创建一个分支feature/awesome-stuff
3. 打开PR并链接相关问题
4. 等待CI+审查🎉

---

📜 许可证

Apache License v2

---

🙏 致谢

• 模型上下文协议社区，提供开放规范
• MCP Inspector，用于调试
• 所有提交问题或PR的人——感谢你们！❤️