使用说明

MCP平台

一个可扩展的基于MCP的执行平台，允许用户通过聊天UI进行交互，LLM（通过LlamaIndex）通过MCP解释意图和受控执行特定于应用程序的操作。

架构概述

┌─────────────┐
│   Chat UI   │  React-based frontend
└──────┬──────┘
       │
       ▼
┌─────────────────────────────┐
│  Orchestrator (AI Gateway)  │  FastAPI - Conversation management, LLM orchestration
└──────┬──────────────────────┘
       │
       ├────────────────────┐
       ▼                    ▼
┌─────────────┐      ┌─────────────┐
│     LLM     │      │ MCP Client  │
│ (LlamaIndex)│      │             │
└─────────────┘      └──────┬──────┘
                            │
                            ▼
                     ┌─────────────┐
                     │ MCP Server  │  Tool registry, auth, audit, routing
                     └──────┬──────┘
                            │
          ┌─────────────────┼─────────────────┐
          ▼                 ▼                 ▼
    ┌───────────┐    ┌───────────┐    ┌───────────┐
    │    HR     │    │    ERP    │    │  DevOps   │
    │  Domain   │    │  Domain   │    │  Domain   │
    └───────────┘    └───────────┘    └───────────┘

关键原则

关注点分离：每个组件都有一个单一的职责
域隔离：应用程序是隔离的，没有跨域调用
配置驱动：通过配置而非代码更改添加新域
法学硕士是顾问，MCP是权威：LLM建议采取行动，MCP强制执行

组件

前端（聊天用户界面）

捕获用户输入
显示助手响应
无业务逻辑
无直接LLM或MCP访问

编排器（AI网关）

管理对话状态
通过LlamaIndex与LLM接口
为LLM提供工具定义
解析结构化工具调用
调用MCP客户端

MCP服务器

注册并公开MCP工具
强制授权
将调用路由到应用程序域
审核所有执行
无LLM或UI逻辑

应用程序域

每个域包含：

工具定义（命名空间。， hr.get_employee)
适配器实现
权限模型
配置

包含的域名：

人力资源：员工查询，部门信息
企业资源计划：发票、库存管理
开发运维：Kubernetes操作、日志、扩展

快速开始

先决条件

Python 3.10+
Node.js 18+
Docker（可选）

本地开发

克隆和设置:

cd mcp_poc
cp .env.example .env
# Edit .env with your LLM API keys

安装Python依赖项:

pip install -e ".[dev]"

启动MCP服务器 （终端1）：

export PYTHONPATH=$PWD/src
python -m mcp_server.main

启动编排器 （终端2）：

export PYTHONPATH=$PWD/src
python -m orchestrator.main

启动前端 （终端3）：

cd frontend
npm install
npm run dev

打开浏览器: http://localhost:3000

使用Docker

# Build and run all services
docker-compose up --build

# Access:
# - Frontend: http://localhost:3000
# - Orchestrator API: http://localhost:8000
# - MCP Server API: http://localhost:8001

使用模拟LLM进行测试

对于没有LLM API密钥的测试，请使用mock提供程序：

# config/settings.yaml
llm:
  provider: mock

API终点

编排器（端口8000）

端点	方法	描述
`/health`	GET	健康检查
`/chat`	POST	发送聊天消息
`/conversations`	GET	列出对话
`/conversations/{id}`	GET	获取对话历史记录
`/conversations/{id}`	DELETE	删除对话
`/tools`	GET	列出可用工具

MCP服务器（端口8001）

端点	方法	描述
`/health`	GET	健康检查
`/tools`	GET	列出已注册的工具
`/tools/{name}`	GET	获取工具详细信息
`/execute`	POST	执行工具
`/domains`	GET	列出已注册的域名

工具示例

人力资源领域

# Get employee information
hr.get_employee(employee_id="E001")

# Search employees
hr.search_employees(department="Engineering", query="developer")

# List departments
hr.list_departments()

ERP领域

# Get invoice
erp.get_invoice(invoice_id="INV-001")

# Create invoice
erp.create_invoice(
    customer="Acme Corp",
    items=[{"description": "Service", "quantity": 1, "unit_price": 1000}]
)

# Check low stock
erp.check_low_stock(category="Components")

DevOps领域

# List pods
devops.list_pods(namespace="production")

# Get pod logs
devops.get_pod_logs(pod_name="api-server-xyz")

# Scale deployment
devops.scale_deployment(deployment_name="api-server", replicas=3)

