使用说明

MCP技能框架

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

概述

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

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

主要优势

大规模代币减少：代理可以看到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 << 'EOF'
{
  "servers": [
    {
      "name": "filesystem",
      "command": "npx -y @modelcontextprotocol/server-filesystem /tmp"
    },
    {
      "name": "github",
      "command": "npx -y @modelcontextprotocol/server-github"
    }
  ]
}
EOF

# 2. Run code generation
mcp-generate mcp-servers.json

# 3. Commit the generated code
git add servers/
git commit -m "Add MCP server wrappers"

这将创建 servers/ 您的代理商将进口的包裹。仅在添加/更改MCP服务器时重新运行。

替代：直接使用Python API：

from src.cli import generate_servers

generate_servers(
    servers=[
        {"name": "filesystem", "command": "npx -y @modelcontextprotocol/server-filesystem /tmp"}
    ],
    servers_dir="servers"
)

它产生了什么：

servers/
├── filesystem/
│   ├── read_file/
│   │   ├── main.py              # Python function wrapper
│   │   ├── README.md            # Tool documentation
│   │   └── __init__.py
│   └── write_file/
└── google_drive/
    └── list_files/

第二步：建立你的代理

您的代理代码从生成的 servers/ 包裹：

# my_agent.py
from servers.filesystem.read_file import filesystem_read_file

# Use in your agent
content = filesystem_read_file("/tmp/test.txt")

步骤3：运行您的代理

这 servers/ 包现在像任何Python库一样可用：

python my_agent.py

快速入门（代理运行时）

一旦你生成了 servers/ 软件包（请参阅上面的开发人员工作流程）：

import asyncio
from src import MCPApi

async def main():
    # Initialize API with agent name (required)
    api = MCPApi(
        agent_name="my-agent",
        servers_dir="servers",
        skills_dir="skills",
        skills_db="skills.db"
    )

    # === HYDRATE SKILLS FROM DATABASE ===
    # Restore skills from database
    count = await api.hydrate_skills()
    print(f"Loaded {count} skills from previous sessions")

    # Start MCP runtime
    api.start()

    # === AGENT CREATES NEW SKILLS ===
    # Agent writes code using generated APIs
    skill_code = '''
from servers.filesystem.read_file import filesystem_read_file

def count_lines(filepath):
    """Count lines in a file."""
    content = filesystem_read_file(filepath)
    return len(content.split('\\n'))
'''

    # Save as skill (immediately available + persisted to DB)
    api.save_skill(
        code=skill_code,
        name="count_lines",
        category="file_operations",
        tags=["filesystem", "utility"]
    )

    # List all skills
    skills = api.list_skills()
    print(f"Total skills: {len(skills)}")

    # Get database stats
    stats = await api.get_skill_stats()
    print(f"Skills in database: {stats['total_skills']}")

    # Cleanup
    api.stop()

asyncio.run(main())

核心概念

1.代码生成

该框架为每个MCP工具生成Python包装器函数：

# MCP tool schema (verbose, many tokens)
{
  "name": "list_files",
  "description": "List files in directory",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {"type": "string"}
    }
  }
}

# Generated Python API (clean, few tokens)
def google_drive_list_files(path: str) -> dict:
    """List files in directory."""
    return mcp_call('google_drive', 'list_files', {'path': path})

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

2.技能坚持

当代理保存技能时：

立即写入文件系统 (skills/{category}/{name}/)
- 代理商可以立即导入和使用
- 包括main.py、README.md、元数据
异步持久化到数据库
- 以（agent_name，skill_name）为关键字的SQLite数据库
- 容器重启和代理会话幸存
启动时的水合作用
- 数据库是真理的源泉
- 清理和重建 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直接使用的比较

方面	MCP直接	此框架
上下文使用	~500个令牌/工具	~50个令牌/刀具
代理接口	JSON模式	Python函数
技能持久性	无	SQLite数据库
多会话	无内存	数据库水合
发现	浏览所有模式	探索文件系统
类型安全	JSON验证	Python类型提示

贡献

欢迎投稿！请确保：

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

许可证

麻省理工学院

致谢

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

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