MCP-OS · Model Context Protocol Orchestration System

MCP-OS · Model Context Protocol Orchestration System

Let your large language model focus on solving tasks—not wading through a sea of MCPs.

👉 查看中文版 README

---

✨ Project Vision

As the Model Context Protocol (MCP) ecosystem explodes, hundreds of MCP servers create three familiar headaches:

Pain Point	Description
Prompt Bloat	Lengthy MCP descriptions crowd the context window; the model spends more tokens picking tools than planning / analysis.
Connection Hygiene	We must constantly track which MCPs are alive and whether they satisfy the current task.
Resource & Security	Always-on MCP servers consume memory and expose interfaces, increasing attack surface.

MCP-OS aims to:

“Manage MCPs the way an operating system manages processes—load on demand, unload when idle.”

---

🌟 Current Phase: MCP-Retriever (Completed ✅)

1. Vector Retrieval — Embed task descriptions and retrieve Top-k MCPs from a vector index.
2. Slim Prompt Template — Inject only the Top-k MCP descriptions, saving ~70 % prompt tokens on average.
3. Pluggable Back-ends — Default openai/embeddings; swap in FAISS, Qdrant, Milvus, etc.

📖 Details in /packages/retriever.

---

🛣️ Roadmap

Milestone	Feature	Status
v0.1	MCP-Retriever – vector search	✅ Released
v0.2	MCP-Retriever - light version	⏳ In progress
v0.3	Health-Check Daemon – auto heartbeat & pruning	⏳ In progress
v0.4	Runtime Manager – on-demand MCP start/stop	🗓 Planned
v1.0	Policy Sandbox – fine-grained auth, rate, cost	🗓 Planned

---

⚙️ Quick Start

1. Clone & Install

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

2. Build the Vector Index

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

3. Start the Retriever Server

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

4. Wire It into Your LLM / Agent

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

Or call the REST endpoint:

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

Sample response:

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

---

📂 Repository Layout

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 List Format

mcp_list.json describes MCP metadata:

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

---

❓ FAQ

Retrieval quality is poor—how do I tune it?

• Increase topK for higher recall.
• Switch to a stronger embedding model.
• Refine task-text normalization rules.

How do I plug in my own vector store?

Implement the VectorStore interface: src/store/yourStore.ts.

---

🤝 Contributing

1. Fork the repo
2. Create a branch feature/awesome-stuff
3. Open a PR and link related issues
4. Wait for CI + review 🎉

---

📜 License

Apache License v2

---

🙏 Acknowledgements

• The Model Context Protocol community for the open specification
• MCP Inspector for debugging
• Everyone who files issues or PRs—thank you! ❤️