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 ✅)

Vector Retrieval — Embed task descriptions and retrieve Top-k MCPs from a vector index.
Slim Prompt Template — Inject only the Top-k MCP descriptions, saving ~70 % prompt tokens on average.
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

Fork the repo
Create a branch feature/awesome-stuff
Open a PR and link related issues
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! ❤️

MCP Servers