Pure Agentic MCP Server

纯代理MCP服务器

模型上下文协议（MCP）的纯实现，遵循代理架构，其中所有功能都通过专用代理作为MCP工具公开。

特性

• 🤖 纯代理架构：所有功能（OpenAI、Ollama、File操作）都作为代理实现
• 🔗 双重访问模式：用于Claude Desktop的MCP协议+用于web/Streamlit UI的HTTP端点
• ⚡ 动态工具注册表：代理在启动时自动注册他们的工具
• 🔧 模块化设计：无需修改核心服务器代码即可轻松添加新代理
• 📱 干净的Web UI：用于交互式工具使用的现代Streamlit界面
• 🛡️ 故障弱化：代理独立失败，不影响系统
• 🔑 基于环境的配置：通过环境变量实现安全的API密钥管理

架构概述

服务器实现了 纯代理模式 哪里：

1. 代理 封装特定功能（OpenAI API、Ollama、文件操作）
2. 注册表 管理动态工具注册和路由
3. MCP服务器 为Claude Desktop提供JSON-RPC协议合规性
4. HTTP主机 通过REST API为web接口公开工具
5. 流线型UI 提供对所有工具的用户友好的网络访问

Claude Desktop ←→ MCP Protocol ←→ Pure MCP Server ←→ Agent Registry ←→ Agents
                                                                      ↕
Web Browser    ←→ HTTP API     ←→ Simple MCP Host  ←→ Agent Registry ←→ Agents

快速开始

先决条件

• Python 3.11+
• 虚拟环境支持

安装

git clone 
cd mcp_server_full

# Create and activate virtual environment
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

配置

创建一个 .env 带有API密钥的文件（全部可选）：

# OpenAI Agent (optional)
OPENAI_API_KEY=your_openai_api_key_here

# Ollama Agent (optional, uses local Ollama server)
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.2

# File Agent (enabled by default, no config needed)
# Provides file reading, writing, and listing capabilities

运行服务器

适用于克劳德桌面（MCP协议）

# Start the pure MCP server for Claude Desktop
python run_mcp_server.py

添加到您的Claude桌面配置(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）

# Terminal 1: Start HTTP host for tools
python simple_mcp_host.py

# Terminal 2: Start Streamlit UI  
streamlit run streamlit_app.py

访问网页界面：http://localhost:8501

测试您的设置

# Test agent registration and tool availability
python test_quick.py

# Test specific agents
python test_both.py

# Validate server functionality
python validate_server.py

可用代理和工具

🤖 OpenAI代理

状态：可与API密钥一起使用\ 工具:

• openai_chat：使用GPT模型完成聊天
• openai_analysis：文本分析和见解

设置：添加 OPENAI_API_KEY 向 .env 文件

🦙 Ollama代理商

状态：可用于本地Ollama服务器\ 工具:

• ollama_chat：与当地Ollama模特聊天
• ollama_generate：文本生成

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

📁 文件代理

状态：始终可用\ 工具:

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

设置：无需配置

API使用

MCP协议（克劳德桌面版）

配置服务器后，工具将在Claude Desktop中自动可用。请克劳德：

• “读取.txt文件的内容”
• “使用Ollama生成文本”
• “使用OpenAI分析此文本”

HTTP API（Web/Streamlit）

# List available tools
curl http://localhost:8000/tools

# Call a specific tool
curl -X POST http://localhost:8000/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "file_read",
    "arguments": {
      "file_path": "example.txt"
    }
  }'

建筑

核心组件

• 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
• 克劳德桌面：直接MCP协议集成

代理注册流程

# Each agent registers its tools dynamically
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 automatically discovers and routes tools
registry.register_agent("your_agent", YourAgent(config))

发展

项目结构

mcp_server_full/
├── agents/                    # Agent implementations
│   ├── base.py               # Base agent interface
│   ├── openai_agent.py       # OpenAI integration
│   ├── ollama_agent.py       # Ollama integration
│   └── file_agent.py         # File operations
├── pure_mcp_server.py        # Main MCP server for Claude Desktop
├── simple_mcp_host.py        # HTTP host for web interfaces
├── registry.py               # Dynamic tool registration
├── run_mcp_server.py         # Claude Desktop entry point
├── streamlit_app.py          # Web UI
├── config.py                 # Configuration management
├── protocol.py               # MCP protocol models
├── requirements.txt          # Dependencies
├── .env                      # Environment variables (create this)
├── ADDING_NEW_AGENTS.md      # Detailed agent development guide
└── README.md                 # This file

添加新代理

有关添加新代理的完整分步指南，请参阅 添加_新闻_新闻.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. 更新文档

例子：

# In your agent
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密钥和服务连接

   # Test agent registration
   python test_quick.py

1. 克劳德桌面未连接：验证配置路径和入口点

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

1. 简化UI问题：确保HTTP主机正在运行

   # Start HTTP host first
   python simple_mcp_host.py
   # Then start Streamlit  
   streamlit run streamlit_app.py

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

   # Test OpenAI directly
   python openai_test.py

1. Ollama不工作：验证Ollama服务器是否正在运行

   # Check Ollama status
   curl http://localhost:11434/api/tags

调试模式

启用详细日志记录：

# Set environment variable
export LOG_LEVEL=DEBUG
python run_mcp_server.py

健康检查

# Check HTTP API health
curl http://localhost:8000/health

# List registered tools
curl http://localhost:8000/tools

# Test tool call
curl -X POST http://localhost:8000/tools/call \
  -H "Content-Type: application/json" \
  -d '{"tool_name": "file_list", "arguments": {"directory_path": "."}}'

依赖项

核心运行时

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

特定代理

• openai：OpenAI API客户端（用于OpenAI代理）
• 成为：Ollama API客户（用于Ollama代理商）

web界面

• 流明：现代web UI框架
• 请求：：Streamlit的HTTP请求

开发与测试

• pytest：测试框架
• 日志记录：调试和监控

所有依赖项都是通过自动安装的 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并创建使用示例

许可证

麻省理工学院

流线型Web界面

Streamlit应用程序为所有MCP工具提供了一个直观的web界面。

特性

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

用法

1. 启动后端: python simple_mcp_host.py
2. 发射Streamlit: streamlit run streamlit_app.py
3. 打开浏览器：导航到http://localhost:8501
4. 选择工具：从可用的代理工具中选择
5. 执行：以交互方式填充参数和运行工具

工具集成

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