模型上下文协议 (MCP)

MCP 是一个开放协议，用于标准化应用程序如何向 LLM 提供上下文 - 可以将其视为 AI 应用程序的 USB-C 接口。它实现了 AI 模型与各种数据源/工具之间的无缝连接。

🔌 为什么选择 MCP？

MCP 通过提供以下功能，帮助在 LLM 之上构建代理和复杂的工作流程：

• 预构建的集成，供您的 LLM 接入
• 灵活切换 LLM 提供商
• 安全的数据处理最佳实践
• AI 应用程序的标准化接口

🏗️ 核心组件

flowchart LR
    A[MCP 主机] --> B[MCP 客户端]
    B --> C[终端]
    B --> D[文件系统]
    B --> E[内存]
    C --> F[本地数据]
    D --> G[本地文件]
    E --> H[远程 API]

1. MCP 主机: 需要 AI 上下文的应用程序（如 Claude Desktop、IDE）
2. MCP 客户端: 管理服务器连接的协议处理程序
3. MCP 服务器: 暴露特定功能的轻量级程序：
   • 终端服务器：执行命令
   • 文件系统服务器：访问本地文件
   • 内存服务器：持久数据存储
4. 数据源:
   • 本地：您机器上的文件、数据库
   • 远程：Web API 和云服务

🚀 系统概述

flowchart LR
    用户 --> 客户端
    客户端 --> AI[AI 处理]
    客户端 --> 终端[终端]
    客户端 --> 文件系统[文件系统]
    客户端 --> 内存[内存]

核心组件：

• AI 处理: Google Gemini + LangChain 用于自然语言理解
• 终端服务器: 在隔离的工作区中执行系统命令
• 文件系统服务器: 管理文件操作
• 内存服务器: 存储和检索持久数据

主要特点：

• 根据需要自动启动服务器
• 安全的工作区隔离
• 灵活的配置
• 可扩展的架构

📂 文件结构

flowchart TD
    A[mcp] --> B[客户端]
    A --> C[服务器]
    A --> D[工作区]
    
    B --> E[mcp-client]
    E --> F[main.py]
    E --> G[client.py]
    E --> H[config.json]
    E --> I[.env]
    
    C --> J[终端]
    J --> K[server.py]
    
    D --> L[memory.json]
    D --> M[notes.txt]

关键文件：

• clients/mcp-client/main.py: 主要客户端入口点
• clients/mcp-client/langchain_mcp_client_wconfig.py: AI 集成
• clients/mcp-client/theailanguage_config.json: 服务器配置
• clients/mcp-client/.env: 环境变量
• servers/terminal_server/terminal_server.py: 终端服务器
• workspace/memory.json: 持久内存存储
• workspace/notes.txt: 系统笔记

文件类型细分：

• Python 文件 (60%):

  • 核心应用程序逻辑和业务规则
  • 服务器实现和客户端应用程序
  • 包括同步和异步代码
  • 遵循 PEP 8 风格指南

• JSON 文件 (20%):

  • 服务器和服务配置文件
  • API 请求/响应模式
  • 持久数据存储格式
  • 强制执行严格的模式验证

• 文本文件 (15%):

  • 系统文档（README、指南）
  • 开发人员笔记和注释
  • 临时数据存储
  • 纯文本日志和输出

• 其他格式 (5%):

  • 环境变量文件 (.env)
  • Git 忽略模式
  • 许可信息
  • 构建配置文件

🔌 客户端组件

flowchart TD
    A[用户输入] --> B[客户端]
    B --> C{类型?}
    C -->|命令| D[终端]
    C -->|文件| E[文件系统]
    C -->|内存| F[存储]
    C -->|AI| G[Gemini]
    D --> H[响应]
    E --> H
    F --> H
    G --> H
    H --> I[输出]

主要客户端文件：

• langchain_mcp_client_wconfig.py: 主要客户端应用程序
• theailanguage_config.json: 服务器配置
• .env: 环境变量

主要特点：

• 管理多个 MCP 服务器
• 集成 Google Gemini 用于自然语言处理
• 处理动态响应生成
• 处理 LangChain 对象

配置：

1. theailanguage_config.json:

{
  "mcpServers": {
    "terminal_server": {
      "command": "uv",
      "args": ["run", "../../servers/terminal_server/terminal_server.py"]
    },
    "memory": {
      "command": "npx.cmd",
      "args": ["@modelcontextprotocol/server-memory"],
      "env": {"MEMORY_FILE_PATH": "workspace/memory.json"}
    }
  }
}

2. .env 设置:

GOOGLE_API_KEY=your_api_key_here
THEAILANGUAGE_CONFIG=clients/mcp-client/theailanguage_config.json

设置步骤：

1. 在 clients/mcp-client/ 中创建 .env 文件
2. 添加所需变量
3. 更改后重启客户端

🖥️ 服务器组件

