AI导哈

模型上下文协议代理框架

一个用于构建模型上下文协议（MCP）代理的模块化基础设施，提供核心构建块如传输层、服务架构、配置管理和工具抽象，适用于生产级MCP系统的开发和维护。

  • by imraf
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 imraf/multiagent-mcp

使用说明

MCP代理基金会

用于构建模型上下文协议（MCP）代理的强大模块化基础设施。

该项目提供了编排智能代理所需的核心构建块——传输层、服务架构、配置管理和工具抽象。它专为可扩展性和可维护性而设计，可作为构建生产级MCP系统的参考实现。

🏗️ 架构概述

该项目围绕关注点的清晰分离进行构建，确保域逻辑、基础设施和传输层保持解耦。

graph TD
    subgraph "Client Layer"
        CLI["CLI (mcp_cli)"]
        SDK["Python SDK (mcp_client)"]
    end

    subgraph "Transport Layer (mcp_transport)"
        SSE[SSE Transport]
        Stdio[Stdio Transport]
    end

    subgraph "Server Layer (mcp_server)"
        Tools[Tools Registration]
        Prompts[Prompts Registration]
        Resources[Resources Provider]
    end

    subgraph "Core Domain (mcp_core)"
        Service[Invoice Service]
        Repo[Repository]
        Models[Domain Models]
    end

    subgraph "Infrastructure (mcp_infra)"
        Config[Configuration]
        Log[Structured Logging]
    end

    CLI --> SDK
    SDK --> SSE
    SSE --> Tools
    Stdio --> Tools
    Tools --> Service
    Service --> Repo
    Repo --> Models
    Service --> Log
    Service --> Config

📦 组件调查

这 src/ 目录包含以下模块，每个模块在系统中都扮演着特定的角色：

1.核心域(mcp_core)

应用程序的核心，包含业务逻辑和数据模型。

  • models.py：定义核心实体的Pydantic模型，如 Invoice, Customer，以及 InvoiceItem.
  • repository.py & json_repository.py：存储库模式实现。 JsonFileRepository 提供了一个具有乐观锁定的基于文件的持久层。
  • invoice_service.py：封装发票管理的业务规则（创建、最终确定、状态转换）。
  • prompt.py：管理基于Jinja2的提示模板，允许动态和可重用的LLM提示。
  • tool.py & resource.py：定义MCP工具和资源契约的抽象基类。

2.基础设施(mcp_infra)

处理跨领域问题。

  • config.py：使用配置管理 pydantic-settings.支持从环境变量加载(MCP_*)以及YAML文件。
  • logging.py：使用设置结构化JSON日志 structlog，确保可观察性和机器可读日志。

3.传输层(mcp_transport)

管理通信协议。

  • base.py：定义摘要 Transport 和 Server 接口。
  • sse.py：使用FastAPI通过HTTP实现服务器发送事件（SSE），适用于基于web的客户端。
  • stdio.py：实现标准输入/输出传输，非常适合本地进程通信和CLI工具。
  • factory.py：一个根据配置实例化正确传输的工厂。

4.服务器实现(mcp_server)

将域逻辑连接到MCP协议。

  • tools.py：注册域功能（例如。， create_draft_invoice)作为MCP工具。
  • prompts.py：注册高级提示（例如。， compose_dunning_email)用于LLM使用。
  • invoice_resources.py：将发票数据作为MCP资源公开（例如，虚拟PDF）。

5.客户端和CLI(mcp_client, mcp_cli)

与代理交互的工具。

  • mcp_client/client.py：一个流畅的Python SDK，用于以编程方式与代理交互。
  • mcp_cli/main.py：用于管理发票和客户的基于Typer的命令行界面。

🚀 入门指南

先决条件

安装

  1. 克隆存储库：

    git clone https://github.com/yourusername/mcp-docs.git
cd mcp-docs

  2. 安装依赖项：

    pip install -e .

  3. 配置： 应用程序可以通过环境变量进行配置。创建一个 .env 文件：

    MCP_APP__ENVIRONMENT=development
MCP_LOGGING__LEVEL=DEBUG
MCP_TRANSPORT=stdio

💻 用法

运行CLI

CLI允许您直接从终端与发票系统交互。

# View help
python src/mcp_cli/main.py --help

# Create a new invoice
python src/mcp_cli/main.py new --customer-id "CUST-123" --description "Consulting Services" --quantity 10 --price 150.0

# List all invoices
python src/mcp_cli/main.py list

# Filter invoices by status
python src/mcp_cli/main.py list --status draft

运行服务器（SSE）

要通过HTTP/SSE公开代理，请使用以下命令运行服务器 uvicorn.

# Start the server (ensure you have an entry point configured)
uvicorn src.mcp_server.main:app --reload

🛠️ 发展

测试

运行综合测试套件：

pytest

装订和格式化

通过以下方式保持代码质量 ruff:

ruff check .
ruff format .

视觉效果

命令行界面（CLI）

CLI提供了一个丰富的基于表的界面来管理发票和客户。

示例：列出发票

           Invoices (All)            
┏━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┓
┃ ID    ┃ Customer ┃ Status ┃ Total ┃
┡━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━┩
│ inv_1 │ cust_1   │ draft  │ $0.00 │
└───────┴──────────┴────────┴───────┘

交互式仪表板

Streamlit仪表板可用于可视化发票指标。

运行它：

streamlit run dashboard.py

它显示：

  • 总收入和发票计数
  • 状态分布图
  • 用于深入了解发票详细信息的数据表

❓ 故障排除

常见问题

1.服务器无法启动，显示“找不到模块” 确保您已在可编辑模式下安装了软件包：

pip install -e .

2.CLI无法连接到服务器

  • 确保服务器正在运行(python src/mcp_server/main.py 或 uvicorn src.mcp_server.main:app).
  • 检查端口8000是否被占用。
  • 验证 MCP_TRANSPORT 环境变量与您的设置相匹配。

3.“乐观锁定失败” 当多个进程试图同时更新同一发票时，就会发生这种情况。系统采用乐观并发控制；只需重试该操作。

相关 MCP