MCP Server Full

🚀 纯代理式MCP服务器

本项目是对模型上下文协议（MCP）的纯代理式实现，采用代理式架构，将所有功能通过专门的代理以MCP工具的形式呈现。

✨ 主要特性

• 🤖 纯代理式架构：所有功能（OpenAI、Ollama、文件操作）均以代理的形式实现。
• 🔗 双访问模式：为Claude Desktop提供MCP协议，为Web/Streamlit UI提供HTTP端点。
• ⚡ 动态工具注册：代理在启动时自动注册其工具。
• 🔧 模块化设计：可轻松添加新的代理，无需修改核心服务器代码。
• 📱 简洁的Web界面：采用现代的Streamlit界面，方便交互式使用工具。
• 🛡️ 优雅降级：代理可独立失败，不影响整个系统。
• 🔑 基于环境的配置：通过环境变量安全管理API密钥。

🚀 快速开始

前提条件

• Python 3.11+
• 支持虚拟环境

📦 安装指南

git clone <repo-url>
cd mcp_server_full

# 创建并激活虚拟环境
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate

# 安装依赖
pip install --upgrade pip
pip install -r requirements.txt

配置

创建一个 .env 文件，并添加你的API密钥（均为可选）：

# OpenAI 代理（可选）
OPENAI_API_KEY=your_openai_api_key_here

# Ollama 代理（可选，使用本地Ollama服务器）
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.2

# 文件代理（默认启用，无需配置）
# 提供文件读取、写入和列表功能

运行服务器

用于Claude Desktop（MCP协议）

# 启动用于Claude Desktop的纯MCP服务器
python run_mcp_server.py

将以下内容添加到你的Claude Desktop配置文件（claude_desktop_config.json）中：

{
  "mcpServers": {
    "agentic-mcp": {
      "command": "python",
      "args": ["run_mcp_server.py"],
      "cwd": "d:\\AI Lab\\MCP research\\mcp_server_full"
    }
  }
}

用于Web界面（HTTP + Streamlit）

# 终端1：启动用于工具的HTTP主机
python simple_mcp_host.py

# 终端2：启动Streamlit UI
streamlit run streamlit_app.py

通过以下地址访问Web界面：http://localhost:8501

测试设置

# 测试代理注册和工具可用性
python test_quick.py

# 测试特定代理
python test_both.py

# 验证服务器功能
python validate_server.py

💻 使用示例

基础用法

在Claude Desktop中，服务器配置完成后，工具会自动可用。你可以向Claude提出如下请求：

• "读取file.txt的内容"
• "使用Ollama生成文本"
• "使用OpenAI分析这段文本"

高级用法

HTTP API（Web/Streamlit）

# 列出可用工具
curl http://localhost:8000/tools

# 调用特定工具
curl -X POST http://localhost:8000/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "file_read",
    "arguments": {
      "file_path": "example.txt"
    }
  }'

📚 详细文档

可用代理和工具

🤖 OpenAI代理

状态：提供API密钥时可用 工具：

• openai_chat：使用GPT模型进行聊天完成
• openai_analysis：文本分析和洞察

设置：在 .env 文件中添加 OPENAI_API_KEY。

🦙 Ollama代理

状态：本地Ollama服务器运行时可用 工具：

• ollama_chat：与本地Ollama模型进行聊天
• ollama_generate：文本生成

设置：在本地安装并运行Ollama，配置 OLLAMA_BASE_URL 和 OLLAMA_MODEL。

📁 文件代理

状态：始终可用 工具：

• file_read：读取文件内容
• file_write：将内容写入文件
• file_list：列出目录内容

设置：无需配置。

API使用

MCP协议（Claude Desktop）

服务器配置完成后，工具会自动在Claude Desktop中可用。你可以向Claude提出相应请求来使用工具。

HTTP API（Web/Streamlit）

通过上述的 curl 命令示例，你可以列出可用工具并调用特定工具。

架构

核心组件

• pure_mcp_server.py：用于Claude Desktop集成的主MCP JSON-RPC服务器。
• simple_mcp_host.py：通过REST API公开MCP工具的HTTP包装器。
• registry.py：动态代理和工具注册系统。
• run_mcp_server.py：Claude Desktop配置的入口脚本。
• config.py：基于环境的配置管理。
• protocol.py：MCP协议模型和类型。

代理

• agents/base.py：所有代理实现的基础代理接口。
• agents/openai_agent.py：OpenAI API集成代理。
• agents/ollama_agent.py：本地Ollama模型集成代理。
• agents/file_agent.py：文件系统操作代理。

用户界面

• streamlit_app.py：用于交互式工具使用的现代Web UI。
• Claude Desktop：直接的MCP协议集成。

代理注册流程

# 每个代理动态注册其工具
class YourAgent(BaseAgent):
    def get_tools(self) -> Dict[str, Any]:
        return {
            "your_tool": {
                "description": "What your tool does",
                "inputSchema": {...}
            }
        }
    
    async def handle_tool_call(self, tool_name: str, params: Dict[str, Any]) -> Any:
        # Handle the tool call
        pass

# 注册表自动发现并路由工具
registry.register_agent("your_agent", YourAgent(config))

开发

项目结构

