使用说明

MCP网关和检查器

一个模块化的微服务通信协议（MCP）网关包，用于将GraphQL API包裹在标准化的跟踪、身份验证和错误处理中。包括一个功能齐全的网络检查器，用于测试和监控。

特性

MCP网关包

模块化设计：可重用的Python包，可以通过pip安装或独立使用
追踪：自动相关ID生成和传播
认证：承载令牌验证中间件
错误处理：标准化MCP错误代码和响应
GraphQL代理：无缝代理到后端GraphQL服务

MCP检查器Web应用程序

请求构建器：Visual GraphQL查询编辑器
响应查看器：格式化的JSON响应显示，错误突出显示
请求历史：跟踪和回放以前的请求
环境管理：在dev/stating/prod环境之间切换
请求模板：保存和重用常见查询
导出/导入：将请求共享为JSON文件
关联ID跟踪：查看和复制相关ID以进行调试

安装

Python包

# Install dependencies
pip install -r requirements.txt

# Or install as a package
pip install -e .

检查器Web应用程序

cd inspector
npm install

配置

复制 .env.example 到 .env 并配置：

cp .env.example .env

关键配置选项：

TARGET_GRAPHQL_URL：后端GraphQL API终结点
PORT：网关服务器端口（默认值：8080）
ENABLE_AUTH：启用/禁用身份验证（默认值：true）
LOG_LEVEL：日志记录级别（调试、信息、警告、错误）

用法

运行网关

# Using uvicorn directly
uvicorn gateway.main:app --reload --host 0.0.0.0 --port 8080

# Or using Python
python -m gateway.main

网关将在 http://localhost:8080

运行模拟后端（用于测试）

如果你没有真正的GraphQL后端，你可以使用附带的模拟后端进行测试：

# Easy way: Use the startup script
./start_mock_backend.sh

# Or manually:
python3 mock_backend.py
# or
uvicorn mock_backend:app --reload --port 8081

模拟后端将在 http://localhost:8081 并支持常见的GraphQL查询，如：

query { hello }
query { user(id: "1") { id name email } }
query { users { id name email } }
mutation { createUser(input: {name: "John", email: "john@example.com"}) { id } }

重要提示：

在启动网关之前，确保模拟后端正在运行
测试后端： curl http://localhost:8081/health
如果收到“连接被拒绝”，则模拟后端未运行
看 QUICKSTART.md 详细故障排除

运行MCP服务器进行LLM集成

CRM员工管理MCP服务器（模型上下文协议）将CRM功能作为LLM可以使用的工具公开：

# Install MCP SDK first
pip install git+https://github.com/modelcontextprotocol/python-sdk.git

# Start the MCP server
./start_crm_mcp.sh
# or
python3 crm_mcp_server.py

MCP服务器工具：

list_employees -使用筛选器列出/搜索员工
get_employee -按ID获取员工详细信息
create_employee -创建新员工
update_employee -更新员工信息
delete_employee -删除员工（软删除）
search_employees -按姓名、电子邮件等搜索员工。
get_employee_stats -获取员工统计信息
get_departments -列出所有部门

配置： 看 MCP_SETUP.md 有关Claude Desktop、Cursor和其他MCP兼容客户端的详细设置说明。

LLM使用示例： 连接到Claude Desktop或Cursor后，您可以使用自然语言：

“列出工程部门的所有员工”
“显示员工统计数据”
“在销售部门创建一个名为John Doe的新员工”
“搜索职位上有‘工程师’的员工”

正在运行CRM REST API服务器

CRM员工管理REST API服务器是一个全面的REST API服务器，用于管理员工数据：

# Easy way: Use the startup script
./start_crm_rest.sh

# Or manually:
python3 crm_rest_server.py
# or
uvicorn crm_rest_server:app --reload --port 8083

CRM服务器将在 http://localhost:8083 并提供：

员工管理端点：

GET /api/employees -列出所有员工（带过滤、分页、排序）
GET /api/employees/{id} -获取员工详细信息
POST /api/employees -创建新员工
PUT /api/employees/{id} -更新员工
DELETE /api/employees/{id} -删除员工（软删除）
GET /api/employees/search?q={query} -搜索员工
GET /api/employees/department/{dept} -按部门获取员工
GET /api/employees/stats -获取员工统计信息
GET /api/departments -列出所有部门

员工数据模型示例：

{
  "id": "emp-001",
  "firstName": "Ahmet",
  "lastName": "Yılmaz",
  "email": "ahmet.yilmaz@company.com",
  "phone": "+90 555 123 4567",
  "department": "Engineering",
  "position": "Senior Software Engineer",
  "salary": 85000.0,
  "hireDate": "2020-03-15",
  "status": "active",
  "address": "Atatürk Cad. No:123",
  "city": "Istanbul",
  "country": "Turkey",
  "managerId": null,
  "skills": ["Python", "JavaScript", "React", "Node.js"],
  "notes": "Team lead candidate"
}

运行检查器

cd inspector
npm run dev

检查员将在 http://localhost:3000 包括：

GraphQL检查器：测试GraphQL查询和突变
客户关系管理经理：功能齐全的员工管理界面，包括：
- 具有搜索和筛选功能的员工列表
- 添加/编辑/删除员工
- 基于部门的过滤
- 员工统计仪表板

快速入门-一次提供所有服务

要使用单个命令启动所有四个服务（模拟后端、网关、CRM MCP服务器和检查器）：

./dev-live.sh

此脚本将：