classDiagram
    class TerminalServer {
        +path: String
        +run()
        +validate() 
        +execute()
    }
    TerminalServer --|> FastMCP
    class FastMCP {
        +decorate()
        +transport()
    }

终端服务器

• 目的: 在隔离的工作区中执行系统命令
• 主要特点:
  • 快速命令执行
  • 安全的工作区隔离
  • 全面的日志记录
• 技术细节:
  • 使用 FastMCP 进行传输
  • 在执行前验证命令
  • 捕获并返回输出

工作区文件

memory.json

• 目的: 持久数据存储
• 操作:
  • 存储/更新/读取数据
  • 查询特定信息
• 示例结构:

{
  "user_preferences": {
    "favorite_color": "blue",
    "interests": ["science fiction"]
  },
  "system_state": {
    "last_commands": ["git status", "ls"]
  }
}

notes.txt

• 目的: 系统文档和笔记
• 内容类型:
  • 用户文档 (40%)
  • 系统笔记 (30%)
  • 临时数据 (20%)
  • 其他 (10%)

🛠️ 本地设置指南

前提条件

• Python 3.9+
• Node.js 16+
• Google API 密钥
• UV 包管理器

安装步骤

1. 克隆存储库:

   git clone https://github.com/Techiral/mcp.git
   cd mcp
   

2. 设置 Python 环境:

   python -m venv venv
   # Linux/Mac:
   source venv/bin/activate
   # Windows:
   venv\Scripts\activate
   pip install -r requirements.txt
   

3. 配置环境变量:

   echo "GOOGLE_API_KEY=your_key_here" > clients/mcp-client/.env
   echo "THEAILANGUAGE_CONFIG=clients/mcp-client/theailanguage_config.json" >> clients/mcp-client/.env
   

4. 安装 Node.js 服务器:

   npm install -g @modelcontextprotocol/server-memory @modelcontextprotocol/server-filesystem
   

验证清单:

• [x] 存储库已克隆
• [x] Python 虚拟环境已创建并激活
• [x] Python 依赖项已安装
• [x] .env 文件已配置
• [x] Node.js 服务器已安装

🚀 使用说明

基本用法

1. 启动客户端：

python clients/mcp-client/langchain_mcp_client_wconfig.py

2. 输入自然语言请求并接收响应

命令示例

文件操作:

创建一个名为 example.txt 的文件
在所有 Python 文件中搜索 "function"
统计 main.py 中的行数

Web 内容:

总结 https://example.com
从新闻网站提取标题

系统命令:

列出当前目录中的文件
检查 Python 版本
运行 git status

内存操作:

记住我最喜欢的颜色是蓝色
我设置了什么偏好？
显示最近的命令

服务器配置

关键配置文件:

• theailanguage_config.json: 主要服务器配置
• .env: 环境变量

示例服务器配置:

{
  "terminal_server": {
    "command": "uv",
    "args": ["run", "servers/terminal_server/terminal_server.py"]
  },
  "memory": {
    "command": "npx.cmd",
    "args": ["@modelcontextprotocol/server-memory"],
    "env": {"MEMORY_FILE_PATH": "workspace/memory.json"}
  }
}

配置提示:

• 使用绝对路径以提高可靠性
• 为敏感数据设置环境变量
• 配置更改后重启服务器

🛠️ 故障排除

常见问题和解决方案:

1. 身份验证问题:

   • 验证 .env 中的 Google API 密钥
   • 检查密钥是否具有正确的权限
   • 如果需要，重新生成密钥

2. 文件操作失败:

   # 检查权限
   ls -la workspace/
   
   # 重启文件系统服务器
   npx @modelcontextprotocol/inspector uvx mcp-server-filesystem
   

3. 内存操作失败:

   # 验证 memory.json 是否存在
   ls workspace/memory.json
   
   # 重启内存服务器
   npx @modelcontextprotocol/server-memory
   

调试工具:

• 启用详细日志记录：

  echo "LOG_LEVEL=DEBUG" >> clients/mcp-client/.env
  

• 列出正在运行的服务器：

  npx @modelcontextprotocol/inspector list
  

支持:

• 文档
• 报告问题

🤝 如何贡献

入门:

1. Fork 并克隆存储库
2. 设置开发环境（请参阅本地设置指南）

开发工作流程:

# 创建功能分支
git checkout -b feature/your-feature

# 按照以下方式进行更改：
# - Python: PEP 8 风格
# - JavaScript: StandardJS 风格
# - 记录所有新函数

# 运行测试
python -m pytest tests/

# 推送更改
git push origin feature/your-feature

Pull Requests:

• 引用相关问题
• 清楚地描述更改
• 包括测试结果
• 在合并之前压缩提交

代码审查:

• 通常在 48 小时内进行审查
• 在合并之前解决所有反馈

推荐设置:

• 带有 Python/JS 扩展的 VSCode
• 用于测试的 Docker
• Pre-commit hooks