使用说明

MCP代理服务器

带有Python后端和Go CLI客户端的模型上下文协议（MCP）服务器。

什么是MCP协议

模型上下文协议（MCP）是AI助手连接到外部工具和数据源的标准化协议。它在几个关键方面不同于简单的JSON HTTP API：

MCP与简单JSON HTTP

简单JSON HTTP API：

POST /api/file
{
  "action": "read",
  "path": "test.txt"
}

MCP协议（JSON-RPC 2.0）：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "file_operations",
    "arguments": {
      "operation": "read",
      "path": "test.txt"
    }
  }
}

主要区别

标准化结构：MCP使用带有必填字段（jsonrpc、id、方法、参数）的JSON-RPC 2.0
工具发现：MCP服务器通过以下方式公开可用工具 tools/list 方法
架构验证：每个工具都定义了输入/输出模式
错误处理：标准化的错误代码和消息
人工智能集成：专为AI助手工具调用而设计

性能和开销分析

JSON结构开销

简单JSON：~50字节有效载荷
MCP协议：~150字节的有效载荷（大3倍）
开销：每个请求约100字节

处理开销

简单JSON：直接参数提取
MCP协议：JSON-RPC解析+方法路由+模式验证
附加CPU：每次请求约2-5ms

网络性能

简单JSON：单端点，无需发现
MCP协议：初始工具发现+后续调用
延迟影响：+1次工具发现往返

现实世界影响

低交通量：可忽略的差异（<1ms）
大：MCP开销变得明显
人工智能集成：MCP收益大于管理费用

MCP在哪里运行

传输层：HTTP、WebSocket或stdio
本项目：在本地主机8081上使用HTTP
生产：经常在AI开发环境中运行（VS Code等）

请求流：GitHub Copilot如何调用MCP服务器

以下综合图说明了GitHub Copilot的AI模型如何处理用户请求和调用MCP服务器的完整流程：

%% Dark-theme optimized
flowchart TD
    %% User Input
    A[User Request: Read the contents of README.md] --> B{Copilot AI Analysis}
    
    %% Initial Setup
    B --> C{Is MCP Server Running?}
    C -->|No| D[Start MCP Server: python3 mcp_server.py]
    C -->|Yes| E[Load Tool Definitions: copilot-tools.json]
    D --> E

    %% Tool Discovery
    E --> F[Discover Tools: GET /tools/list]
    F --> G[Store Schemas: mcp_file_operations, etc.]

    %% NLP and Intent
    G --> H[Natural Language Processing]
    H --> I[Intent: read file]
    I --> J[Entity: README.md]
    J --> K[Action: read operation]

    %% Tool Selection
    K --> L{Tool Selection}
    L -->|File| M[mcp_file_operations]
    L -->|Code| N[mcp_code_analysis]
    L -->|Git| O[mcp_git_operations]
    L -->|System| P[mcp_system_info]
    L -->|Web| Q[mcp_web_search]

    %% Parameter Extraction
    M --> R[Params:\noperation=read,\npath=README.md]
    N --> S[Params:\nfile=file.py,\ntype=quality]
    O --> T[Params:\noperation=status]
    P --> U[Params:\ninfo_type=all]
    Q --> V[Params:\nquery=term]

    %% Schema Validation
    R --> W[Schema Validation]
    S --> W
    T --> W
    U --> W
    V --> W

    %% JSON-RPC
    W --> X{Valid?}
    X -->|Yes| Y[Create JSON-RPC Request]
    X -->|No| Z[Ask for Clarification]
    Z --> A

    Y --> AA[POST to localhost:8081/mcp]
    AA --> BB[Payload:\njsonrpc: 2.0,\nid: 1,\nmethod: tools/call,\nparams...]

    %% MCP Server
    BB --> CC[Process Request]
    CC --> DD[Parse JSON-RPC]
    DD --> EE[Route to Handler]
    EE --> FF[Run Tool]
    FF --> GG[Read File]

    %% Response
    GG --> HH{Success?}
    HH -->|Yes| II[Return:\njsonrpc: 2.0,\nresult:\n  content: '# MCP...']
    HH -->|No| JJ[Return:\njsonrpc: 2.0,\nerror: File not found]

    II --> KK[Process Success]
    JJ --> KK
    KK --> LL[Parse Response]
    LL --> MM[Format for Chat]
    MM --> NN[Display in Chat]

    %% Feedback Loop
    NN --> OO{Satisfied?}
    OO -->|Yes| PP[Done]
    OO -->|No| QQ[Retry Tool]
    QQ --> L

    %% Complex Request
    A --> RR{Complex Request?\ne.g. analysis}
    RR -->|Yes| SS[Decompose]
    SS --> TT[List Files]
    SS --> UU[Read README]
    SS --> VV[Analyze Code]
    SS --> WW[Check Git]
    SS --> XX[Get System Info]

    TT --> YY[Run Multiple Tools]
    UU --> YY
    VV --> YY
    WW --> YY
    XX --> YY

    YY --> ZZ[Gather Results]
    ZZ --> AAA[Format Combined]
    AAA --> NN

    %% Dark Theme Styling
    classDef userNode fill:#1f3b4d,stroke:#ffffff,stroke-width:2px,color:#ffffff
    classDef copilotNode fill:#2e1a47,stroke:#ffffff,stroke-width:2px,color:#ffffff
    classDef serverNode fill:#1b5e20,stroke:#ffffff,stroke-width:2px,color:#ffffff
    classDef toolNode fill:#3e2723,stroke:#ffffff,stroke-width:2px,color:#ffffff
    classDef errorNode fill:#b71c1c,stroke:#ffffff,stroke-width:2px,color:#ffffff

    class A,NN,PP userNode
    class B,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,AA,BB,KK,LL,MM,OO,QQ,RR,SS,TT,UU,VV,WW,XX,YY,ZZ,AAA copilotNode
    class C,D,E,F,G,CC,DD,EE,FF,GG,HH,II,JJ serverNode
    class M,N,O,P,Q toolNode
    class Z,QQ errorNode