添加新域

src/domains/mydomain/
├── __init__.py
└── config.yaml (optional)

机具适配器:

# src/domains/mydomain/__init__.py
from domains.base import BaseAdapter
from shared.models import DomainConfig, ToolDefinition

class MyDomainAdapter(BaseAdapter):
    def __init__(self, config: DomainConfig):
        super().__init__(config)
        self._define_tools()
    
    def _define_tools(self):
        self._tools["my_action"] = ToolDefinition(
            name="my_action",
            domain="mydomain",
            description="Does something useful",
            input_schema={...},
            output_schema={...}
        )
    
    @property
    def tools(self):
        return list(self._tools.values())
    
    def execute(self, action, parameters, context):
        # Implement action handlers
        ...

def register_mydomain_domain(router):
    config = DomainConfig(name="mydomain", ...)
    adapter = MyDomainAdapter(config)
    
    from mcp_server.registry import get_registry
    get_registry().register_many(adapter.tools)
    router.register_adapter("mydomain", adapter.execute)

注册于 domains/__init__.py:

from domains.mydomain import register_mydomain_domain

def load_all_domains(router):
    # ... existing domains ...
    register_mydomain_domain(router)

添加配置 （可选）：

# config/domains/mydomain.yaml
name: mydomain
description: My custom domain
version: "1.0.0"
enabled: true

配置

环境变量

变量	描述	默认值
`MCP_ENVIRONMENT`	环境名称	开发
`MCP_LOG_LEVEL`	日志级别	信息
`LLM_PROVIDER`	LLM提供程序	azure _openai
`LLM_API_KEY`	LLM的API密钥	-
`LLM_API_BASE`	API基础URL	-
`LLM_MODEL`	型号名称	gpt-4
`MCP_SERVER_PORT`	MCP服务器端口	8001
`ORCHESTRATOR_PORT`	编排器端口	8000

YAML配置

看 config/settings.yaml 查看完整配置选项。

安全

认证

用户身份源自Orchestrator
MCP服务器只信任经过身份验证的MCP客户端
基于JWT的令牌身份验证

授权

在MCP服务器中强制执行
从未由法学硕士决定
基于角色和基于范围的访问控制

审计

记录所有工具执行情况
捕获：用户、工具、参数、时间戳、结果
敏感参数会自动编辑

测试

# Run all tests
pytest

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

# Run specific test file
pytest tests/test_domains.py

# Run specific test
pytest tests/test_mcp_server.py::TestToolRegistry::test_register_tool

项目结构

mcp_poc/
├── src/
│   ├── shared/              # Shared models, config, utilities
│   │   ├── models.py        # Pydantic models
│   │   ├── config.py        # Configuration management
│   │   ├── logging.py       # Structured logging
│   │   └── schema.py        # JSON Schema utilities
│   ├── mcp_server/          # MCP Server
│   │   ├── main.py          # FastAPI app
│   │   ├── registry.py      # Tool registry
│   │   ├── router.py        # Tool routing
│   │   ├── auth.py          # Authentication/Authorization
│   │   └── audit.py         # Audit logging
│   ├── mcp_client/          # MCP Client
│   │   ├── client.py        # HTTP client
│   │   └── discovery.py     # Tool discovery with caching
│   ├── orchestrator/        # AI Gateway
│   │   ├── main.py          # FastAPI app
│   │   ├── llm.py           # LLM providers (LlamaIndex)
│   │   ├── conversation.py  # Conversation management
│   │   └── gateway.py       # Core orchestration logic
│   └── domains/             # Application domains
│       ├── base.py          # Base adapter classes
│       ├── hr/              # HR domain
│       ├── erp/             # ERP domain
│       └── devops/          # DevOps domain
├── frontend/                # React chat UI
│   ├── src/
│   │   ├── App.tsx          # Main component
│   │   └── services/api.ts  # API client
│   └── package.json
├── config/                  # Configuration files
│   ├── settings.yaml        # Main config
│   └── domains/             # Domain configs
├── tests/                   # Test suite
├── docker-compose.yml       # Docker orchestration
├── Dockerfile              # Backend container
└── pyproject.toml          # Python project config

成功标准

✅ 仅通过新域登录新应用程序
✅ 没有为延期而重新部署核心资源
✅ LLM提供程序可交换，无需更改MCP
✅ 多个应用程序的安全共存
✅ 设计域隔离
✅ 配置驱动的可扩展性

许可证

MIT许可证-请参阅许可证了解详情。