MCP API Experiment

MCP技能框架

一个用于使用MCP构建代理的代码生成和技能持久性框架。

概述

MCP技能框架将MCP（模型上下文协议）工具转换为特定领域的Python API，并为代理提供持久的技能存储。该框架没有将代理暴露于冗长的MCP工具模式，而是：

1. 生成干净的Python API 来自MCP服务器配置
2. 使代理能够编写可重用的代码 使用这些API
3. 将技能应用于SQLite数据库 用于跨会话知识保留
4. 在创业时补充水分 因此，代理可以立即使用积累的知识
5. 支持多代理隔离 具有特定于代理的技能命名空间

主要优势

• 大规模代币减少：代理可以看到Python API，而不是冗长的工具模式
• 渐进式披露：代理通过文件系统按需探索API
• 技能积累：代理通过保存工作代码随着时间的推移积累知识
• 数据库持久性：技能在代理重启和容器重建中幸存下来
• 多代理支持：多个代理可以共享一个具有独立技能的数据库
• 框架无关：适用于任何代理框架（LangGraph、CrewAI等）

建筑

┌─────────────────────────────────────────────────────────────┐
│ Developer Workflow (One-time)                               │
├─────────────────────────────────────────────────────────────┤
│ 1. Configure MCP servers                                    │
│ 2. Run code generation                                      │
│ 3. Commit servers/ package to git                           │
└─────────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│ Agent Runtime (Every session)                               │
├─────────────────────────────────────────────────────────────┤
│ 1. Hydrate skills from database → skills/                  │
│ 2. Import generated APIs from servers/                     │
│ 3. Import existing skills from skills/                     │
│ 4. Create new skills → save to skills/ + persist to DB     │
└─────────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│ Storage                                                      │
├─────────────────────────────────────────────────────────────┤
│ • servers/        → Git (committed with agent code)         │
│ • skills/         → Ephemeral (regenerated from DB)         │
│ • skills.db       → SQLite (source of truth for skills)     │
└─────────────────────────────────────────────────────────────┘

安装

# Install in development mode
pip install -e .

# Or install with dev dependencies
pip install -e ".[dev]"

开发人员工作流程

步骤1：生成MCP服务器包装器（一次性）

在运行代理之前，为MCP服务器生成Python包装器：

# 1. Configure your MCP servers in mcp-servers.json
cat > mcp-servers.json  dict:
    """List files in directory."""
    return mcp_call('google_drive', 'list_files', {'path': path})

生成的API保存到 servers/{server_name}/{tool_name}/main.py.

2.技能坚持

当代理保存技能时：

1. 立即写入文件系统 (skills/{category}/{name}/)

- 代理商可以立即导入和使用 - 包括main.py、README.md、元数据

1. 异步持久化到数据库

- 以（agent_name，skill_name）为关键字的SQLite数据库 - 容器重启和代理会话幸存

1. 启动时的水合作用

- 数据库是真理的源泉 - 清理和重建 skills/ DB中的目录 - 确保会话之间的一致性

3.多代理支持

多个代理可以共享一个数据库：

# Agent 1
api1 = MCPApi(agent_name="agent-1", skills_db="shared.db")
api1.save_skill(code, "skill1", "category1")

# Agent 2
api2 = MCPApi(agent_name="agent-2", skills_db="shared.db")
api2.save_skill(code, "skill2", "category2")

# Isolated: agent-1 only sees skill1, agent-2 only sees skill2

目录结构

your-agent-project/
├── servers/              # Generated MCP APIs (commit to git)
│   ├── filesystem/
│   │   ├── read_file/
│   │   │   ├── main.py
│   │   │   └── README.md
│   │   └── write_file/
│   └── google_drive/
│
├── skills/               # Agent skills (ephemeral, from DB)
│   ├── file_operations/
│   │   ├── count_lines/
│   │   │   ├── main.py
│   │   │   ├── README.md
│   │   │   ├── __init__.py
│   │   │   └── .meta.json
│   │   └── get_file_size/
│   └── data_processing/
│
├── skills.db             # SQLite database (source of truth)
│
└── your_agent.py         # Your agent code

API 参考

MCPApi

api = MCPApi(
    agent_name: str,                    # Required: Agent identifier
    servers_dir: str = "servers",       # Generated API directory
    skills_dir: str = "skills",         # Skills directory
    skills_db: str = "skills.db",       # SQLite database path
    telemetry_db: Optional[str] = ...   # Telemetry database (optional)
)

方法

代码生成

• add_mcp_server(name, command) -注册MCP服务器
• generate_libraries() -从所有服务器生成Python API

运行时管理

• start() -连接到MCP服务器
• stop() -断开与MCP服务器的连接

技能管理

• save_skill(code, name, category, tags=None, persist_to_db=True) -保存技能
• list_skills(category=None) -从文件系统中列出技能
• get_skill_info(category, name) -获取详细的技能信息
• await hydrate_skills() -从数据库还原技能（异步）
• await get_skill_stats() -获取数据库统计信息（异步）

示例

请参阅 examples/ 目录：

• basic_usage.py -完成工作流程演练
• skill_persistence_demo.py -展示水合作用和多智能体支持

运行示例：

python examples/basic_usage.py
python examples/skill_persistence_demo.py

测试

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src --cov-report=html

发展

# Install with dev dependencies
pip install -e ".[dev]"

# Format code
black src/ tests/

# Lint
ruff check src/ tests/

# Type check
mypy src/

用例

该框架非常适合：

• 自治代理 需要随着时间的推移积累知识
• 多会话工作流 在重启过程中，技能应该持续存在
• 多智能体系统 共享技能数据库
• 工具重剂 受益于清洁的API包装
• 开发团队 希望将生成的代码提交到git

设计决策

为什么数据库持久化？

• 技能在容器重启和代理崩溃中幸存下来
• 实现多代理知识共享
• 提供可查询的技能元数据
• 支持未来的功能（技能版本控制、分析）

为什么是即时文件系统+异步数据库？

• 代理可以立即使用技能（无需等待数据库写入）
• 非阻塞持久性使代理保持响应
• 文件系统作为工作目录
• 数据库是持久的真相来源

为什么要清除和重建水合作用？

• 数据库是唯一的事实来源（没有同步冲突）
• 简单、可预测的行为
• 确保会话之间的一致性

与MCP直接使用的比较

贡献

欢迎投稿！请确保：

• 测试通过： pytest tests/
• 代码的格式为： black src/ tests/
• 类型正确： mypy src/

许可证

麻省理工学院

致谢

建在上面 模型上下文协议（MCP） 通过Anthropic。

受文章启发： 构建高效代理