检查依赖关系和端口可用性
在单独的终端窗口中启动所有服务
显示服务URL和有用的端点
显示信息性状态消息

注：在macOS上，该脚本会打开新的终端窗口。在Linux上，它使用 gnome-terminal.

服务已启动：

模拟后端（端口8081）-GraphQL测试后端
网关（端口8080）-带REST和GraphQL代理的MCP网关
CRM MCP服务器（端口8083）-员工管理REST API
Inspector（端口3000）-用于测试和管理的Web UI

停止所有服务

要停止所有服务并释放端口，请执行以下操作：

./dev-live-shutdown.sh

此脚本将停止所有正在运行的服务（模拟后端、网关、CRM MCP服务器、检查器），并验证端口8081、8080、8083和3000是否可用。

在项目中使用MCP包

作为一个包裹

from mcp import MCPGateway, TracingMiddleware, AuthMiddleware
from fastapi import FastAPI

app = FastAPI()
app.add_middleware(TracingMiddleware)

gateway = MCPGateway(target_url="http://backend:8081/graphql")
auth = AuthMiddleware()

@app.post("/graphql")
async def graphql_proxy(request: Request, graphql_request: MCPRequest):
    auth.validate_request(request)
    return await gateway.proxy_graphql_request(request, graphql_request)

独立模块

复制 mcp/ 目录到您的项目，并根据需要导入。

API终点

网关端点

POST /graphql -代理GraphQL请求
POST /mcp/proxy -动态GraphQL代理（用于检查器）
POST /mcp/rest-proxy -REST API代理（支持GET、POST、PUT、DELETE、PATCH）
GET /health -健康检查端点

请求格式

{
  "query": "query { hello }",
  "operationName": "MyQuery",
  "variables": { "key": "value" }
}

认证

在授权标头中包含承载令牌：

Authorization: Bearer your-token-here

错误代码

MCP-401：身份验证失败
MCP-503：后端服务不可用
BACKEND-ERROR：后端服务错误
MCP-500：内部服务器错误

项目结构

mcp/
├── mcp/                    # Core MCP package (modular, reusable)
│   ├── __init__.py
│   ├── gateway.py          # Gateway base class
│   ├── middleware.py       # Tracing middleware
│   ├── auth.py             # Authentication handlers
│   ├── errors.py           # Error handling
│   └── models.py            # Pydantic models
├── gateway/                 # FastAPI application
│   ├── main.py             # FastAPI app entry point
│   └── config.py           # Configuration management
├── inspector/               # Next.js web application
│   ├── app/                # Next.js app directory
│   ├── components/         # React components
│   └── lib/                # Utilities
├── crm_rest_server.py      # CRM REST API server
├── crm_mcp_server.py       # CRM MCP Server (for LLM integration)
├── mcp_config.json         # MCP client configuration example
├── MCP_SETUP.md            # MCP Server setup guide
├── pyproject.toml          # Python package config
├── requirements.txt        # Python dependencies
└── README.md               # This file

测试

测试网关

# Successful request
curl -X POST "http://localhost:8080/graphql" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer my-valid-token-123" \
     -d '{
         "query": "query { hello }",
         "operationName": "TestQuery"
     }'

# Authentication error
curl -X POST "http://localhost:8080/graphql" \
     -H "Content-Type: application/json" \
     -d '{
         "query": "query { hello }"
     }'

使用检查器

启动网关和检查器
打开 http://localhost:3000 在浏览器中
配置环境（默认值： http://localhost:8080)
输入GraphQL查询
如果需要，添加身份验证令牌
点击“发送请求”
查看响应、关联ID和定时信息

发展

Python开发

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

# Run tests (when implemented)
pytest

# Format code
black .
ruff check .

检查员发展

cd inspector
npm run dev      # Development server
npm run build    # Production build
npm run lint     # Lint code

用于LLM集成的MCP服务器

该项目包括一个模型上下文协议（MCP）服务器，允许LLM（如Claude Desktop、Cursor）通过自然语言与CRM系统交互。

快速开始

安装MCP SDK：

pip install git+https://github.com/modelcontextprotocol/python-sdk.git

启动MCP服务器：

./start_crm_mcp.sh
# or
python3 crm_mcp_server.py

配置Claude桌面或光标：
- 看 MCP_SETUP.md 详细说明
- 添加指向的MCP服务器配置 crm_mcp_server.py

可用工具

MCP服务器提供了8个全面的CRM管理工具：

list_员工 -列出/搜索员工，可选择按部门、状态或搜索查询进行筛选
get_员工 -按ID获取特定员工的详细信息
创建者_员工 -在CRM系统中创建新员工记录
update_员工 -更新现有员工的信息
删除_员工 -删除员工（软删除-将状态设置为“已终止”）
搜索_员工 -按姓名、电子邮件、职位或部门搜索员工
get_employee_stats -获取员工的统计数据和分析
get_公寓 -获取组织中所有部门的列表

示例用法

连接到Claude Desktop或Cursor后，您可以使用自然语言：

"Show me all employees in the Engineering department"
"Create a new employee named Jane Smith in Sales"
"What are the employee statistics?"
"Search for employees with 'manager' in their title"
"Update employee emp-001's salary to 90000"

LLM将自动使用适当的MCP工具来满足您的请求。

数据存储集成

MCP服务器使用与REST API服务器相同的数据存储(crm_rest_server.py).两台服务器共享相同的 employees_db 字典，因此通过一个界面所做的更改在另一个界面中可见。

文档

有关完整的设置说明，请参阅 MCP_SETUP.md.

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交拉取请求。