建筑

Python服务器在端口8081上实现MCP协议。Go CLI使用JSON-RPC 2.0格式通过HTTP作为客户端连接。

Python MCP服务器

在localhost:8081上使用HTTP服务器实现工具。处理文件操作、代码分析、Git操作、系统信息和web搜索。

Go CLI客户端

连接到Python服务器的快速命令行界面。提供对所有MCP工具的交互式访问。

为什么这个项目与众不同

不仅仅是简单的JSON HTTP

该项目展示了 MCP协议实现，不是一个基本的JSON API：

工具发现：CLI可以动态发现可用工具
模式感知：工具已定义输入模式和验证
标准化协议：使用JSON-RPC 2.0并进行适当的错误处理
AI就绪：专为AI助手集成而设计
可扩展：易于添加具有适当模式的新工具

简单的JSON HTTP替代方案

一个基本的替代方案是：

curl -X POST http://localhost:8081/api/file \
  -H "Content-Type: application/json" \
  -d '{"action": "read", "path": "test.txt"}'

但这缺乏工具发现、模式验证和AI集成功能。

何时使用每个：

在以下情况下使用简单JSON：

高性能要求（>1000要求/秒）
已知API端点
所需开销最小

在以下情况下使用MCP协议：

AI助手集成
需要动态工具发现
需要架构验证
可扩展的工具生态系统

建筑

Python服务器在端口8081上实现MCP协议。Go CLI使用JSON-RPC 2.0格式通过HTTP作为客户端连接。

用法

make setup
make run

代理示例

列出可用工具

mcp-cli tools

Fetching available tools from Python MCP server...
Available Tools (5):

1. file_operations
   Perform file operations like read, write, list, and search

2. code_analysis
   Analyze code for quality, issues, and suggestions

3. git_operations
   Perform Git operations like status, commit, push, pull

4. system_info
   Get system information like CPU, memory, disk usage

5. web_search
   Search the web for information

文件操作

mcp-cli file list .

Calling tool: file_operations
Result:
Directory listing for .:
  - go.mod
  - Makefile
  - README.md
  - internal
  - mcp-cli
  - mcp_server.py
  - go.sum
  - cmd
  - requirements.txt

Git操作

mcp-cli git status

Calling tool: git_operations
Result:
Git error: fatal: not a git repository (or any of the parent directories): .git

系统信息

mcp-cli sys all

Calling tool: system_info
Result:
System Information
CPU Cores: 8
Total Memory: 16384 MB
Disk Usage:
Filesystem      Size  Used Avail Use% Mounted on
/dev/sda1       500G  150G  350G  30% /

代码分析

mcp-cli analyze cmd/cli.go

Calling tool: code_analysis
Result:
Code Analysis for cmd/cli.go
Language: auto
Analysis Type: quality
Lines of Code: 245
Characters: 6542
Empty Lines: 32
Comment Lines: 0
Code Density: 87.0%

服务器状态

mcp-cli status

Python MCP server is running at http://localhost:8081

交互式聊天

mcp-cli chat

以工具发现和命令解析开始交互式会话。

测试

make test-all

测试Python MCP服务器和Go CLI端点。

VS Code GitHub复制代理工具集成

VS代码配置

已创建以下配置文件：

.vscode/settings.json -VS代码设置与Copilot代理工具配置
.vscode/tasks.json -构建和运行任务
.vscode/launch.json -调试配置
.vscode/extensions.json -推荐的扩展
copilot-tools.json -副驾驶工具定义

启动MCP服务器

您可以通过多种方式启动MCP服务器：

选项A：使用VS代码任务