mcp_server_full/
├── agents/                    # 代理实现
│   ├── base.py               # 基础代理接口
│   ├── openai_agent.py       # OpenAI集成
│   ├── ollama_agent.py       # Ollama集成
│   └── file_agent.py         # 文件操作
├── pure_mcp_server.py        # 用于Claude Desktop的主MCP服务器
├── simple_mcp_host.py        # 用于Web界面的HTTP主机
├── registry.py               # 动态工具注册
├── run_mcp_server.py         # Claude Desktop入口点
├── streamlit_app.py          # Web UI
├── config.py                 # 配置管理
├── protocol.py               # MCP协议模型
├── requirements.txt          # 依赖项
├── .env                      # 环境变量（需创建）
├── ADDING_NEW_AGENTS.md      # 详细的代理开发指南
└── README.md                 # 本文件

添加新代理

如需完整的添加新代理的分步指南，请参阅 ADDING_NEW_AGENTS.md。

快速概述：

1. 在 agents/ 目录下创建继承自 BaseAgent 的代理文件。
2. 实现 get_tools() 和 handle_tool_call() 方法。
3. 在 pure_mcp_server.py 和 simple_mcp_host.py 中注册代理。
4. 添加配置并测试你的代理。

该指南包含完整的代码示例、最佳实践和故障排除提示。

添加新工具

要向现有代理添加新工具，请按以下步骤操作：

1. 编辑代理的 get_tools() 方法，定义新工具的架构。
2. 在代理的 handle_tool_call() 方法中添加处理程序方法。
3. 测试新工具的功能。
4. 更新文档。

示例：

# 在你的代理中
def get_tools(self):
    return {
        "new_tool": {
            "description": "Description of new tool",
            "inputSchema": {
                "type": "object", 
                "properties": {
                    "param": {"type": "string", "description": "Parameter description"}
                },
                "required": ["param"]
            }
        }
    }

async def handle_tool_call(self, tool_name: str, params: Dict[str, Any]) -> Any:
    if tool_name == "new_tool":
        return await self._handle_new_tool(params)

故障排除

常见问题

1. 代理不可用：检查API密钥和服务连接性。

   # 测试代理注册
   python test_quick.py
   

2. Claude Desktop无法连接：验证配置路径和入口点。

   # 检查claude_desktop_config.json
   {
     "mcpServers": {
       "agentic-mcp": {
         "command": "python",
         "args": ["run_mcp_server.py"],
         "cwd": "d:\\AI Lab\\MCP research\\mcp_server_full"
       }
     }
   }
   

3. Streamlit UI问题：确保HTTP主机正在运行。

   # 先启动HTTP主机
   python simple_mcp_host.py
   # 然后启动Streamlit
   streamlit run streamlit_app.py
   

4. OpenAI错误：检查API密钥和配额。

   # 直接测试OpenAI
   python openai_test.py
   

5. Ollama无法工作：验证Ollama服务器是否正在运行。

   # 检查Ollama状态
   curl http://localhost:11434/api/tags
   

调试模式

启用详细日志记录：

# 设置环境变量
export LOG_LEVEL=DEBUG
python run_mcp_server.py

健康检查

# 检查HTTP API健康状况
curl http://localhost:8000/health

# 列出已注册的工具
curl http://localhost:8000/tools

# 测试工具调用
curl -X POST http://localhost:8000/tools/call \
  -H "Content-Type: application/json" \
  -d '{"tool_name": "file_list", "arguments": {"directory_path": "."}}'

依赖项

核心运行时

• pydantic：配置和数据验证。
• asyncio：异步操作支持。
• httpx：用于外部API的HTTP客户端。
• aiofiles：异步文件操作。

特定代理

• openai：OpenAI API客户端（用于OpenAI代理）。
• ollama：Ollama API客户端（用于Ollama代理）。

Web界面

• streamlit：现代Web UI框架。
• requests：用于Streamlit的HTTP请求。

开发与测试

• pytest：测试框架。
• logging：调试和监控。

所有依赖项通过 requirements.txt 自动安装。

贡献

1. 分叉仓库。
2. 创建功能分支：git checkout -b feature/your-feature。
3. 按照 代理开发指南 添加你的代理。
4. 测试你的更改：python test_quick.py。
5. 提交拉取请求。

代理开发工作流程

1. 规划：定义你的代理将提供哪些工具。
2. 实现：创建继承自 BaseAgent 的代理类。
3. 注册：在两个服务器文件中添加代理注册。
4. 测试：验证代理在MCP和HTTP模式下均可正常工作。
5. 文档：更新README并创建使用示例。

Streamlit Web界面

功能

• 🔧 实时工具发现：自动显示所有已注册代理的可用工具。
• 💬 交互式界面：提供易于使用的表单，用于输入工具参数。
• 📊 响应显示：格式化显示工具结果。
• 🖥️ 代理状态：实时监控代理的可用性。
• ⚙️ 配置：基于环境的设置，带有清晰的状态指示器。

使用方法

1. 启动后端：python simple_mcp_host.py。
2. 启动Streamlit：streamlit run streamlit_app.py。
3. 打开浏览器：访问 http://localhost:8501。
4. 选择工具：从可用的代理工具中进行选择。
5. 执行：填写参数并交互式运行工具。

工具集成

Streamlit UI会自动发现并为代理注册的任何工具创建表单，方便在添加代理时测试和使用新功能。

📄 许可证

本项目采用MIT许可证。