Pure Agentic MCP Server

# Pure Agentic MCP Server A pure implementation of the Model Context Protocol (MCP) following an agentic architecture where all features are exposed as MCP tools through specialized agents. ## Features - **🤖 Pure Agentic Architecture**: All capabilities (OpenAI, Ollama, File operations) are implemented as agents - **🔗 Dual Access Modes**: MCP protocol for Claude Desktop + HTTP endpoints for web/Streamlit UI - **⚡ Dynamic Tool Registry**: Agents register their tools automatically at startup - **🔧 Modular Design**: Add new agents easily without modifying core server code - **📱 Clean Web UI**: Modern Streamlit interface for interactive tool usage - **🛡️ Graceful Degradation**: Agents fail independently without affecting the system - **🔑 Environment-Based Config**: Secure API key management via environment variables ## Architecture Overview The server implements a **pure agentic pattern** where: 1. **Agents** encapsulate specific functionality (OpenAI API, Ollama, file operations) 2. **Registry** manages dynamic tool registration and routing 3. **MCP Server** provides JSON-RPC protocol compliance for Claude Desktop 4. **HTTP Host** exposes tools via REST API for web interfaces 5. **Streamlit UI** provides user-friendly web access to all tools ``` Claude Desktop ←→ MCP Protocol ←→ Pure MCP Server ←→ Agent Registry ←→ Agents ↕ Web Browser ←→ HTTP API ←→ Simple MCP Host ←→ Agent Registry ←→ Agents ``` ## Quick Start ### Prerequisites - Python 3.11+ - Virtual environment support ### Installation ```bash git clone <repo-url> 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 ``` ### Configuration Create a `.env` file with your API keys (all optional): ```env # 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 ``` ### Running the Server #### For Claude Desktop (MCP Protocol) ```bash # Start the pure MCP server for Claude Desktop python run_mcp_server.py ``` Add to your Claude Desktop config (`claude_desktop_config.json`): ```json { "mcpServers": { "agentic-mcp": { "command": "python", "args": ["run_mcp_server.py"], "cwd": "d:\\AI Lab\\MCP research\\mcp_server_full" } } } ``` #### For Web Interface (HTTP + Streamlit) ```bash # Terminal 1: Start HTTP host for tools python simple_mcp_host.py # Terminal 2: Start Streamlit UI streamlit run streamlit_app.py ``` Access the web interface at: http://localhost:8501 ### Testing Your Setup ```bash # Test agent registration and tool availability python test_quick.py # Test specific agents python test_both.py # Validate server functionality python validate_server.py ``` ## Available Agents & Tools ### 🤖 OpenAI Agent **Status**: Available with API key **Tools**: - `openai_chat`: Chat completion with GPT models - `openai_analysis`: Text analysis and insights **Setup**: Add `OPENAI_API_KEY` to `.env` file ### 🦙 Ollama Agent **Status**: Available with local Ollama server **Tools**: - `ollama_chat`: Chat with local Ollama models - `ollama_generate`: Text generation **Setup**: Install and run Ollama locally, configure `OLLAMA_BASE_URL` and `OLLAMA_MODEL` ### 📁 File Agent **Status**: Always available **Tools**: - `file_read`: Read file contents - `file_write`: Write content to files - `file_list`: List directory contents **Setup**: No configuration needed ## API Usage ### MCP Protocol (Claude Desktop) Tools are automatically available in Claude Desktop once the server is configured. Ask Claude to: - "Read the contents of file.txt" - "Generate text using Ollama" - "Analyze this text with OpenAI" ### HTTP API (Web/Streamlit) ```bash # 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" } }' ``` ## Architecture ### Core Components - **`pure_mcp_server.py`**: Main MCP JSON-RPC server for Claude Desktop integration - **`simple_mcp_host.py`**: HTTP wrapper that exposes MCP tools via REST API - **`registry.py`**: Dynamic agent and tool registration system - **`run_mcp_server.py`**: Entry point script for Claude Desktop configuration - **`config.py`**: Environment-based configuration management - **`protocol.py`**: MCP protocol models and types ### Agents - **`agents/base.py`**: Base agent interface that all agents implement - **`agents/openai_agent.py`**: OpenAI API integration agent - **`agents/ollama_agent.py`**: Local Ollama model integration agent - **`agents/file_agent.py`**: File system operations agent ### User Interfaces - **`streamlit_app.py`**: Modern web UI for interactive tool usage - **Claude Desktop**: Direct MCP protocol integration ### Agent Registration Flow ```python # 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)) ``` ## Development ### Project Structure ``` 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 ``` ### Adding New Agents For a complete step-by-step guide on adding new agents, see **[ADDING_NEW_AGENTS.md](ADDING_NEW_AGENTS.md)**. **Quick Overview:** 1. Create agent file in `agents/` inheriting from `BaseAgent` 2. Implement `get_tools()` and `handle_tool_call()` methods 3. Register agent in both `pure_mcp_server.py` and `simple_mcp_host.py` 4. Add configuration and test your agent The guide includes complete code examples, best practices, and troubleshooting tips. ### Adding New Tools To add new tools to existing agents: 1. Edit the agent's `get_tools()` method to define new tool schema 2. Add handler method in agent's `handle_tool_call()` method 3. Test the new tool functionality 4. Update documentation Example: ```python # 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) ``` ## Troubleshooting ### Common Issues 1. **Agent Not Available**: Check API keys and service connectivity ```bash # Test agent registration python test_quick.py ``` 2. **Claude Desktop Not Connecting**: Verify config path and entry point ```json # Check 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 Issues**: Ensure HTTP host is running ```bash # Start HTTP host first python simple_mcp_host.py # Then start Streamlit streamlit run streamlit_app.py ``` 4. **OpenAI Errors**: Check API key and quota ```bash # Test OpenAI directly python openai_test.py ``` 5. **Ollama Not Working**: Verify Ollama server is running ```bash # Check Ollama status curl http://localhost:11434/api/tags ``` ### Debug Mode Enable detailed logging: ```bash # Set environment variable export LOG_LEVEL=DEBUG python run_mcp_server.py ``` ### Health Checks ```bash # 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": "."}}' ``` ## Dependencies ### Core Runtime - **pydantic**: Configuration and data validation - **asyncio**: Async operation support - **httpx**: HTTP client for external APIs - **aiofiles**: Async file operations ### Agent-Specific - **openai**: OpenAI API client (for OpenAI agent) - **ollama**: Ollama API client (for Ollama agent) ### Web Interface - **streamlit**: Modern web UI framework - **requests**: HTTP requests for Streamlit ### Development & Testing - **pytest**: Testing framework - **logging**: Debug and monitoring All dependencies are automatically installed via `requirements.txt`. ## Contributing 1. Fork the repository 2. Create a feature branch: `git checkout -b feature/your-feature` 3. Add your agent following the [agent development guide](ADDING_NEW_AGENTS.md) 4. Test your changes: `python test_quick.py` 5. Submit a pull request ### Agent Development Workflow 1. **Plan**: Define what tools your agent will provide 2. **Implement**: Create agent class inheriting from `BaseAgent` 3. **Register**: Add agent registration to both server files 4. **Test**: Verify agent works in both MCP and HTTP modes 5. **Document**: Update README and create usage examples ## License MIT ## Streamlit Web Interface The Streamlit app provides an intuitive web interface for all MCP tools. ### Features - **🔧 Real-time Tool Discovery**: Automatically displays all available tools from registered agents - **💬 Interactive Interface**: Easy-to-use forms for tool parameters - **📊 Response Display**: Formatted display of tool results - **� Agent Status**: Real-time monitoring of agent availability - **⚙️ Configuration**: Environment-based setup with clear status indicators ### Usage 1. **Start the backend**: `python simple_mcp_host.py` 2. **Launch Streamlit**: `streamlit run streamlit_app.py` 3. **Open browser**: Navigate to http://localhost:8501 4. **Select tools**: Choose from available agent tools 5. **Execute**: Fill parameters and run tools interactively ### Tool Integration The Streamlit UI automatically discovers and creates forms for any tools registered by agents, making it easy to test and use new functionality as agents are added.