打开命令选项板(Ctrl+Shift+P)
类型“任务：运行任务”
选择“启动MCP服务器”

选项B：使用终端

python3 mcp_server.py

使用调试配置

转到运行和调试面板(Ctrl+Shift+D)
选择“调试MCP服务器”
点击播放按钮

验证集成

检查服务器是否正在运行：

./mcp-cli status

列出可用工具：

./mcp-cli tools

可用工具

1.文件操作(`mcp_file_operations`)

读：读取文件内容
写：将内容写入文件
列表：列出目录内容
搜索：按模式搜索文件
删除：删除文件或目录

2.代码分析(`mcp_code_analysis`)

质量：分析代码质量指标
安全：检查安全问题
演出：分析性能方面
风格：检查编码风格和惯例

3.Git操作(`mcp_git_operations`)

状态：检查Git存储库状态
提交：创建提交
推：将更改推送到远程
拉：从远程拉取更改
日志：查看提交历史记录
差异：显示差异

4.系统信息(`mcp_system_info`)

中央处理器：CPU信息
记忆：内存使用情况
磁盘：磁盘使用情况
网络：网络状态
全部：所有系统信息

5.网络搜索(`mcp_web_search`)

在网上搜索信息
可配置的结果计数

使用GitHub Copilot

1.启用代理工具

集成配置为自动启用Copilot代理工具。您可以在VS代码设置中验证这一点：

{
    "github.copilot.agent.tools.enabled": true,
    "github.copilot.agent.tools.autoStart": true
}

2.在聊天中使用工具

在GitHub Copilot Chat中，您现在可以使用以下命令：

“阅读以下内容 main.go"
“分析代码质量 mcp_server.py"
“检查Git状态”
“获取系统信息”
“搜索有关MCP协议的信息”

3.在代码中使用工具

Copilot现在可以在编码时建议和使用这些工具。例如：

当您要求读取文件时，它可以使用文件操作工具
当您需要系统信息时，可以使用系统信息工具
当您需要分析代码时，可以使用代码分析工具

开发工作流程

1.发展模式

对于开发，您可以使用交互式CLI：

./mcp-cli chat

这将启动一个交互式会话，您可以在其中测试所有工具。

2.调试

使用提供的调试配置：

“调试MCP服务器”-调试Python服务器
“调试MCP CLI”-调试Go CLI
“调试MCP CLI聊天”-调试交互式聊天

3.测试

测试单个工具：

# Test file operations
./mcp-cli file read README.md

# Test Git operations
./mcp-cli git status

# Test system info
./mcp-cli sys all

# Test code analysis
./mcp-cli analyze mcp_server.py

配置文件

VS代码设置(`.vscode/settings.json`)

配置Copilot代理工具
设置Python和Go环境
启用自动工具启动

任务(`.vscode/tasks.json`)

启动/停止MCP服务器
构建MCP CLI
运行各种CLI命令
检查服务器状态

启动配置(`.vscode/launch.json`)

Python和Go组件的调试配置
集成终端支持
环境变量配置

复制工具(`copilot-tools.json`)

定义Copilot的可用工具
指定输入模式
配置服务器启动

故障排除

常见问题

服务器未启动:
- 检查端口8081是否可用
- 验证是否安装了Python依赖项
- 检查终端是否有错误消息
CLI不工作:
- 确保已构建CLI： go build -o mcp-cli ./cmd
- 检查服务器是否正在运行
- 在CLI配置中验证服务器URL
副驾驶工具不可用:
- 重新启动VS代码
- 检查GitHub Copilot扩展是否已启用
- 验证中的设置 .vscode/settings.json

调试命令

# Check server health
curl http://localhost:8081/health

# Test MCP protocol
curl -X POST http://localhost:8081/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Check CLI status
./mcp-cli status

高级配置

定制工具开发

要添加新工具，请执行以下操作：

将工具添加到 mcp_server.py 在 _register_tools() 方法
在中实现工具逻辑 _execute_tool()
更新 copilot-tools.json 使用新的工具定义
在中添加CLI命令 cmd/cli.go

环境变量

您可以使用环境变量自定义行为：

export MCP_SERVER_URL=http://localhost:8081
export MCP_TIMEOUT=30s
export PYTHONPATH=/path/to/your/project

自定义服务器配置

修改 mcp_server.py 致：

更改服务器端口
添加身份验证
实施自定义协议
添加更复杂的错误处理

安全考虑

文件访问：文件操作工具可以访问系统上的任何文件
系统信息：系统信息工具可以暴露敏感的系统数据
网络接入：网络搜索工具发出外部网络请求
Git操作：Git操作可以修改您的存储库

在生产环境中使用工具之前，始终对其进行审查和测试。

贡献

为了促进这种整合：

分叉存储库
创建要素分支
进行更改
彻底测试
提交拉取请求