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許可證。