1 line
385 KiB
JSON
1 line
385 KiB
JSON
{"repo": "amranu/cli-agent", "files": {"README.md": {"dbc208eaa22c3af5532553cfe9c9784658c0ac9a": {"t": 1785746491.8244526, "n": 18492, "h": "c5b988d77e62ab44", "c": "# CLI Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, OpenRouter, and ollama with easy extensibility\n- **Deep Research System**: Coordinated multi-subagent research workflow with autonomous report generation\n- **Hooks System**: Powerful workflow automation with security controls - audit commands, block dangerous operations, auto-format code, and integrate with external tools\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n### Option 1: Install from PyPI (Recommended)\n\n```bash\npip install mcp-cli-agent\n```\n\n### Option 2: Install from Source\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/cli-agent.git\n cd cli-agent\n ```\n\n2. **Install the package**:\n ```bash\n pip install -e .\n ```\n\n## ⚙️ Configuration\n\n**Configure API keys** (environment variables):\n\n```bash\n # Set environment variables for the providers you want to use\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Start with automatic provider selection\n agent chat\n \n # Or specify a particular provider-model combination\n agent chat --model openai:gpt-4-turbo-preview\n```\n\n**Smart Provider Selection**: The agent automatically selects a configured provider based on available API keys.\n\nConfiguration is automatically saved to `~/.config/cli-agent/config.json` and persists across sessions.\n\n**Migration from MCP Agent**: If you previously used MCP Agent, your configuration will be automatically migrated from `~/.config/mcp-agent/` to `~/.config/cli-agent/` on first run.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI (defaults to stdio)\nagent mcp serve\nagent mcp serve --stdio # explicit stdio\n\n# Start with TCP transport (useful for debugging)\npython mcp_server.py --tcp --port 3000 --host localhost\nagent mcp serve --tcp --port 3000 --host localhost\n```\n\nThe model server exposes AI models from 6 providers:\n- **Anthropic**: Claude models\n- **OpenAI**: GPT models\n- **DeepSeek**: Chat and reasoning models\n- **Gemini**: Google's Gemini models\n- **OpenRouter**: Multi-provider access\n- **Ollama**: Local models via Ollama server\n\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\nagent mcp add myserver:node:/path/to/server.js\nagent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\nagent mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\nagent mcp list\n```\n\n#### Remove a server\n\n```bash\nagent mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\nagent ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\nagent switch anthropic:claude-3.5-sonnet\nagent switch openai:gpt-4-turbo-preview\nagent switch deepseek:deepseek-chat\nagent switch gemini:gemini-2.5-flash\n\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/cli-agent/config.json`:\n\n- **API Keys**: Set via environment variables\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Subagent Configuration\nSUBAGENT_PERMISSIONS_BYPASS=false # bypass permission checks for subagents, defaults to false\n\n# Host Configuration (optional)\nHOST_NAME=cli-agent # defaults to 'cli-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n\n### AI Model Tools (via MCP Server)\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n- `/deep-research <topic>` - Launch coordinated multi-subagent research workflow\n\n## 📚 Examples\n\n\n### Example: Basic File Operations\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: Can you analyze all Python files in the src/ directory and create a summary of the class structure and dependencies?\n [Agent automatically spawns subagent using the task tool]\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n### Example: Deep Research Workflow\n\nFor comprehensive research on complex topics, use the coordinated multi-subagent research system:\n\n```\nYou: /deep-research Enterprise AI Adoption in Healthcare 2024\n\n[System switches to Research Director role and launches automated workflow]\n\nResearch Director: \n1. Creates comprehensive todo list for tracking research phases\n2. Breaks down topic into focused sub-topics (e.g., \"Current AI Tools\", \"Implementation Challenges\", \"ROI Analysis\", \"Future Trends\")\n3. Spawns multiple researcher role subagents in parallel\n4. Each researcher conducts web searches and creates 3+ source summaries\n5. Creates detailed outline based on all research findings\n6. Spawns single summarizer role subagent to write sections\n7. Assembles final 10-12 page executive report automatically\n8. Displays completed research report to user\n\nFinal Output: `/tmp/deep_research_master_report_[topic]_[timestamp].md`\n```\n\n**Key Features:**\n- **Autonomous Operation**: Runs start-to-finish without user intervention\n- **Parallel Research**: Multiple subagents work simultaneously on different aspects\n- **Role-Based Coordination**: Research Director → Researchers → Summarizer workflow\n- **Comprehensive Coverage**: Targets 10-100 sources across academic, industry, news, and expert sources\n- **Executive Quality**: Professional 10-12 page reports with structured analysis\n\n## 🔬 Deep Research System\n\nThe CLI Agent features a sophisticated deep research system that coordinates multiple specialized subagents to conduct comprehensive research on complex topics.\n\n### Research Workflow\n\nThe `/deep-research` command launches a fully autonomous research process:\n\n1. **Topic Analysis**: Research Director analyzes the topic and creates comprehensive todo tracking\n2. **Parallel Research**: Spawns 3-5 researcher role subagents to work simultaneously on different sub-topics\n3. **Source Collection**: Each researcher conducts web searches and creates detailed source summaries (minimum 3 sources each)\n4. **Outline Creation**: Research Director reviews all findings and creates detailed 8-10 section outline\n5. **Report Writing**: Single summarizer role subagent writes all sections with 3-round iterative refinement\n6. **Final Assembly**: Automatically concatenates sections into executive-quality master report\n\n### Research Roles\n\n- **Research Director**: Coordinates the entire workflow, manages todo tracking, and assembles final reports\n- **Researcher**: Conducts web searches, reads sources, and creates comprehensive summaries\n- **Summarizer**: Writes structured report sections based on research findings with iterative refinement\n\n### Output Quality\n\n- **Target Length**: 10-12 pages (5,000-6,000 words)\n- **Source Coverage**: 10-100 sources across academic, industry, news, and expert categories\n- **Structure**: Executive summary, detailed analysis, key findings, recommendations\n- **Format**: Professional markdown reports with proper citations and structure\n\n### Usage Examples\n\n```bash\n# Technology research\n/deep-research Enterprise AI Adoption in Healthcare 2024\n\n# Market analysis\n/deep-research Competitive Analysis of Electric Vehicle Market 2024\n\n# Technical investigation\n/deep-research Cybersecurity Threats in Cloud Infrastructure\n\n# Industry trends\n/deep-research Future of Remote Work Technologies Post-2024\n```\n\nAll research is conducted autonomously without user intervention, producing publication-ready reports.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐\n│ CLI Interface │ \n│ (agent.py) │ \n└─────────┬───────┘ \n │ \n ▼ \n┌─────────────────────┐ ┌─────────────────────────────────────────┐\n│ MCPHost │◄───│ Provider + Model │\n│ (BaseLLMProvider) │ │ Composition │\n└─────────┬───────────┘ │ ┌─────────────────┐ ┌─────────────────┐ │\n │ │ │ BaseProvider │ │ ModelConfig │ │\n ▼ │ │ Subclasses: │ │ Subclasses: │ │\n┌─────────────────────┐ │ │ • Anthropic │ │ • ClaudeModel │ │\n│ BaseLLMProvider │ │ │ • OpenAI │ │ • GPTModel │ │\n│ (Centralized LLM │ │ │ • DeepSeek │ │ • GeminiModel │ │\n│ functionality) │ │ │ • Google │ │ • DeepSeekModel │ │\n└─────────┬───────────┘ │ │ • OpenRouter │ │ │ │\n │ │ └─────────────────┘ └─────────────────┘ │\n ▼ └─────────────────────────────────────────┘\n┌─────────────────────┐ │\n│ BaseMCPAgent │ ▼\n│ (Abstract base) │ ┌─────────────────┐\n└─────────┬───────────┘ │ Tool Converters │\n │ │ • OpenAI Format │\n┌─────────▼───────────┐ │ • Anthropic │\n│ Core Components: │ │ • Gemini │\n│ • SubagentCoordinator│ └─────────────────┘\n│ • BuiltinToolExecutor│ \n│ • ChatInterface │ ┌─────────────────┐\n│ • SlashCommands │◄───────────────│ Built-in Tools │\n│ • ToolExecutionEngine│ │ • File Ops │\n│ • TokenManager │ │ • Bash Execute │\n│ • SystemPromptBuilder│ │ • Web Fetch │\n│ • MessageProcessor │ │ • Todo Mgmt │\n└─────────┬───────────┘ │ • Task Spawn │\n │ │ • Glob/Grep │\n ▼ │ • MultiEdit │\n┌─────────────────────┐ └─────────────────┘\n│ External MCP Servers │ \n│ • AI Model Server │ ┌─────────────────┐\n│ • File System │ │ Subagent System │\n│ • APIs & Databases │ │ • Focused Tasks │\n│ • Custom Tools │ │ • Auto Cleanup │\n└─────────────────────┘ │ • Event-Driven │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables\n- **Configuration**: Automatically managed in user home directory (`~/.config/cli-agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n- **Subagent Permissions**: Can be configured to bypass permission checks for automated workflows via `SUBAGENT_PERMISSIONS_BYPASS=true`\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/cli-agent/issues)\n- 💬 [Discussions](https://github.com/amranu/cli-agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/cli-agent/wiki)\n\n---\n\n**Happy coding with CLI Agent! 🤖✨**\n"}, "13a8f9dbbf32a1ce25ae1aa1a1777d7b68935253": {"t": 1785764902.868182, "n": 18492, "h": "c5b988d77e62ab44", "c": "# CLI Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, OpenRouter, and ollama with easy extensibility\n- **Deep Research System**: Coordinated multi-subagent research workflow with autonomous report generation\n- **Hooks System**: Powerful workflow automation with security controls - audit commands, block dangerous operations, auto-format code, and integrate with external tools\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n### Option 1: Install from PyPI (Recommended)\n\n```bash\npip install mcp-cli-agent\n```\n\n### Option 2: Install from Source\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/cli-agent.git\n cd cli-agent\n ```\n\n2. **Install the package**:\n ```bash\n pip install -e .\n ```\n\n## ⚙️ Configuration\n\n**Configure API keys** (environment variables):\n\n```bash\n # Set environment variables for the providers you want to use\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Start with automatic provider selection\n agent chat\n \n # Or specify a particular provider-model combination\n agent chat --model openai:gpt-4-turbo-preview\n```\n\n**Smart Provider Selection**: The agent automatically selects a configured provider based on available API keys.\n\nConfiguration is automatically saved to `~/.config/cli-agent/config.json` and persists across sessions.\n\n**Migration from MCP Agent**: If you previously used MCP Agent, your configuration will be automatically migrated from `~/.config/mcp-agent/` to `~/.config/cli-agent/` on first run.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI (defaults to stdio)\nagent mcp serve\nagent mcp serve --stdio # explicit stdio\n\n# Start with TCP transport (useful for debugging)\npython mcp_server.py --tcp --port 3000 --host localhost\nagent mcp serve --tcp --port 3000 --host localhost\n```\n\nThe model server exposes AI models from 6 providers:\n- **Anthropic**: Claude models\n- **OpenAI**: GPT models\n- **DeepSeek**: Chat and reasoning models\n- **Gemini**: Google's Gemini models\n- **OpenRouter**: Multi-provider access\n- **Ollama**: Local models via Ollama server\n\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\nagent mcp add myserver:node:/path/to/server.js\nagent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\nagent mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\nagent mcp list\n```\n\n#### Remove a server\n\n```bash\nagent mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\nagent ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\nagent switch anthropic:claude-3.5-sonnet\nagent switch openai:gpt-4-turbo-preview\nagent switch deepseek:deepseek-chat\nagent switch gemini:gemini-2.5-flash\n\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/cli-agent/config.json`:\n\n- **API Keys**: Set via environment variables\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Subagent Configuration\nSUBAGENT_PERMISSIONS_BYPASS=false # bypass permission checks for subagents, defaults to false\n\n# Host Configuration (optional)\nHOST_NAME=cli-agent # defaults to 'cli-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n\n### AI Model Tools (via MCP Server)\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n- `/deep-research <topic>` - Launch coordinated multi-subagent research workflow\n\n## 📚 Examples\n\n\n### Example: Basic File Operations\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: Can you analyze all Python files in the src/ directory and create a summary of the class structure and dependencies?\n [Agent automatically spawns subagent using the task tool]\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n### Example: Deep Research Workflow\n\nFor comprehensive research on complex topics, use the coordinated multi-subagent research system:\n\n```\nYou: /deep-research Enterprise AI Adoption in Healthcare 2024\n\n[System switches to Research Director role and launches automated workflow]\n\nResearch Director: \n1. Creates comprehensive todo list for tracking research phases\n2. Breaks down topic into focused sub-topics (e.g., \"Current AI Tools\", \"Implementation Challenges\", \"ROI Analysis\", \"Future Trends\")\n3. Spawns multiple researcher role subagents in parallel\n4. Each researcher conducts web searches and creates 3+ source summaries\n5. Creates detailed outline based on all research findings\n6. Spawns single summarizer role subagent to write sections\n7. Assembles final 10-12 page executive report automatically\n8. Displays completed research report to user\n\nFinal Output: `/tmp/deep_research_master_report_[topic]_[timestamp].md`\n```\n\n**Key Features:**\n- **Autonomous Operation**: Runs start-to-finish without user intervention\n- **Parallel Research**: Multiple subagents work simultaneously on different aspects\n- **Role-Based Coordination**: Research Director → Researchers → Summarizer workflow\n- **Comprehensive Coverage**: Targets 10-100 sources across academic, industry, news, and expert sources\n- **Executive Quality**: Professional 10-12 page reports with structured analysis\n\n## 🔬 Deep Research System\n\nThe CLI Agent features a sophisticated deep research system that coordinates multiple specialized subagents to conduct comprehensive research on complex topics.\n\n### Research Workflow\n\nThe `/deep-research` command launches a fully autonomous research process:\n\n1. **Topic Analysis**: Research Director analyzes the topic and creates comprehensive todo tracking\n2. **Parallel Research**: Spawns 3-5 researcher role subagents to work simultaneously on different sub-topics\n3. **Source Collection**: Each researcher conducts web searches and creates detailed source summaries (minimum 3 sources each)\n4. **Outline Creation**: Research Director reviews all findings and creates detailed 8-10 section outline\n5. **Report Writing**: Single summarizer role subagent writes all sections with 3-round iterative refinement\n6. **Final Assembly**: Automatically concatenates sections into executive-quality master report\n\n### Research Roles\n\n- **Research Director**: Coordinates the entire workflow, manages todo tracking, and assembles final reports\n- **Researcher**: Conducts web searches, reads sources, and creates comprehensive summaries\n- **Summarizer**: Writes structured report sections based on research findings with iterative refinement\n\n### Output Quality\n\n- **Target Length**: 10-12 pages (5,000-6,000 words)\n- **Source Coverage**: 10-100 sources across academic, industry, news, and expert categories\n- **Structure**: Executive summary, detailed analysis, key findings, recommendations\n- **Format**: Professional markdown reports with proper citations and structure\n\n### Usage Examples\n\n```bash\n# Technology research\n/deep-research Enterprise AI Adoption in Healthcare 2024\n\n# Market analysis\n/deep-research Competitive Analysis of Electric Vehicle Market 2024\n\n# Technical investigation\n/deep-research Cybersecurity Threats in Cloud Infrastructure\n\n# Industry trends\n/deep-research Future of Remote Work Technologies Post-2024\n```\n\nAll research is conducted autonomously without user intervention, producing publication-ready reports.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐\n│ CLI Interface │ \n│ (agent.py) │ \n└─────────┬───────┘ \n │ \n ▼ \n┌─────────────────────┐ ┌─────────────────────────────────────────┐\n│ MCPHost │◄───│ Provider + Model │\n│ (BaseLLMProvider) │ │ Composition │\n└─────────┬───────────┘ │ ┌─────────────────┐ ┌─────────────────┐ │\n │ │ │ BaseProvider │ │ ModelConfig │ │\n ▼ │ │ Subclasses: │ │ Subclasses: │ │\n┌─────────────────────┐ │ │ • Anthropic │ │ • ClaudeModel │ │\n│ BaseLLMProvider │ │ │ • OpenAI │ │ • GPTModel │ │\n│ (Centralized LLM │ │ │ • DeepSeek │ │ • GeminiModel │ │\n│ functionality) │ │ │ • Google │ │ • DeepSeekModel │ │\n└─────────┬───────────┘ │ │ • OpenRouter │ │ │ │\n │ │ └─────────────────┘ └─────────────────┘ │\n ▼ └─────────────────────────────────────────┘\n┌─────────────────────┐ │\n│ BaseMCPAgent │ ▼\n│ (Abstract base) │ ┌─────────────────┐\n└─────────┬───────────┘ │ Tool Converters │\n │ │ • OpenAI Format │\n┌─────────▼───────────┐ │ • Anthropic │\n│ Core Components: │ │ • Gemini │\n│ • SubagentCoordinator│ └─────────────────┘\n│ • BuiltinToolExecutor│ \n│ • ChatInterface │ ┌─────────────────┐\n│ • SlashCommands │◄───────────────│ Built-in Tools │\n│ • ToolExecutionEngine│ │ • File Ops │\n│ • TokenManager │ │ • Bash Execute │\n│ • SystemPromptBuilder│ │ • Web Fetch │\n│ • MessageProcessor │ │ • Todo Mgmt │\n└─────────┬───────────┘ │ • Task Spawn │\n │ │ • Glob/Grep │\n ▼ │ • MultiEdit │\n┌─────────────────────┐ └─────────────────┘\n│ External MCP Servers │ \n│ • AI Model Server │ ┌─────────────────┐\n│ • File System │ │ Subagent System │\n│ • APIs & Databases │ │ • Focused Tasks │\n│ • Custom Tools │ │ • Auto Cleanup │\n└─────────────────────┘ │ • Event-Driven │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables\n- **Configuration**: Automatically managed in user home directory (`~/.config/cli-agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n- **Subagent Permissions**: Can be configured to bypass permission checks for automated workflows via `SUBAGENT_PERMISSIONS_BYPASS=true`\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/cli-agent/issues)\n- 💬 [Discussions](https://github.com/amranu/cli-agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/cli-agent/wiki)\n\n---\n\n**Happy coding with CLI Agent! 🤖✨**\n"}, "b34c58f81fe1ecedb5bfc3fc544b278ec5d5925c": {"t": 1785764904.5282807, "n": 14853, "h": "47fcbbc2b22a2013", "c": "# CLI Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, OpenRouter, and ollama with easy extensibility\n- **Hooks System**: Powerful workflow automation with security controls - audit commands, block dangerous operations, auto-format code, and integrate with external tools\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n### Option 1: Install from PyPI (Recommended)\n\n```bash\npip install mcp-cli-agent\n```\n\n### Option 2: Install from Source\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/cli-agent.git\n cd cli-agent\n ```\n\n2. **Install the package**:\n ```bash\n pip install -e .\n ```\n\n## ⚙️ Configuration\n\n**Configure API keys** (environment variables):\n\n```bash\n # Set environment variables for the providers you want to use\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Start with automatic provider selection\n agent chat\n \n # Or specify a particular provider-model combination\n agent chat --model openai:gpt-4-turbo-preview\n```\n\n**Smart Provider Selection**: The agent automatically selects a configured provider based on available API keys.\n\nConfiguration is automatically saved to `~/.config/cli-agent/config.json` and persists across sessions.\n\n**Migration from MCP Agent**: If you previously used MCP Agent, your configuration will be automatically migrated from `~/.config/mcp-agent/` to `~/.config/cli-agent/` on first run.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI (defaults to stdio)\nagent mcp serve\nagent mcp serve --stdio # explicit stdio\n\n# Start with TCP transport (useful for debugging)\npython mcp_server.py --tcp --port 3000 --host localhost\nagent mcp serve --tcp --port 3000 --host localhost\n```\n\nThe model server exposes AI models from 6 providers:\n- **Anthropic**: Claude models\n- **OpenAI**: GPT models\n- **DeepSeek**: Chat and reasoning models\n- **Gemini**: Google's Gemini models\n- **OpenRouter**: Multi-provider access\n- **Ollama**: Local models via Ollama server\n\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\nagent mcp add myserver:node:/path/to/server.js\nagent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\nagent mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\nagent mcp list\n```\n\n#### Remove a server\n\n```bash\nagent mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\nagent ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\nagent switch anthropic:claude-3.5-sonnet\nagent switch openai:gpt-4-turbo-preview\nagent switch deepseek:deepseek-chat\nagent switch gemini:gemini-2.5-flash\n\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/cli-agent/config.json`:\n\n- **API Keys**: Set via environment variables\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Subagent Configuration\nSUBAGENT_PERMISSIONS_BYPASS=false # bypass permission checks for subagents, defaults to false\n\n# Host Configuration (optional)\nHOST_NAME=cli-agent # defaults to 'cli-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n\n### AI Model Tools (via MCP Server)\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n\n## 📚 Examples\n\n\n### Example: Basic File Operations\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: Can you analyze all Python files in the src/ directory and create a summary of the class structure and dependencies?\n [Agent automatically spawns subagent using the task tool]\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐\n│ CLI Interface │ \n│ (agent.py) │ \n└─────────┬───────┘ \n │ \n ▼ \n┌─────────────────────┐ ┌─────────────────────────────────────────┐\n│ MCPHost │◄───│ Provider + Model │\n│ (BaseLLMProvider) │ │ Composition │\n└─────────┬───────────┘ │ ┌─────────────────┐ ┌─────────────────┐ │\n │ │ │ BaseProvider │ │ ModelConfig │ │\n ▼ │ │ Subclasses: │ │ Subclasses: │ │\n┌─────────────────────┐ │ │ • Anthropic │ │ • ClaudeModel │ │\n│ BaseLLMProvider │ │ │ • OpenAI │ │ • GPTModel │ │\n│ (Centralized LLM │ │ │ • DeepSeek │ │ • GeminiModel │ │\n│ functionality) │ │ │ • Google │ │ • DeepSeekModel │ │\n└─────────┬───────────┘ │ │ • OpenRouter │ │ │ │\n │ │ └─────────────────┘ └─────────────────┘ │\n ▼ └─────────────────────────────────────────┘\n┌─────────────────────┐ │\n│ BaseMCPAgent │ ▼\n│ (Abstract base) │ ┌─────────────────┐\n└─────────┬───────────┘ │ Tool Converters │\n │ │ • OpenAI Format │\n┌─────────▼───────────┐ │ • Anthropic │\n│ Core Components: │ │ • Gemini │\n│ • SubagentCoordinator│ └─────────────────┘\n│ • BuiltinToolExecutor│ \n│ • ChatInterface │ ┌─────────────────┐\n│ • SlashCommands │◄───────────────│ Built-in Tools │\n│ • ToolExecutionEngine│ │ • File Ops │\n│ • TokenManager │ │ • Bash Execute │\n│ • SystemPromptBuilder│ │ • Web Fetch │\n│ • MessageProcessor │ │ • Todo Mgmt │\n└─────────┬───────────┘ │ • Task Spawn │\n │ │ • Glob/Grep │\n ▼ │ • MultiEdit │\n┌─────────────────────┐ └─────────────────┘\n│ External MCP Servers │ \n│ • AI Model Server │ ┌─────────────────┐\n│ • File System │ │ Subagent System │\n│ • APIs & Databases │ │ • Focused Tasks │\n│ • Custom Tools │ │ • Auto Cleanup │\n└─────────────────────┘ │ • Event-Driven │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables\n- **Configuration**: Automatically managed in user home directory (`~/.config/cli-agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n- **Subagent Permissions**: Can be configured to bypass permission checks for automated workflows via `SUBAGENT_PERMISSIONS_BYPASS=true`\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/cli-agent/issues)\n- 💬 [Discussions](https://github.com/amranu/cli-agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/cli-agent/wiki)\n\n---\n\n**Happy coding with CLI Agent! 🤖✨**\n"}, "f8797ce15228fcd3a4d8cb8df70a1dca6d593787": {"t": 1785764905.8543868, "n": 14836, "h": "29fa4a36637b9a91", "c": "# CLI Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, OpenRouter, and ollama with easy extensibility\n- **Hooks System**: Powerful workflow automation with security controls - audit commands, block dangerous operations, auto-format code, and integrate with external tools\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n### Option 1: Install from PyPI (Recommended)\n\n```bash\npip install mcp-cli-agent\n```\n\n### Option 2: Install from Source\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/cli-agent.git\n cd cli-agent\n ```\n\n2. **Install the package**:\n ```bash\n pip install -e .\n ```\n\n## ⚙️ Configuration\n\n**Configure API keys** (environment variables):\n\n```bash\n # Set environment variables for the providers you want to use\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Start with automatic provider selection\n agent chat\n \n # Or specify a particular provider-model combination\n agent chat --model openai:gpt-4-turbo-preview\n```\n\n**Smart Provider Selection**: The agent automatically selects a configured provider based on available API keys.\n\nConfiguration is automatically saved to `~/.config/cli-agent/config.json` and persists across sessions.\n\n**Migration from MCP Agent**: If you previously used MCP Agent, your configuration will be automatically migrated from `~/.config/mcp-agent/` to `~/.config/cli-agent/` on first run.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI (defaults to stdio)\nagent mcp serve\nagent mcp serve --stdio # explicit stdio\n\n# Start with TCP transport (useful for debugging)\npython mcp_server.py --tcp --port 3000 --host localhost\nagent mcp serve --tcp --port 3000 --host localhost\n```\n\nThe model server exposes AI models from 6 providers:\n- **Anthropic**: Claude models\n- **OpenAI**: GPT models\n- **DeepSeek**: Chat and reasoning models\n- **Gemini**: Google's Gemini models\n- **OpenRouter**: Multi-provider access\n- **Ollama**: Local models via Ollama server\n\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\nagent mcp add myserver:node:/path/to/server.js\nagent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\nagent mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\nagent mcp list\n```\n\n#### Remove a server\n\n```bash\nagent mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\nagent ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\nagent switch anthropic:claude-3.5-sonnet\nagent switch openai:gpt-4-turbo-preview\nagent switch deepseek:deepseek-chat\nagent switch gemini:gemini-2.5-flash\n\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/cli-agent/config.json`:\n\n- **API Keys**: Set via environment variables\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Subagent Configuration\nSUBAGENT_PERMISSIONS_BYPASS=false # bypass permission checks for subagents, defaults to false\n\n# Host Configuration (optional)\nHOST_NAME=cli-agent # defaults to 'cli-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n\n### AI Model Tools (via MCP Server)\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n- `/task` - Spawn a subagent for complex tasks\n\n## 📚 Examples\n\n\n### Example: Basic File Operations\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐\n│ CLI Interface │ \n│ (agent.py) │ \n└─────────┬───────┘ \n │ \n ▼ \n┌─────────────────────┐ ┌─────────────────────────────────────────┐\n│ MCPHost │◄───│ Provider + Model │\n│ (BaseLLMProvider) │ │ Composition │\n└─────────┬───────────┘ │ ┌─────────────────┐ ┌─────────────────┐ │\n │ │ │ BaseProvider │ │ ModelConfig │ │\n ▼ │ │ Subclasses: │ │ Subclasses: │ │\n┌─────────────────────┐ │ │ • Anthropic │ │ • ClaudeModel │ │\n│ BaseLLMProvider │ │ │ • OpenAI │ │ • GPTModel │ │\n│ (Centralized LLM │ │ │ • DeepSeek │ │ • GeminiModel │ │\n│ functionality) │ │ │ • Google │ │ • DeepSeekModel │ │\n└─────────┬───────────┘ │ │ • OpenRouter │ │ │ │\n │ │ └─────────────────┘ └─────────────────┘ │\n ▼ └─────────────────────────────────────────┘\n┌─────────────────────┐ │\n│ BaseMCPAgent │ ▼\n│ (Abstract base) │ ┌─────────────────┐\n└─────────┬───────────┘ │ Tool Converters │\n │ │ • OpenAI Format │\n┌─────────▼───────────┐ │ • Anthropic │\n│ Core Components: │ │ • Gemini │\n│ • SubagentCoordinator│ └─────────────────┘\n│ • BuiltinToolExecutor│ \n│ • ChatInterface │ ┌─────────────────┐\n│ • SlashCommands │◄───────────────│ Built-in Tools │\n│ • ToolExecutionEngine│ │ • File Ops │\n│ • TokenManager │ │ • Bash Execute │\n│ • SystemPromptBuilder│ │ • Web Fetch │\n│ • MessageProcessor │ │ • Todo Mgmt │\n└─────────┬───────────┘ │ • Task Spawn │\n │ │ • Glob/Grep │\n ▼ │ • MultiEdit │\n┌─────────────────────┐ └─────────────────┘\n│ External MCP Servers │ \n│ • AI Model Server │ ┌─────────────────┐\n│ • File System │ │ Subagent System │\n│ • APIs & Databases │ │ • Focused Tasks │\n│ • Custom Tools │ │ • Auto Cleanup │\n└─────────────────────┘ │ • Event-Driven │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables\n- **Configuration**: Automatically managed in user home directory (`~/.config/cli-agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n- **Subagent Permissions**: Can be configured to bypass permission checks for automated workflows via `SUBAGENT_PERMISSIONS_BYPASS=true`\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/cli-agent/issues)\n- 💬 [Discussions](https://github.com/amranu/cli-agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/cli-agent/wiki)\n\n---\n\n**Happy coding with CLI Agent! 🤖✨**\n"}, "72a97f68c4e28c249fc258185afa52b10e3bebfd": {"t": 1785764907.3883405, "n": 14717, "h": "42e6506e53c97a7f", "c": "# CLI Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, OpenRouter, and ollama with easy extensibility\n- **Hooks System**: Powerful workflow automation with security controls - audit commands, block dangerous operations, auto-format code, and integrate with external tools\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/cli-agent.git\n cd cli-agent\n ```\n\n2. **Install the package**:\n ```bash\n pip install -e .\n ```\n\n3. **Configure API keys** (environment variables):\n ```bash\n # Set environment variables for the providers you want to use\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Start with automatic provider selection\n agent chat\n \n # Or specify a particular provider-model combination\n agent chat --model openai:gpt-4-turbo-preview\n ```\n\n **Smart Provider Selection**: The agent automatically selects a configured provider based on available API keys.\n\n Configuration is automatically saved to `~/.config/cli-agent/config.json` and persists across sessions.\n\n **Migration from MCP Agent**: If you previously used MCP Agent, your configuration will be automatically migrated from `~/.config/mcp-agent/` to `~/.config/cli-agent/` on first run.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI (defaults to stdio)\nagent mcp serve\nagent mcp serve --stdio # explicit stdio\n\n# Start with TCP transport (useful for debugging)\npython mcp_server.py --tcp --port 3000 --host localhost\nagent mcp serve --tcp --port 3000 --host localhost\n```\n\nThe model server exposes AI models from 6 providers:\n- **Anthropic**: Claude models\n- **OpenAI**: GPT models\n- **DeepSeek**: Chat and reasoning models\n- **Gemini**: Google's Gemini models\n- **OpenRouter**: Multi-provider access\n- **Ollama**: Local models via Ollama server\n\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\nagent mcp add myserver:node:/path/to/server.js\nagent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\nagent mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\nagent mcp list\n```\n\n#### Remove a server\n\n```bash\nagent mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\nagent ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\nagent switch anthropic:claude-3.5-sonnet\nagent switch openai:gpt-4-turbo-preview\nagent switch deepseek:deepseek-chat\nagent switch gemini:gemini-2.5-flash\n\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/cli-agent/config.json`:\n\n- **API Keys**: Set via environment variables\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Subagent Configuration\nSUBAGENT_PERMISSIONS_BYPASS=false # bypass permission checks for subagents, defaults to false\n\n# Host Configuration (optional)\nHOST_NAME=cli-agent # defaults to 'cli-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n\n### AI Model Tools (via MCP Server)\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n- `/task` - Spawn a subagent for complex tasks\n\n## 📚 Examples\n\n\n### Example: Basic File Operations\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐\n│ CLI Interface │ \n│ (agent.py) │ \n└─────────┬───────┘ \n │ \n ▼ \n┌─────────────────────┐ ┌─────────────────────────────────────────┐\n│ MCPHost │◄───│ Provider + Model │\n│ (BaseLLMProvider) │ │ Composition │\n└─────────┬───────────┘ │ ┌─────────────────┐ ┌─────────────────┐ │\n │ │ │ BaseProvider │ │ ModelConfig │ │\n ▼ │ │ Subclasses: │ │ Subclasses: │ │\n┌─────────────────────┐ │ │ • Anthropic │ │ • ClaudeModel │ │\n│ BaseLLMProvider │ │ │ • OpenAI │ │ • GPTModel │ │\n│ (Centralized LLM │ │ │ • DeepSeek │ │ • GeminiModel │ │\n│ functionality) │ │ │ • Google │ │ • DeepSeekModel │ │\n└─────────┬───────────┘ │ │ • OpenRouter │ │ │ │\n │ │ └─────────────────┘ └─────────────────┘ │\n ▼ └─────────────────────────────────────────┘\n┌─────────────────────┐ │\n│ BaseMCPAgent │ ▼\n│ (Abstract base) │ ┌─────────────────┐\n└─────────┬───────────┘ │ Tool Converters │\n │ │ • OpenAI Format │\n┌─────────▼───────────┐ │ • Anthropic │\n│ Core Components: │ │ • Gemini │\n│ • SubagentCoordinator│ └─────────────────┘\n│ • BuiltinToolExecutor│ \n│ • ChatInterface │ ┌─────────────────┐\n│ • SlashCommands │◄───────────────│ Built-in Tools │\n│ • ToolExecutionEngine│ │ • File Ops │\n│ • TokenManager │ │ • Bash Execute │\n│ • SystemPromptBuilder│ │ • Web Fetch │\n│ • MessageProcessor │ │ • Todo Mgmt │\n└─────────┬───────────┘ │ • Task Spawn │\n │ │ • Glob/Grep │\n ▼ │ • MultiEdit │\n┌─────────────────────┐ └─────────────────┘\n│ External MCP Servers │ \n│ • AI Model Server │ ┌─────────────────┐\n│ • File System │ │ Subagent System │\n│ • APIs & Databases │ │ • Focused Tasks │\n│ • Custom Tools │ │ • Auto Cleanup │\n└─────────────────────┘ │ • Event-Driven │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables\n- **Configuration**: Automatically managed in user home directory (`~/.config/cli-agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n- **Subagent Permissions**: Can be configured to bypass permission checks for automated workflows via `SUBAGENT_PERMISSIONS_BYPASS=true`\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/cli-agent/issues)\n- 💬 [Discussions](https://github.com/amranu/cli-agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/cli-agent/wiki)\n\n---\n\n**Happy coding with CLI Agent! 🤖✨**\n"}, "0b5e377268982a4477c8cecf6af15a09e1dabe04": {"t": 1785764908.8031044, "n": 14502, "h": "5dd261300618c60e", "c": "# CLI Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, OpenRouter, and ollama with easy extensibility\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/cli-agent.git\n cd cli-agent\n ```\n\n2. **Install the package**:\n ```bash\n pip install -e .\n ```\n\n3. **Configure API keys** (environment variables):\n ```bash\n # Set environment variables for the providers you want to use\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Start with automatic provider selection\n agent chat\n \n # Or specify a particular provider-model combination\n agent chat --model openai:gpt-4-turbo-preview\n ```\n\n **Smart Provider Selection**: The agent automatically selects a configured provider based on available API keys.\n\n Configuration is automatically saved to `~/.config/cli-agent/config.json` and persists across sessions.\n\n **Migration from MCP Agent**: If you previously used MCP Agent, your configuration will be automatically migrated from `~/.config/mcp-agent/` to `~/.config/cli-agent/` on first run.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI (defaults to stdio)\nagent mcp serve\nagent mcp serve --stdio # explicit stdio\n\n# Start with TCP transport (useful for debugging)\npython mcp_server.py --tcp --port 3000 --host localhost\nagent mcp serve --tcp --port 3000 --host localhost\n```\n\nThe model server exposes AI models from 5 providers:\n- **Anthropic**: Claude models\n- **OpenAI**: GPT models\n- **DeepSeek**: Chat and reasoning models\n- **Gemini**: Google's Gemini models\n- **OpenRouter**: Multi-provider access\n\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\nagent mcp add myserver:node:/path/to/server.js\nagent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\nagent mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\nagent mcp list\n```\n\n#### Remove a server\n\n```bash\nagent mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\nagent ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\nagent switch anthropic:claude-3.5-sonnet\nagent switch openai:gpt-4-turbo-preview\nagent switch deepseek:deepseek-chat\nagent switch gemini:gemini-2.5-flash\n\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/cli-agent/config.json`:\n\n- **API Keys**: Set via environment variables\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Subagent Configuration\nSUBAGENT_PERMISSIONS_BYPASS=false # bypass permission checks for subagents, defaults to false\n\n# Host Configuration (optional)\nHOST_NAME=cli-agent # defaults to 'cli-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n\n### AI Model Tools (via MCP Server)\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n- `/task` - Spawn a subagent for complex tasks\n\n## 📚 Examples\n\n\n### Example: Basic File Operations\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐\n│ CLI Interface │ \n│ (agent.py) │ \n└─────────┬───────┘ \n │ \n ▼ \n┌─────────────────────┐ ┌─────────────────────────────────────────┐\n│ MCPHost │◄───│ Provider + Model │\n│ (BaseLLMProvider) │ │ Composition │\n└─────────┬───────────┘ │ ┌─────────────────┐ ┌─────────────────┐ │\n │ │ │ BaseProvider │ │ ModelConfig │ │\n ▼ │ │ Subclasses: │ │ Subclasses: │ │\n┌─────────────────────┐ │ │ • Anthropic │ │ • ClaudeModel │ │\n│ BaseLLMProvider │ │ │ • OpenAI │ │ • GPTModel │ │\n│ (Centralized LLM │ │ │ • DeepSeek │ │ • GeminiModel │ │\n│ functionality) │ │ │ • Google │ │ • DeepSeekModel │ │\n└─────────┬───────────┘ │ │ • OpenRouter │ │ │ │\n │ │ └─────────────────┘ └─────────────────┘ │\n ▼ └─────────────────────────────────────────┘\n┌─────────────────────┐ │\n│ BaseMCPAgent │ ▼\n│ (Abstract base) │ ┌─────────────────┐\n└─────────┬───────────┘ │ Tool Converters │\n │ │ • OpenAI Format │\n┌─────────▼───────────┐ │ • Anthropic │\n│ Core Components: │ │ • Gemini │\n│ • SubagentCoordinator│ └─────────────────┘\n│ • BuiltinToolExecutor│ \n│ • ChatInterface │ ┌─────────────────┐\n│ • SlashCommands │◄───────────────│ Built-in Tools │\n│ • ToolExecutionEngine│ │ • File Ops │\n│ • TokenManager │ │ • Bash Execute │\n│ • SystemPromptBuilder│ │ • Web Fetch │\n│ • MessageProcessor │ │ • Todo Mgmt │\n└─────────┬───────────┘ │ • Task Spawn │\n │ │ • Glob/Grep │\n ▼ │ • MultiEdit │\n┌─────────────────────┐ └─────────────────┘\n│ External MCP Servers │ \n│ • AI Model Server │ ┌─────────────────┐\n│ • File System │ │ Subagent System │\n│ • APIs & Databases │ │ • Focused Tasks │\n│ • Custom Tools │ │ • Auto Cleanup │\n└─────────────────────┘ │ • Event-Driven │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables\n- **Configuration**: Automatically managed in user home directory (`~/.config/cli-agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n- **Subagent Permissions**: Can be configured to bypass permission checks for automated workflows via `SUBAGENT_PERMISSIONS_BYPASS=true`\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/cli-agent/issues)\n- 💬 [Discussions](https://github.com/amranu/cli-agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/cli-agent/wiki)\n\n---\n\n**Happy coding with CLI Agent! 🤖✨**\n"}, "f179999902e2c5eac94bedaa23bdb861414791b9": {"t": 1785764910.8204615, "n": 14303, "h": "5ab7c8aa62e38a34", "c": "# MCP Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, OpenRouter, and ollama with easy extensibility\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/mcp-agent.git\n cd mcp-agent\n ```\n\n2. **Install the package**:\n ```bash\n pip install -e .\n ```\n\n3. **Configure API keys** (environment variables):\n ```bash\n # Set environment variables for the providers you want to use\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Start with automatic provider selection\n agent chat\n \n # Or specify a particular provider-model combination\n agent chat --model openai:gpt-4-turbo-preview\n ```\n\n **Smart Provider Selection**: The agent automatically selects a configured provider based on available API keys.\n\n Configuration is automatically saved to `~/.config/mcp-agent/config.json` and persists across sessions.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI (defaults to stdio)\nagent mcp serve\nagent mcp serve --stdio # explicit stdio\n\n# Start with TCP transport (useful for debugging)\npython mcp_server.py --tcp --port 3000 --host localhost\nagent mcp serve --tcp --port 3000 --host localhost\n```\n\nThe model server exposes AI models from 5 providers:\n- **Anthropic**: Claude models\n- **OpenAI**: GPT models\n- **DeepSeek**: Chat and reasoning models\n- **Gemini**: Google's Gemini models\n- **OpenRouter**: Multi-provider access\n\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\nagent mcp add myserver:node:/path/to/server.js\nagent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\nagent mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\nagent mcp list\n```\n\n#### Remove a server\n\n```bash\nagent mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\nagent ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\nagent switch anthropic:claude-3.5-sonnet\nagent switch openai:gpt-4-turbo-preview\nagent switch deepseek:deepseek-chat\nagent switch gemini:gemini-2.5-flash\n\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/mcp-agent/config.json`:\n\n- **API Keys**: Set via environment variables\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Subagent Configuration\nSUBAGENT_PERMISSIONS_BYPASS=false # bypass permission checks for subagents, defaults to false\n\n# Host Configuration (optional)\nHOST_NAME=mcp-agent # defaults to 'mcp-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n\n### AI Model Tools (via MCP Server)\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n- `/task` - Spawn a subagent for complex tasks\n\n## 📚 Examples\n\n\n### Example: Basic File Operations\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐\n│ CLI Interface │ \n│ (agent.py) │ \n└─────────┬───────┘ \n │ \n ▼ \n┌─────────────────────┐ ┌─────────────────────────────────────────┐\n│ MCPHost │◄───│ Provider + Model │\n│ (BaseLLMProvider) │ │ Composition │\n└─────────┬───────────┘ │ ┌─────────────────┐ ┌─────────────────┐ │\n │ │ │ BaseProvider │ │ ModelConfig │ │\n ▼ │ │ Subclasses: │ │ Subclasses: │ │\n┌─────────────────────┐ │ │ • Anthropic │ │ • ClaudeModel │ │\n│ BaseLLMProvider │ │ │ • OpenAI │ │ • GPTModel │ │\n│ (Centralized LLM │ │ │ • DeepSeek │ │ • GeminiModel │ │\n│ functionality) │ │ │ • Google │ │ • DeepSeekModel │ │\n└─────────┬───────────┘ │ │ • OpenRouter │ │ │ │\n │ │ └─────────────────┘ └─────────────────┘ │\n ▼ └─────────────────────────────────────────┘\n┌─────────────────────┐ │\n│ BaseMCPAgent │ ▼\n│ (Abstract base) │ ┌─────────────────┐\n└─────────┬───────────┘ │ Tool Converters │\n │ │ • OpenAI Format │\n┌─────────▼───────────┐ │ • Anthropic │\n│ Core Components: │ │ • Gemini │\n│ • SubagentCoordinator│ └─────────────────┘\n│ • BuiltinToolExecutor│ \n│ • ChatInterface │ ┌─────────────────┐\n│ • SlashCommands │◄───────────────│ Built-in Tools │\n│ • ToolExecutionEngine│ │ • File Ops │\n│ • TokenManager │ │ • Bash Execute │\n│ • SystemPromptBuilder│ │ • Web Fetch │\n│ • MessageProcessor │ │ • Todo Mgmt │\n└─────────┬───────────┘ │ • Task Spawn │\n │ │ • Glob/Grep │\n ▼ │ • MultiEdit │\n┌─────────────────────┐ └─────────────────┘\n│ External MCP Servers │ \n│ • AI Model Server │ ┌─────────────────┐\n│ • File System │ │ Subagent System │\n│ • APIs & Databases │ │ • Focused Tasks │\n│ • Custom Tools │ │ • Auto Cleanup │\n└─────────────────────┘ │ • Event-Driven │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables\n- **Configuration**: Automatically managed in user home directory (`~/.config/mcp-agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n- **Subagent Permissions**: Can be configured to bypass permission checks for automated workflows via `SUBAGENT_PERMISSIONS_BYPASS=true`\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/agent/issues)\n- 💬 [Discussions](https://github.com/amranu/agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/agent/wiki)\n\n---\n\n**Happy coding with MCP Agent! 🤖✨**\n"}, "746f5f9a02238e03cb27549c58f60ddf58c05e22": {"t": 1785764912.6101696, "n": 14295, "h": "5c3fe5c7819341dc", "c": "# MCP Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, and OpenRouter with easy extensibility\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/mcp-agent.git\n cd mcp-agent\n ```\n\n2. **Install the package**:\n ```bash\n pip install -e .\n ```\n\n3. **Configure API keys** (environment variables):\n ```bash\n # Set environment variables for the providers you want to use\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Start with automatic provider selection\n agent chat\n \n # Or specify a particular provider-model combination\n agent chat --model openai:gpt-4-turbo-preview\n ```\n\n **Smart Provider Selection**: The agent automatically selects a configured provider based on available API keys.\n\n Configuration is automatically saved to `~/.config/mcp-agent/config.json` and persists across sessions.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI (defaults to stdio)\nagent mcp serve\nagent mcp serve --stdio # explicit stdio\n\n# Start with TCP transport (useful for debugging)\npython mcp_server.py --tcp --port 3000 --host localhost\nagent mcp serve --tcp --port 3000 --host localhost\n```\n\nThe model server exposes AI models from 5 providers:\n- **Anthropic**: Claude models\n- **OpenAI**: GPT models\n- **DeepSeek**: Chat and reasoning models\n- **Gemini**: Google's Gemini models\n- **OpenRouter**: Multi-provider access\n\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\nagent mcp add myserver:node:/path/to/server.js\nagent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\nagent mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\nagent mcp list\n```\n\n#### Remove a server\n\n```bash\nagent mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\nagent ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\nagent switch anthropic:claude-3.5-sonnet\nagent switch openai:gpt-4-turbo-preview\nagent switch deepseek:deepseek-chat\nagent switch gemini:gemini-2.5-flash\n\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/mcp-agent/config.json`:\n\n- **API Keys**: Set via environment variables\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Subagent Configuration\nSUBAGENT_PERMISSIONS_BYPASS=false # bypass permission checks for subagents, defaults to false\n\n# Host Configuration (optional)\nHOST_NAME=mcp-agent # defaults to 'mcp-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n\n### AI Model Tools (via MCP Server)\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n- `/task` - Spawn a subagent for complex tasks\n\n## 📚 Examples\n\n\n### Example: Basic File Operations\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐\n│ CLI Interface │ \n│ (agent.py) │ \n└─────────┬───────┘ \n │ \n ▼ \n┌─────────────────────┐ ┌─────────────────────────────────────────┐\n│ MCPHost │◄───│ Provider + Model │\n│ (BaseLLMProvider) │ │ Composition │\n└─────────┬───────────┘ │ ┌─────────────────┐ ┌─────────────────┐ │\n │ │ │ BaseProvider │ │ ModelConfig │ │\n ▼ │ │ Subclasses: │ │ Subclasses: │ │\n┌─────────────────────┐ │ │ • Anthropic │ │ • ClaudeModel │ │\n│ BaseLLMProvider │ │ │ • OpenAI │ │ • GPTModel │ │\n│ (Centralized LLM │ │ │ • DeepSeek │ │ • GeminiModel │ │\n│ functionality) │ │ │ • Google │ │ • DeepSeekModel │ │\n└─────────┬───────────┘ │ │ • OpenRouter │ │ │ │\n │ │ └─────────────────┘ └─────────────────┘ │\n ▼ └─────────────────────────────────────────┘\n┌─────────────────────┐ │\n│ BaseMCPAgent │ ▼\n│ (Abstract base) │ ┌─────────────────┐\n└─────────┬───────────┘ │ Tool Converters │\n │ │ • OpenAI Format │\n┌─────────▼───────────┐ │ • Anthropic │\n│ Core Components: │ │ • Gemini │\n│ • SubagentCoordinator│ └─────────────────┘\n│ • BuiltinToolExecutor│ \n│ • ChatInterface │ ┌─────────────────┐\n│ • SlashCommands │◄───────────────│ Built-in Tools │\n│ • ToolExecutionEngine│ │ • File Ops │\n│ • TokenManager │ │ • Bash Execute │\n│ • SystemPromptBuilder│ │ • Web Fetch │\n│ • MessageProcessor │ │ • Todo Mgmt │\n└─────────┬───────────┘ │ • Task Spawn │\n │ │ • Glob/Grep │\n ▼ │ • MultiEdit │\n┌─────────────────────┐ └─────────────────┘\n│ External MCP Servers │ \n│ • AI Model Server │ ┌─────────────────┐\n│ • File System │ │ Subagent System │\n│ • APIs & Databases │ │ • Focused Tasks │\n│ • Custom Tools │ │ • Auto Cleanup │\n└─────────────────────┘ │ • Event-Driven │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables\n- **Configuration**: Automatically managed in user home directory (`~/.config/mcp-agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n- **Subagent Permissions**: Can be configured to bypass permission checks for automated workflows via `SUBAGENT_PERMISSIONS_BYPASS=true`\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/agent/issues)\n- 💬 [Discussions](https://github.com/amranu/agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/agent/wiki)\n\n---\n\n**Happy coding with MCP Agent! 🤖✨**\n"}, "c039256ed9c500acdbf8b54951888898933a8ea5": {"t": 1785764914.291823, "n": 14873, "h": "4db4f15e5910513e", "c": "# MCP Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, and OpenRouter with easy extensibility\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/mcp-agent.git\n cd mcp-agent\n ```\n\n2. **Install the package**:\n ```bash\n pip install -e .\n ```\n\n3. **Configure API keys** (environment variables):\n ```bash\n # Set environment variables for the providers you want to use\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Start with automatic provider selection\n agent chat\n \n # Or specify a particular provider-model combination\n agent chat --model openai:gpt-4-turbo-preview\n ```\n\n **Smart Provider Selection**: The agent automatically selects a configured provider based on available API keys.\n\n Configuration is automatically saved to `~/.config/mcp-agent/config.json` and persists across sessions.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI (defaults to stdio)\nagent mcp serve\nagent mcp serve --stdio # explicit stdio\n\n# Start with TCP transport (useful for debugging)\npython mcp_server.py --tcp --port 3000 --host localhost\nagent mcp serve --tcp --port 3000 --host localhost\n```\n\nThe model server exposes AI models from 5 providers:\n- **Anthropic**: Claude models\n- **OpenAI**: GPT models\n- **DeepSeek**: Chat and reasoning models\n- **Gemini**: Google's Gemini models\n- **OpenRouter**: Multi-provider access\n\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\nagent mcp add myserver:node:/path/to/server.js\nagent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\nagent mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\nagent mcp list\n```\n\n#### Remove a server\n\n```bash\nagent mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\nagent ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\nagent switch anthropic:claude-3.5-sonnet\nagent switch openai:gpt-4-turbo-preview\nagent switch deepseek:deepseek-chat\nagent switch gemini:gemini-2.5-flash\n\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/mcp-agent/config.json`:\n\n- **API Keys**: Set via environment variables\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Subagent Configuration\nSUBAGENT_PERMISSIONS_BYPASS=false # bypass permission checks for subagents, defaults to false\n\n# Host Configuration (optional)\nHOST_NAME=mcp-agent # defaults to 'mcp-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n### MCP Server Tools\n\nConnect external MCP servers to add functionality like:\n\n- **AI Model Access**: Multiple AI models from 5 providers via the built-in MCP model server\n- **API Integrations**: Connect to various web APIs\n- **File System**: Advanced file operations\n- **Database Connectors**: PostgreSQL, MySQL, SQLite\n- **Development Tools**: Git operations, code analysis\n- **Custom Services**: Your own MCP-compatible tools\n\n### AI Model Tools (via MCP Server)\n\nEach AI model is exposed as an MCP tool with persistent conversation support.\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n- **Complete Response Display**: No truncation of results\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n- `/task` - Spawn a subagent for complex tasks\n\n## 📚 Examples\n\n\n### Example: Basic File Operations\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐\n│ CLI Interface │ \n│ (agent.py) │ \n└─────────┬───────┘ \n │ \n ▼ \n┌─────────────────────┐ ┌─────────────────────────────────────────┐\n│ MCPHost │◄───│ Provider + Model │\n│ (BaseLLMProvider) │ │ Composition │\n└─────────┬───────────┘ │ ┌─────────────────┐ ┌─────────────────┐ │\n │ │ │ BaseProvider │ │ ModelConfig │ │\n ▼ │ │ Subclasses: │ │ Subclasses: │ │\n┌─────────────────────┐ │ │ • Anthropic │ │ • ClaudeModel │ │\n│ BaseLLMProvider │ │ │ • OpenAI │ │ • GPTModel │ │\n│ (Centralized LLM │ │ │ • DeepSeek │ │ • GeminiModel │ │\n│ functionality) │ │ │ • Google │ │ • DeepSeekModel │ │\n└─────────┬───────────┘ │ │ • OpenRouter │ │ │ │\n │ │ └─────────────────┘ └─────────────────┘ │\n ▼ └─────────────────────────────────────────┘\n┌─────────────────────┐ │\n│ BaseMCPAgent │ ▼\n│ (Abstract base) │ ┌─────────────────┐\n└─────────┬───────────┘ │ Tool Converters │\n │ │ • OpenAI Format │\n┌─────────▼───────────┐ │ • Anthropic │\n│ Core Components: │ │ • Gemini │\n│ • SubagentCoordinator│ └─────────────────┘\n│ • BuiltinToolExecutor│ \n│ • ChatInterface │ ┌─────────────────┐\n│ • SlashCommands │◄───────────────│ Built-in Tools │\n│ • ToolExecutionEngine│ │ • File Ops │\n│ • TokenManager │ │ • Bash Execute │\n│ • SystemPromptBuilder│ │ • Web Fetch │\n│ • MessageProcessor │ │ • Todo Mgmt │\n└─────────┬───────────┘ │ • Task Spawn │\n │ │ • Glob/Grep │\n ▼ │ • MultiEdit │\n┌─────────────────────┐ └─────────────────┘\n│ External MCP Servers │ \n│ • AI Model Server │ ┌─────────────────┐\n│ • File System │ │ Subagent System │\n│ • APIs & Databases │ │ • Focused Tasks │\n│ • Custom Tools │ │ • Auto Cleanup │\n└─────────────────────┘ │ • Event-Driven │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables\n- **Configuration**: Automatically managed in user home directory (`~/.config/mcp-agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n- **Subagent Permissions**: Can be configured to bypass permission checks for automated workflows via `SUBAGENT_PERMISSIONS_BYPASS=true`\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/agent/issues)\n- 💬 [Discussions](https://github.com/amranu/agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/agent/wiki)\n\n---\n\n**Happy coding with MCP Agent! 🤖✨**\n"}, "e0f99107bc2ca967be4e39dcf7e6bf6ae9d73ddc": {"t": 1785764916.0961509, "n": 14865, "h": "0e42ff21224fb38c", "c": "# MCP Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, and OpenRouter with easy extensibility\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/agent.git\n cd agent\n ```\n\n2. **Install the package**:\n ```bash\n pip install -e .\n ```\n\n3. **Configure API keys** (environment variables):\n ```bash\n # Set environment variables for the providers you want to use\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Start with automatic provider selection\n agent chat\n \n # Or specify a particular provider-model combination\n agent chat --model openai:gpt-4-turbo-preview\n ```\n\n **Smart Provider Selection**: The agent automatically selects a configured provider based on available API keys.\n\n Configuration is automatically saved to `~/.config/mcp-agent/config.json` and persists across sessions.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI (defaults to stdio)\nagent mcp serve\nagent mcp serve --stdio # explicit stdio\n\n# Start with TCP transport (useful for debugging)\npython mcp_server.py --tcp --port 3000 --host localhost\nagent mcp serve --tcp --port 3000 --host localhost\n```\n\nThe model server exposes AI models from 5 providers:\n- **Anthropic**: Claude models\n- **OpenAI**: GPT models\n- **DeepSeek**: Chat and reasoning models\n- **Gemini**: Google's Gemini models\n- **OpenRouter**: Multi-provider access\n\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\nagent mcp add myserver:node:/path/to/server.js\nagent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\nagent mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\nagent mcp list\n```\n\n#### Remove a server\n\n```bash\nagent mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\nagent ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\nagent switch anthropic:claude-3.5-sonnet\nagent switch openai:gpt-4-turbo-preview\nagent switch deepseek:deepseek-chat\nagent switch gemini:gemini-2.5-flash\n\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/mcp-agent/config.json`:\n\n- **API Keys**: Set via environment variables\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Subagent Configuration\nSUBAGENT_PERMISSIONS_BYPASS=false # bypass permission checks for subagents, defaults to false\n\n# Host Configuration (optional)\nHOST_NAME=mcp-agent # defaults to 'mcp-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n### MCP Server Tools\n\nConnect external MCP servers to add functionality like:\n\n- **AI Model Access**: Multiple AI models from 5 providers via the built-in MCP model server\n- **API Integrations**: Connect to various web APIs\n- **File System**: Advanced file operations\n- **Database Connectors**: PostgreSQL, MySQL, SQLite\n- **Development Tools**: Git operations, code analysis\n- **Custom Services**: Your own MCP-compatible tools\n\n### AI Model Tools (via MCP Server)\n\nEach AI model is exposed as an MCP tool with persistent conversation support.\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n- **Complete Response Display**: No truncation of results\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n- `/task` - Spawn a subagent for complex tasks\n\n## 📚 Examples\n\n\n### Example: Basic File Operations\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐\n│ CLI Interface │ \n│ (agent.py) │ \n└─────────┬───────┘ \n │ \n ▼ \n┌─────────────────────┐ ┌─────────────────────────────────────────┐\n│ MCPHost │◄───│ Provider + Model │\n│ (BaseLLMProvider) │ │ Composition │\n└─────────┬───────────┘ │ ┌─────────────────┐ ┌─────────────────┐ │\n │ │ │ BaseProvider │ │ ModelConfig │ │\n ▼ │ │ Subclasses: │ │ Subclasses: │ │\n┌─────────────────────┐ │ │ • Anthropic │ │ • ClaudeModel │ │\n│ BaseLLMProvider │ │ │ • OpenAI │ │ • GPTModel │ │\n│ (Centralized LLM │ │ │ • DeepSeek │ │ • GeminiModel │ │\n│ functionality) │ │ │ • Google │ │ • DeepSeekModel │ │\n└─────────┬───────────┘ │ │ • OpenRouter │ │ │ │\n │ │ └─────────────────┘ └─────────────────┘ │\n ▼ └─────────────────────────────────────────┘\n┌─────────────────────┐ │\n│ BaseMCPAgent │ ▼\n│ (Abstract base) │ ┌─────────────────┐\n└─────────┬───────────┘ │ Tool Converters │\n │ │ • OpenAI Format │\n┌─────────▼───────────┐ │ • Anthropic │\n│ Core Components: │ │ • Gemini │\n│ • SubagentCoordinator│ └─────────────────┘\n│ • BuiltinToolExecutor│ \n│ • ChatInterface │ ┌─────────────────┐\n│ • SlashCommands │◄───────────────│ Built-in Tools │\n│ • ToolExecutionEngine│ │ • File Ops │\n│ • TokenManager │ │ • Bash Execute │\n│ • SystemPromptBuilder│ │ • Web Fetch │\n│ • MessageProcessor │ │ • Todo Mgmt │\n└─────────┬───────────┘ │ • Task Spawn │\n │ │ • Glob/Grep │\n ▼ │ • MultiEdit │\n┌─────────────────────┐ └─────────────────┘\n│ External MCP Servers │ \n│ • AI Model Server │ ┌─────────────────┐\n│ • File System │ │ Subagent System │\n│ • APIs & Databases │ │ • Focused Tasks │\n│ • Custom Tools │ │ • Auto Cleanup │\n└─────────────────────┘ │ • Event-Driven │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables\n- **Configuration**: Automatically managed in user home directory (`~/.config/mcp-agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n- **Subagent Permissions**: Can be configured to bypass permission checks for automated workflows via `SUBAGENT_PERMISSIONS_BYPASS=true`\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/agent/issues)\n- 💬 [Discussions](https://github.com/amranu/agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/agent/wiki)\n\n---\n\n**Happy coding with MCP Agent! 🤖✨**\n"}, "a96d4be70fffb46d1ac237b68a89dfd376bacdd3": {"t": 1785764917.8646562, "n": 14515, "h": "804bc48f83914e37", "c": "# MCP Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, and OpenRouter with easy extensibility\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/agent.git\n cd agent\n ```\n\n2. **Install the package**:\n ```bash\n pip install -e .\n ```\n\n3. **Configure API keys** (environment variables):\n ```bash\n # Set environment variables (required for the providers you want to use)\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Example usage\n agent chat --model deepseek:deepseek-chat\n ```\n\n Configuration is automatically saved to `~/.config/agent/config.json` and persists across sessions.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI\nagent mcp serve\n\n# Start with TCP transport (useful for debugging)\nagent mcp serve --port 3000 --host localhost\n```\n\nThe model server exposes AI models from 5 providers:\n- **Anthropic**: Claude models\n- **OpenAI**: GPT models\n- **DeepSeek**: Chat and reasoning models\n- **Gemini**: Google's Gemini models\n- **OpenRouter**: Multi-provider access\n\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\nagent mcp add myserver:node:/path/to/server.js\nagent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\nagent mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\nagent mcp list\n```\n\n#### Remove a server\n\n```bash\nagent mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\nagent ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\nagent switch anthropic:claude-3.5-sonnet\nagent switch openai:gpt-4-turbo-preview\nagent switch deepseek:deepseek-chat\nagent switch gemini:gemini-2.5-flash\n\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/agent/config.json`:\n\n- **API Keys**: Set via environment variables\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Subagent Configuration\nSUBAGENT_PERMISSIONS_BYPASS=false # bypass permission checks for subagents, defaults to false\n\n# Host Configuration (optional)\nHOST_NAME=mcp-agent # defaults to 'mcp-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n### MCP Server Tools\n\nConnect external MCP servers to add functionality like:\n\n- **AI Model Access**: Multiple AI models from 5 providers via the built-in MCP model server\n- **API Integrations**: Connect to various web APIs\n- **File System**: Advanced file operations\n- **Database Connectors**: PostgreSQL, MySQL, SQLite\n- **Development Tools**: Git operations, code analysis\n- **Custom Services**: Your own MCP-compatible tools\n\n### AI Model Tools (via MCP Server)\n\nEach AI model is exposed as an MCP tool with persistent conversation support.\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n- **Complete Response Display**: No truncation of results\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n- `/task` - Spawn a subagent for complex tasks\n\n## 📚 Examples\n\n\n### Example: Basic File Operations\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐\n│ CLI Interface │ \n│ (agent.py) │ \n└─────────┬───────┘ \n │ \n ▼ \n┌─────────────────────┐ ┌─────────────────────────────────────────┐\n│ MCPHost │◄───│ Provider + Model │\n│ (BaseLLMProvider) │ │ Composition │\n└─────────┬───────────┘ │ ┌─────────────────┐ ┌─────────────────┐ │\n │ │ │ BaseProvider │ │ ModelConfig │ │\n ▼ │ │ Subclasses: │ │ Subclasses: │ │\n┌─────────────────────┐ │ │ • Anthropic │ │ • ClaudeModel │ │\n│ BaseLLMProvider │ │ │ • OpenAI │ │ • GPTModel │ │\n│ (Centralized LLM │ │ │ • DeepSeek │ │ • GeminiModel │ │\n│ functionality) │ │ │ • Google │ │ • DeepSeekModel │ │\n└─────────┬───────────┘ │ │ • OpenRouter │ │ │ │\n │ │ └─────────────────┘ └─────────────────┘ │\n ▼ └─────────────────────────────────────────┘\n┌─────────────────────┐ │\n│ BaseMCPAgent │ ▼\n│ (Abstract base) │ ┌─────────────────┐\n└─────────┬───────────┘ │ Tool Converters │\n │ │ • OpenAI Format │\n┌─────────▼───────────┐ │ • Anthropic │\n│ Core Components: │ │ • Gemini │\n│ • SubagentCoordinator│ └─────────────────┘\n│ • BuiltinToolExecutor│ \n│ • ChatInterface │ ┌─────────────────┐\n│ • SlashCommands │◄───────────────│ Built-in Tools │\n│ • ToolExecutionEngine│ │ • File Ops │\n│ • TokenManager │ │ • Bash Execute │\n│ • SystemPromptBuilder│ │ • Web Fetch │\n│ • MessageProcessor │ │ • Todo Mgmt │\n└─────────┬───────────┘ │ • Task Spawn │\n │ │ • Glob/Grep │\n ▼ │ • MultiEdit │\n┌─────────────────────┐ └─────────────────┘\n│ External MCP Servers │ \n│ • AI Model Server │ ┌─────────────────┐\n│ • File System │ │ Subagent System │\n│ • APIs & Databases │ │ • Focused Tasks │\n│ • Custom Tools │ │ • Auto Cleanup │\n└─────────────────────┘ │ • Event-Driven │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables\n- **Configuration**: Automatically managed in user home directory (`~/.config/agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n- **Subagent Permissions**: Can be configured to bypass permission checks for automated workflows via `SUBAGENT_PERMISSIONS_BYPASS=true`\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/agent/issues)\n- 💬 [Discussions](https://github.com/amranu/agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/agent/wiki)\n\n---\n\n**Happy coding with MCP Agent! 🤖✨**\n"}, "4a52f811c20d25cc1a7a588dc6cc9d27dd92a80e": {"t": 1785764920.1702178, "n": 14244, "h": "c7e43b97f0f29ae4", "c": "# MCP Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, and OpenRouter with easy extensibility\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/agent.git\n cd agent\n ```\n\n2. **Install the package**:\n ```bash\n pip install -e .\n ```\n\n3. **Configure API keys** (environment variables):\n ```bash\n # Set environment variables (required for the providers you want to use)\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Example usage\n agent chat --model deepseek:deepseek-chat\n ```\n\n Configuration is automatically saved to `~/.config/agent/config.json` and persists across sessions.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI\nagent mcp serve\n\n# Start with TCP transport (useful for debugging)\nagent mcp serve --port 3000 --host localhost\n```\n\nThe model server exposes AI models from 5 providers:\n- **Anthropic**: Claude models\n- **OpenAI**: GPT models\n- **DeepSeek**: Chat and reasoning models\n- **Gemini**: Google's Gemini models\n- **OpenRouter**: Multi-provider access\n\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\nagent mcp add myserver:node:/path/to/server.js\nagent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\nagent mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\nagent mcp list\n```\n\n#### Remove a server\n\n```bash\nagent mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\nagent ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\nagent switch anthropic:claude-3.5-sonnet\nagent switch openai:gpt-4-turbo-preview\nagent switch deepseek:deepseek-chat\nagent switch gemini:gemini-2.5-flash\n\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/agent/config.json`:\n\n- **API Keys**: Set via environment variables\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Host Configuration (optional)\nHOST_NAME=mcp-agent # defaults to 'mcp-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n### MCP Server Tools\n\nConnect external MCP servers to add functionality like:\n\n- **AI Model Access**: Multiple AI models from 5 providers via the built-in MCP model server\n- **API Integrations**: Connect to various web APIs\n- **File System**: Advanced file operations\n- **Database Connectors**: PostgreSQL, MySQL, SQLite\n- **Development Tools**: Git operations, code analysis\n- **Custom Services**: Your own MCP-compatible tools\n\n### AI Model Tools (via MCP Server)\n\nEach AI model is exposed as an MCP tool with persistent conversation support.\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n- **Complete Response Display**: No truncation of results\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n- `/task` - Spawn a subagent for complex tasks\n\n## 📚 Examples\n\n\n### Example: Basic File Operations\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐\n│ CLI Interface │ \n│ (agent.py) │ \n└─────────┬───────┘ \n │ \n ▼ \n┌─────────────────────┐ ┌─────────────────────────────────────────┐\n│ MCPHost │◄───│ Provider + Model │\n│ (BaseLLMProvider) │ │ Composition │\n└─────────┬───────────┘ │ ┌─────────────────┐ ┌─────────────────┐ │\n │ │ │ BaseProvider │ │ ModelConfig │ │\n ▼ │ │ Subclasses: │ │ Subclasses: │ │\n┌─────────────────────┐ │ │ • Anthropic │ │ • ClaudeModel │ │\n│ BaseLLMProvider │ │ │ • OpenAI │ │ • GPTModel │ │\n│ (Centralized LLM │ │ │ • DeepSeek │ │ • GeminiModel │ │\n│ functionality) │ │ │ • Google │ │ • DeepSeekModel │ │\n└─────────┬───────────┘ │ │ • OpenRouter │ │ │ │\n │ │ └─────────────────┘ └─────────────────┘ │\n ▼ └─────────────────────────────────────────┘\n┌─────────────────────┐ │\n│ BaseMCPAgent │ ▼\n│ (Abstract base) │ ┌─────────────────┐\n└─────────┬───────────┘ │ Tool Converters │\n │ │ • OpenAI Format │\n┌─────────▼───────────┐ │ • Anthropic │\n│ Core Components: │ │ • Gemini │\n│ • SubagentCoordinator│ └─────────────────┘\n│ • BuiltinToolExecutor│ \n│ • ChatInterface │ ┌─────────────────┐\n│ • SlashCommands │◄───────────────│ Built-in Tools │\n│ • ToolExecutionEngine│ │ • File Ops │\n│ • TokenManager │ │ • Bash Execute │\n│ • SystemPromptBuilder│ │ • Web Fetch │\n│ • MessageProcessor │ │ • Todo Mgmt │\n└─────────┬───────────┘ │ • Task Spawn │\n │ │ • Glob/Grep │\n ▼ │ • MultiEdit │\n┌─────────────────────┐ └─────────────────┘\n│ External MCP Servers │ \n│ • AI Model Server │ ┌─────────────────┐\n│ • File System │ │ Subagent System │\n│ • APIs & Databases │ │ • Focused Tasks │\n│ • Custom Tools │ │ • Auto Cleanup │\n└─────────────────────┘ │ • Event-Driven │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables\n- **Configuration**: Automatically managed in user home directory (`~/.config/agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/agent/issues)\n- 💬 [Discussions](https://github.com/amranu/agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/agent/wiki)\n\n---\n\n**Happy coding with MCP Agent! 🤖✨**\n"}, "e3fd15e72b37c6e8c399e7130ca72fa2fbebb4c2": {"t": 1785764921.6999671, "n": 14719, "h": "4207c031443825b4", "c": "# MCP Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, and OpenRouter with easy extensibility\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/agent.git\n cd agent\n ```\n\n2. **Install the package**:\n ```bash\n pip install -e .\n ```\n\n3. **Configure API keys** (environment variables):\n ```bash\n # Set environment variables (required for the providers you want to use)\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Example usage\n agent chat --model deepseek:deepseek-chat\n ```\n\n Configuration is automatically saved to `~/.config/agent/config.json` and persists across sessions.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI\nagent mcp serve\n\n# Start with TCP transport (useful for debugging)\nagent mcp serve --port 3000 --host localhost\n```\n\nThe model server exposes AI models from 5 providers:\n- **Anthropic**: Claude models\n- **OpenAI**: GPT models\n- **DeepSeek**: Chat and reasoning models\n- **Gemini**: Google's Gemini models\n- **OpenRouter**: Multi-provider access\n\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\nagent mcp add myserver:node:/path/to/server.js\nagent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\nagent mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\nagent mcp list\n```\n\n#### Remove a server\n\n```bash\nagent mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\nagent ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\nagent switch anthropic:claude-3.5-sonnet\nagent switch openai:gpt-4-turbo-preview\nagent switch deepseek:deepseek-chat\nagent switch gemini:gemini-2.5-flash\n\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/agent/config.json`:\n\n- **API Keys**: Set via environment variables\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Host Configuration (optional)\nHOST_NAME=mcp-agent # defaults to 'mcp-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n### MCP Server Tools\n\nConnect external MCP servers to add functionality like:\n\n- **AI Model Access**: Multiple AI models from 5 providers via the built-in MCP model server\n- **API Integrations**: Connect to various web APIs\n- **File System**: Advanced file operations\n- **Database Connectors**: PostgreSQL, MySQL, SQLite\n- **Development Tools**: Git operations, code analysis\n- **Custom Services**: Your own MCP-compatible tools\n\n### AI Model Tools (via MCP Server)\n\nEach AI model is exposed as an MCP tool with persistent conversation support:\n\n- **anthropic_claude_3_5_sonnet**: Anthropic's flagship model for complex reasoning\n- **openai_gpt_4_turbo_preview**: OpenAI's most capable model\n- **deepseek_deepseek_chat**: DeepSeek's standard chat model\n- **deepseek_deepseek_reasoner**: DeepSeek's reasoning-focused model\n- **gemini_gemini_2_5_flash**: Google's fast, efficient model\n- **gemini_gemini_2_5_pro**: Google's most capable model\n- And 5 more models across all providers\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n- **Complete Response Display**: No truncation of results\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n- `/task` - Spawn a subagent for complex tasks\n\n## 📚 Examples\n\n\n### Example: Basic File Operations\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐\n│ CLI Interface │ \n│ (agent.py) │ \n└─────────┬───────┘ \n │ \n ▼ \n┌─────────────────────┐ ┌─────────────────────────────────────────┐\n│ MCPHost │◄───│ Provider + Model │\n│ (BaseLLMProvider) │ │ Composition │\n└─────────┬───────────┘ │ ┌─────────────────┐ ┌─────────────────┐ │\n │ │ │ BaseProvider │ │ ModelConfig │ │\n ▼ │ │ Subclasses: │ │ Subclasses: │ │\n┌─────────────────────┐ │ │ • Anthropic │ │ • ClaudeModel │ │\n│ BaseLLMProvider │ │ │ • OpenAI │ │ • GPTModel │ │\n│ (Centralized LLM │ │ │ • DeepSeek │ │ • GeminiModel │ │\n│ functionality) │ │ │ • Google │ │ • DeepSeekModel │ │\n└─────────┬───────────┘ │ │ • OpenRouter │ │ │ │\n │ │ └─────────────────┘ └─────────────────┘ │\n ▼ └─────────────────────────────────────────┘\n┌─────────────────────┐ │\n│ BaseMCPAgent │ ▼\n│ (Abstract base) │ ┌─────────────────┐\n└─────────┬───────────┘ │ Tool Converters │\n │ │ • OpenAI Format │\n┌─────────▼───────────┐ │ • Anthropic │\n│ Core Components: │ │ • Gemini │\n│ • SubagentCoordinator│ └─────────────────┘\n│ • BuiltinToolExecutor│ \n│ • ChatInterface │ ┌─────────────────┐\n│ • SlashCommands │◄───────────────│ Built-in Tools │\n│ • ToolExecutionEngine│ │ • File Ops │\n│ • TokenManager │ │ • Bash Execute │\n│ • SystemPromptBuilder│ │ • Web Fetch │\n│ • MessageProcessor │ │ • Todo Mgmt │\n└─────────┬───────────┘ │ • Task Spawn │\n │ │ • Glob/Grep │\n ▼ │ • MultiEdit │\n┌─────────────────────┐ └─────────────────┘\n│ External MCP Servers │ \n│ • AI Model Server │ ┌─────────────────┐\n│ • File System │ │ Subagent System │\n│ • APIs & Databases │ │ • Focused Tasks │\n│ • Custom Tools │ │ • Auto Cleanup │\n└─────────────────────┘ │ • Event-Driven │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables, never committed to git\n- **Configuration**: Automatically managed in user home directory (`~/.config/agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/agent/issues)\n- 💬 [Discussions](https://github.com/amranu/agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/agent/wiki)\n\n---\n\n**Happy coding with MCP Agent! 🤖✨**\n"}, "371efd8a95688fadafc7b3edc8fd13ec88eb5641": {"t": 1785764923.1725454, "n": 14846, "h": "b260feaa8957c2fa", "c": "# MCP Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, and OpenRouter with easy extensibility\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/agent.git\n cd agent\n ```\n\n2. **Install the package**:\n ```bash\n pip install -e .\n ```\n\n3. **Configure API keys** (environment variables):\n ```bash\n # Set environment variables (required for the providers you want to use)\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Example usage\n agent chat --model deepseek:deepseek-chat\n ```\n\n Configuration is automatically saved to `~/.config/agent/config.json` and persists across sessions.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI\nagent mcp serve\n\n# Start with TCP transport (useful for debugging)\nagent mcp serve --port 3000 --host localhost\n```\n\nThe model server exposes AI models from 5 providers:\n- **Anthropic**: Claude models\n- **OpenAI**: GPT models\n- **DeepSeek**: Chat and reasoning models\n- **Gemini**: Google's Gemini models\n- **OpenRouter**: Multi-provider access\n\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\nagent mcp add myserver:node:/path/to/server.js\nagent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\nagent mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\nagent mcp list\n```\n\n#### Remove a server\n\n```bash\nagent mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\nagent ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\nagent switch anthropic:claude-3.5-sonnet\nagent switch openai:gpt-4-turbo-preview\nagent switch deepseek:deepseek-chat\nagent switch gemini:gemini-2.5-flash\n\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/agent/config.json`:\n\n- **API Keys**: Set via environment variables\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Host Configuration (optional)\nHOST_NAME=mcp-agent # defaults to 'mcp-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n### MCP Server Tools\n\nConnect external MCP servers to add functionality like:\n\n- **AI Model Access**: Multiple AI models from 5 providers via the built-in MCP model server\n- **API Integrations**: Connect to various web APIs\n- **File System**: Advanced file operations\n- **Database Connectors**: PostgreSQL, MySQL, SQLite\n- **Development Tools**: Git operations, code analysis\n- **Custom Services**: Your own MCP-compatible tools\n\n### AI Model Tools (via MCP Server)\n\nEach AI model is exposed as an MCP tool with persistent conversation support:\n\n- **anthropic_claude_3_5_sonnet**: Anthropic's flagship model for complex reasoning\n- **openai_gpt_4_turbo_preview**: OpenAI's most capable model\n- **deepseek_deepseek_chat**: DeepSeek's standard chat model\n- **deepseek_deepseek_reasoner**: DeepSeek's reasoning-focused model\n- **gemini_gemini_2_5_flash**: Google's fast, efficient model\n- **gemini_gemini_2_5_pro**: Google's most capable model\n- And 5 more models across all providers\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n- **Complete Response Display**: No truncation of results\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n- `/task` - Spawn a subagent for complex tasks\n- `/task-status` - Check status of running subagents\n\n## 📚 Examples\n\n\n### Example: Basic File Operations\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\nYou: /task-status\n [Shows: \"1 subagent running: log-analysis-task\"]\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐\n│ CLI Interface │ \n│ (agent.py) │ \n└─────────┬───────┘ \n │ \n ▼ \n┌─────────────────────┐ ┌─────────────────────────────────────────┐\n│ MCPHost │◄───│ Provider + Model │\n│ (BaseLLMProvider) │ │ Composition │\n└─────────┬───────────┘ │ ┌─────────────────┐ ┌─────────────────┐ │\n │ │ │ BaseProvider │ │ ModelConfig │ │\n ▼ │ │ Subclasses: │ │ Subclasses: │ │\n┌─────────────────────┐ │ │ • Anthropic │ │ • ClaudeModel │ │\n│ BaseLLMProvider │ │ │ • OpenAI │ │ • GPTModel │ │\n│ (Centralized LLM │ │ │ • DeepSeek │ │ • GeminiModel │ │\n│ functionality) │ │ │ • Google │ │ • DeepSeekModel │ │\n└─────────┬───────────┘ │ │ • OpenRouter │ │ │ │\n │ │ └─────────────────┘ └─────────────────┘ │\n ▼ └─────────────────────────────────────────┘\n┌─────────────────────┐ │\n│ BaseMCPAgent │ ▼\n│ (Abstract base) │ ┌─────────────────┐\n└─────────┬───────────┘ │ Tool Converters │\n │ │ • OpenAI Format │\n┌─────────▼───────────┐ │ • Anthropic │\n│ Core Components: │ │ • Gemini │\n│ • SubagentCoordinator│ └─────────────────┘\n│ • BuiltinToolExecutor│ \n│ • ChatInterface │ ┌─────────────────┐\n│ • SlashCommands │◄───────────────│ Built-in Tools │\n│ • ToolExecutionEngine│ │ • File Ops │\n│ • TokenManager │ │ • Bash Execute │\n│ • SystemPromptBuilder│ │ • Web Fetch │\n│ • MessageProcessor │ │ • Todo Mgmt │\n└─────────┬───────────┘ │ • Task Spawn │\n │ │ • Glob/Grep │\n ▼ │ • MultiEdit │\n┌─────────────────────┐ └─────────────────┘\n│ External MCP Servers │ \n│ • AI Model Server │ ┌─────────────────┐\n│ • File System │ │ Subagent System │\n│ • APIs & Databases │ │ • Focused Tasks │\n│ • Custom Tools │ │ • Auto Cleanup │\n└─────────────────────┘ │ • Event-Driven │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables, never committed to git\n- **Configuration**: Automatically managed in user home directory (`~/.config/agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/agent/issues)\n- 💬 [Discussions](https://github.com/amranu/agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/agent/wiki)\n\n---\n\n**Happy coding with MCP Agent! 🤖✨**\n"}, "7e0aa7edf3b3d828212064568d2b454f4edc3d98": {"t": 1785764924.9827955, "n": 14729, "h": "807e8979af5227c7", "c": "# MCP Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, and OpenRouter with easy extensibility\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/agent.git\n cd agent\n ```\n\n2. **Install the package**:\n ```bash\n pip install -e .\n ```\n\n3. **Configure API keys** (environment variables):\n ```bash\n # Set environment variables (required for the providers you want to use)\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Example usage\n agent chat --model deepseek:deepseek-chat\n ```\n\n Configuration is automatically saved to `~/.config/agent/config.json` and persists across sessions.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI\nagent mcp serve\n\n# Start with TCP transport (useful for debugging)\nagent mcp serve --port 3000 --host localhost\n```\n\nThe model server exposes AI models from 5 providers:\n- **Anthropic**: Claude models\n- **OpenAI**: GPT models\n- **DeepSeek**: Chat and reasoning models\n- **Gemini**: Google's Gemini models\n- **OpenRouter**: Multi-provider access\n\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\nagent mcp add myserver:node:/path/to/server.js\nagent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\nagent mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\nagent mcp list\n```\n\n#### Remove a server\n\n```bash\nagent mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\nagent ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\nagent switch anthropic:claude-3.5-sonnet\nagent switch openai:gpt-4-turbo-preview\nagent switch deepseek:deepseek-chat\nagent switch gemini:gemini-2.5-flash\n\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/agent/config.json`:\n\n- **API Keys**: Set via environment variables\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Host Configuration (optional)\nHOST_NAME=mcp-agent # defaults to 'mcp-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n### MCP Server Tools\n\nConnect external MCP servers to add functionality like:\n\n- **AI Model Access**: Multiple AI models from 5 providers via the built-in MCP model server\n- **API Integrations**: Connect to various web APIs\n- **File System**: Advanced file operations\n- **Database Connectors**: PostgreSQL, MySQL, SQLite\n- **Development Tools**: Git operations, code analysis\n- **Custom Services**: Your own MCP-compatible tools\n\n### AI Model Tools (via MCP Server)\n\nEach AI model is exposed as an MCP tool with persistent conversation support:\n\n- **anthropic_claude_3_5_sonnet**: Anthropic's flagship model for complex reasoning\n- **openai_gpt_4_turbo_preview**: OpenAI's most capable model\n- **deepseek_deepseek_chat**: DeepSeek's standard chat model\n- **deepseek_deepseek_reasoner**: DeepSeek's reasoning-focused model\n- **gemini_gemini_2_5_flash**: Google's fast, efficient model\n- **gemini_gemini_2_5_pro**: Google's most capable model\n- And 5 more models across all providers\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n- **Complete Response Display**: No truncation of results\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n- `/task` - Spawn a subagent for complex tasks\n- `/task-status` - Check status of running subagents\n\n## 📚 Examples\n\n\n### Example: Basic File Operations\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\nYou: /task-status\n [Shows: \"1 subagent running: log-analysis-task\"]\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐ ┌──────────────────────┐ ┌─────────────────────┐\n│ CLI Interface │────│ BaseMCPAgent │────│ Provider-Model │\n│ │ │ (Centralized) │ │ Architecture │\n└─────────────────┘ └──────────────────────┘ │ ┌─────────────────┐ │\n │ │ │ MCPHost │ │\n ┌─────────────────┐ │ │ (Provider + │ │\n │ MCP Model Server│ │ │ Model) │ │\n │ │ │ └─────────────────┘ │\n │ ┌─────────────┐ │ │ ┌─────────────────┐ │\n │ │11 AI Models │ │ │ │ AnthropicProvider│ │\n │ │Conversations│ │ │ │ OpenAIProvider │ │\n │ │FastMCP Proto│ │ │ │ DeepSeekProvider│ │\n │ └─────────────┘ │ │ │ GoogleProvider │ │\n └─────────────────┘ │ │ OpenRouterProvider│ │\n │ │ └─────────────────┘ │\n ┌─────────────────┐ └─────────────────────┘\n │ Subagent Mgr │ │\n │ │ ┌─────────────────┐\n │ ┌─────────────┐ │ │ MCP Servers │\n │ │Focused Tasks│ │ │ │\n │ │Auto Cleanup │ │ │ ┌─────────────┐ │\n │ │Parallel Exec│ │ │ │ AI Models │ │\n │ └─────────────┘ │ │ │ File System │ │\n └─────────────────┘ │ │ APIs │ │\n │ │ │ Database │ │\n ┌─────────────────┐ │ │ Custom Tools│ │\n │ Built-in Tools │ │ └─────────────┘ │\n │ │ └─────────────────┘\n │ ┌─────────────┐ │\n │ │File Ops │ │\n │ │Bash Execute │ │\n │ │Todo Mgmt │ │\n │ │Web Fetch │ │\n │ │Task Spawn │ │\n │ └─────────────┘ │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables, never committed to git\n- **Configuration**: Automatically managed in user home directory (`~/.config/agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/agent/issues)\n- 💬 [Discussions](https://github.com/amranu/agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/agent/wiki)\n\n---\n\n**Happy coding with MCP Agent! 🤖✨**\n"}, "ba9ef9e7df27b5eeabef9c3be9ef8e870983d8c1": {"t": 1785764926.8723292, "n": 15220, "h": "07009148bd11364c", "c": "# MCP Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, and OpenRouter with easy extensibility\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/agent.git\n cd agent\n ```\n\n2. **Install the package**:\n ```bash\n pip install -e .\n ```\n\n3. **Configure API keys** (environment variables):\n ```bash\n # Set environment variables (required for the providers you want to use)\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Example usage\n agent chat --model deepseek:deepseek-chat\n ```\n\n Configuration is automatically saved to `~/.config/agent/config.json` and persists across sessions.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI\nagent mcp serve\n\n# Start with TCP transport (useful for debugging)\nagent mcp serve --port 3000 --host localhost\n```\n\nThe model server exposes AI models from 5 providers:\n- **Anthropic**: Claude models\n- **OpenAI**: GPT models\n- **DeepSeek**: Chat and reasoning models\n- **Gemini**: Google's Gemini models\n- **OpenRouter**: Multi-provider access\n\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\nagent mcp add myserver:node:/path/to/server.js\nagent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\nagent mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\nagent mcp list\n```\n\n#### Remove a server\n\n```bash\nagent mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\nagent ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\nagent switch anthropic:claude-3.5-sonnet\nagent switch openai:gpt-4-turbo-preview\nagent switch deepseek:deepseek-chat\nagent switch gemini:gemini-2.5-flash\n\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/agent/config.json`:\n\n- **API Keys**: Set via environment variables\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Host Configuration (optional)\nHOST_NAME=mcp-agent # defaults to 'mcp-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n### MCP Server Tools\n\nConnect external MCP servers to add functionality like:\n\n- **AI Model Access**: Multiple AI models from 5 providers via the built-in MCP model server\n- **API Integrations**: Connect to various web APIs\n- **File System**: Advanced file operations\n- **Database Connectors**: PostgreSQL, MySQL, SQLite\n- **Development Tools**: Git operations, code analysis\n- **Custom Services**: Your own MCP-compatible tools\n\n### AI Model Tools (via MCP Server)\n\nEach AI model is exposed as an MCP tool with persistent conversation support:\n\n- **anthropic_claude_3_5_sonnet**: Anthropic's flagship model for complex reasoning\n- **openai_gpt_4_turbo_preview**: OpenAI's most capable model\n- **deepseek_deepseek_chat**: DeepSeek's standard chat model\n- **deepseek_deepseek_reasoner**: DeepSeek's reasoning-focused model\n- **gemini_gemini_2_5_flash**: Google's fast, efficient model\n- **gemini_gemini_2_5_pro**: Google's most capable model\n- And 5 more models across all providers\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n- **Complete Response Display**: No truncation of results\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n- `/task` - Spawn a subagent for complex tasks\n- `/task-status` - Check status of running subagents\n\n## 📚 Examples\n\n### Example: MCP Model Server Usage\n\nUsing AI models via MCP (requires MCP client):\n\n```json\n// Start conversation with Claude\n{\n \"tool\": \"anthropic_claude_3_5_sonnet\",\n \"arguments\": {\n \"messages\": [{\"role\": \"user\", \"content\": \"Explain quantum computing\"}]\n }\n}\n\n// Continue conversation\n{\n \"tool\": \"anthropic_claude_3_5_sonnet\", \n \"arguments\": {\n \"conversation_id\": \"abc123\",\n \"messages\": [{\"role\": \"user\", \"content\": \"How does it compare to classical computing?\"}]\n }\n}\n```\n\n### Example: Basic File Operations\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\nYou: /task-status\n [Shows: \"1 subagent running: log-analysis-task\"]\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐ ┌──────────────────────┐ ┌─────────────────────┐\n│ CLI Interface │────│ BaseMCPAgent │────│ Provider-Model │\n│ │ │ (Centralized) │ │ Architecture │\n└─────────────────┘ └──────────────────────┘ │ ┌─────────────────┐ │\n │ │ │ MCPHost │ │\n ┌─────────────────┐ │ │ (Provider + │ │\n │ MCP Model Server│ │ │ Model) │ │\n │ │ │ └─────────────────┘ │\n │ ┌─────────────┐ │ │ ┌─────────────────┐ │\n │ │11 AI Models │ │ │ │ AnthropicProvider│ │\n │ │Conversations│ │ │ │ OpenAIProvider │ │\n │ │FastMCP Proto│ │ │ │ DeepSeekProvider│ │\n │ └─────────────┘ │ │ │ GoogleProvider │ │\n └─────────────────┘ │ │ OpenRouterProvider│ │\n │ │ └─────────────────┘ │\n ┌─────────────────┐ └─────────────────────┘\n │ Subagent Mgr │ │\n │ │ ┌─────────────────┐\n │ ┌─────────────┐ │ │ MCP Servers │\n │ │Focused Tasks│ │ │ │\n │ │Auto Cleanup │ │ │ ┌─────────────┐ │\n │ │Parallel Exec│ │ │ │ AI Models │ │\n │ └─────────────┘ │ │ │ File System │ │\n └─────────────────┘ │ │ APIs │ │\n │ │ │ Database │ │\n ┌─────────────────┐ │ │ Custom Tools│ │\n │ Built-in Tools │ │ └─────────────┘ │\n │ │ └─────────────────┘\n │ ┌─────────────┐ │\n │ │File Ops │ │\n │ │Bash Execute │ │\n │ │Todo Mgmt │ │\n │ │Web Fetch │ │\n │ │Task Spawn │ │\n │ └─────────────┘ │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables, never committed to git\n- **Configuration**: Automatically managed in user home directory (`~/.config/agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/agent/issues)\n- 💬 [Discussions](https://github.com/amranu/agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/agent/wiki)\n\n---\n\n**Happy coding with MCP Agent! 🤖✨**\n"}, "bf21ca866d3c5aa1a3a1ba72086996155d0ed960": {"t": 1785764928.569246, "n": 15751, "h": "ead89ea56e158849", "c": "# MCP Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, and OpenRouter with easy extensibility\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/agent.git\n cd agent\n ```\n\n2. **Install the package**:\n ```bash\n pip install -e .\n ```\n\n3. **Configure API keys** (environment variables):\n ```bash\n # Set environment variables (required for the providers you want to use)\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Example usage\n agent chat --model deepseek:deepseek-chat\n ```\n\n Configuration is automatically saved to `~/.config/agent/config.json` and persists across sessions.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI\nagent mcp serve\n\n# Start with TCP transport (useful for debugging)\nagent mcp serve --port 3000 --host localhost\n```\n\nThe model server exposes AI models from 5 providers:\n- **Anthropic**: Claude models\n- **OpenAI**: GPT models\n- **DeepSeek**: Chat and reasoning models\n- **Gemini**: Google's Gemini models\n- **OpenRouter**: Multi-provider access\n\n#### MCP Model Server Usage\n\nEach model tool supports persistent conversations:\n\n```json\n// Start new conversation\n{\n \"messages\": [{\"role\": \"user\", \"content\": \"Hello\"}]\n}\n// Returns: {\"response\": \"Hi! How can I help?\", \"conversation_id\": \"abc123\"}\n\n// Continue conversation\n{\n \"conversation_id\": \"abc123\",\n \"messages\": [{\"role\": \"user\", \"content\": \"What's 2+2?\"}]\n}\n\n// Clear conversation and restart\n{\n \"conversation_id\": \"abc123\", \n \"clear_conversation\": true,\n \"messages\": [{\"role\": \"user\", \"content\": \"New topic\"}]\n}\n```\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\nagent mcp add myserver:node:/path/to/server.js\nagent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\nagent mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\nagent mcp list\n```\n\n#### Remove a server\n\n```bash\nagent mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\nagent ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\nagent switch anthropic:claude-3.5-sonnet\nagent switch openai:gpt-4-turbo-preview\nagent switch deepseek:deepseek-chat\nagent switch gemini:gemini-2.5-flash\n\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/agent/config.json`:\n\n- **API Keys**: Set via environment variables\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Host Configuration (optional)\nHOST_NAME=mcp-agent # defaults to 'mcp-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n### MCP Server Tools\n\nConnect external MCP servers to add functionality like:\n\n- **AI Model Access**: Multiple AI models from 5 providers via the built-in MCP model server\n- **API Integrations**: Connect to various web APIs\n- **File System**: Advanced file operations\n- **Database Connectors**: PostgreSQL, MySQL, SQLite\n- **Development Tools**: Git operations, code analysis\n- **Custom Services**: Your own MCP-compatible tools\n\n### AI Model Tools (via MCP Server)\n\nEach AI model is exposed as an MCP tool with persistent conversation support:\n\n- **anthropic_claude_3_5_sonnet**: Anthropic's flagship model for complex reasoning\n- **openai_gpt_4_turbo_preview**: OpenAI's most capable model\n- **deepseek_deepseek_chat**: DeepSeek's standard chat model\n- **deepseek_deepseek_reasoner**: DeepSeek's reasoning-focused model\n- **gemini_gemini_2_5_flash**: Google's fast, efficient model\n- **gemini_gemini_2_5_pro**: Google's most capable model\n- And 5 more models across all providers\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n- **Complete Response Display**: No truncation of results\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n- `/task` - Spawn a subagent for complex tasks\n- `/task-status` - Check status of running subagents\n\n## 📚 Examples\n\n### Example: MCP Model Server Usage\n\nUsing AI models via MCP (requires MCP client):\n\n```json\n// Start conversation with Claude\n{\n \"tool\": \"anthropic_claude_3_5_sonnet\",\n \"arguments\": {\n \"messages\": [{\"role\": \"user\", \"content\": \"Explain quantum computing\"}]\n }\n}\n\n// Continue conversation\n{\n \"tool\": \"anthropic_claude_3_5_sonnet\", \n \"arguments\": {\n \"conversation_id\": \"abc123\",\n \"messages\": [{\"role\": \"user\", \"content\": \"How does it compare to classical computing?\"}]\n }\n}\n```\n\n### Example: Basic File Operations\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\nYou: /task-status\n [Shows: \"1 subagent running: log-analysis-task\"]\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐ ┌──────────────────────┐ ┌─────────────────────┐\n│ CLI Interface │────│ BaseMCPAgent │────│ Provider-Model │\n│ │ │ (Centralized) │ │ Architecture │\n└─────────────────┘ └──────────────────────┘ │ ┌─────────────────┐ │\n │ │ │ MCPHost │ │\n ┌─────────────────┐ │ │ (Provider + │ │\n │ MCP Model Server│ │ │ Model) │ │\n │ │ │ └─────────────────┘ │\n │ ┌─────────────┐ │ │ ┌─────────────────┐ │\n │ │11 AI Models │ │ │ │ AnthropicProvider│ │\n │ │Conversations│ │ │ │ OpenAIProvider │ │\n │ │FastMCP Proto│ │ │ │ DeepSeekProvider│ │\n │ └─────────────┘ │ │ │ GoogleProvider │ │\n └─────────────────┘ │ │ OpenRouterProvider│ │\n │ │ └─────────────────┘ │\n ┌─────────────────┐ └─────────────────────┘\n │ Subagent Mgr │ │\n │ │ ┌─────────────────┐\n │ ┌─────────────┐ │ │ MCP Servers │\n │ │Focused Tasks│ │ │ │\n │ │Auto Cleanup │ │ │ ┌─────────────┐ │\n │ │Parallel Exec│ │ │ │ AI Models │ │\n │ └─────────────┘ │ │ │ File System │ │\n └─────────────────┘ │ │ APIs │ │\n │ │ │ Database │ │\n ┌─────────────────┐ │ │ Custom Tools│ │\n │ Built-in Tools │ │ └─────────────┘ │\n │ │ └─────────────────┘\n │ ┌─────────────┐ │\n │ │File Ops │ │\n │ │Bash Execute │ │\n │ │Todo Mgmt │ │\n │ │Web Fetch │ │\n │ │Task Spawn │ │\n │ └─────────────┘ │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables, never committed to git\n- **Configuration**: Automatically managed in user home directory (`~/.config/agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/agent/issues)\n- 💬 [Discussions](https://github.com/amranu/agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/agent/wiki)\n\n---\n\n**Happy coding with MCP Agent! 🤖✨**\n"}, "89cbbeadc19b2fdea3f18a95c075125f4f81debc": {"t": 1785764930.1119478, "n": 16422, "h": "436bd49d54184788", "c": "# MCP Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, and OpenRouter with easy extensibility\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/agent.git\n cd agent\n ```\n\n2. **Install the package**:\n ```bash\n pip install -e .\n ```\n\n3. **Configure API keys** (environment variables):\n ```bash\n # Set environment variables (required for the providers you want to use)\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Example usage\n agent chat --model deepseek:deepseek-chat\n ```\n\n Configuration is automatically saved to `~/.config/agent/config.json` and persists across sessions.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI\nagent mcp serve\n\n# Start with TCP transport (useful for debugging)\nagent mcp serve --port 3000 --host localhost\n```\n\nThe model server exposes 11 AI models across 5 providers:\n- **Anthropic**: claude-3.5-sonnet, claude-3.5-haiku, claude-3-opus\n- **OpenAI**: gpt-4-turbo, gpt-3.5-turbo, o1-preview \n- **DeepSeek**: deepseek-chat, deepseek-reasoner\n- **Gemini**: gemini-2.5-flash, gemini-2.5-pro, gemini-1.5-pro\n- **OpenRouter**: Multi-provider access\n\n#### MCP Model Server Usage\n\nEach model tool supports persistent conversations:\n\n```json\n// Start new conversation\n{\n \"messages\": [{\"role\": \"user\", \"content\": \"Hello\"}]\n}\n// Returns: {\"response\": \"Hi! How can I help?\", \"conversation_id\": \"abc123\"}\n\n// Continue conversation\n{\n \"conversation_id\": \"abc123\",\n \"messages\": [{\"role\": \"user\", \"content\": \"What's 2+2?\"}]\n}\n\n// Clear conversation and restart\n{\n \"conversation_id\": \"abc123\", \n \"clear_conversation\": true,\n \"messages\": [{\"role\": \"user\", \"content\": \"New topic\"}]\n}\n```\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\nagent mcp add myserver:node:/path/to/server.js\nagent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\nagent mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\nagent mcp list\n```\n\n#### Remove a server\n\n```bash\nagent mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\nagent ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\nagent switch anthropic:claude-3.5-sonnet\nagent switch openai:gpt-4-turbo-preview\nagent switch deepseek:deepseek-chat\nagent switch gemini:gemini-2.5-flash\n\n# Legacy model switching (still supported)\nagent switch-deepseek # DeepSeek Chat model\nagent switch-reason # DeepSeek Reasoner model\nagent switch-gemini-flash # Google Gemini Flash\nagent switch-gemini-pro # Google Gemini Pro\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n# Legacy commands (still supported)\n/switch-deepseek\n/switch-reason\n/switch-gemini-flash\n/switch-gemini-pro\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/agent/config.json`:\n\n- **API Keys**: Set via environment variables\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Host Configuration (optional)\nHOST_NAME=mcp-agent # defaults to 'mcp-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n### MCP Server Tools\n\nConnect external MCP servers to add functionality like:\n\n- **AI Model Access**: All 11 AI models via the built-in MCP model server\n- **API Integrations**: Connect to various web APIs\n- **File System**: Advanced file operations\n- **Database Connectors**: PostgreSQL, MySQL, SQLite\n- **Development Tools**: Git operations, code analysis\n- **Custom Services**: Your own MCP-compatible tools\n\n### AI Model Tools (via MCP Server)\n\nEach AI model is exposed as an MCP tool with persistent conversation support:\n\n- **anthropic_claude_3_5_sonnet**: Anthropic's flagship model for complex reasoning\n- **openai_gpt_4_turbo_preview**: OpenAI's most capable model\n- **deepseek_deepseek_chat**: DeepSeek's standard chat model\n- **deepseek_deepseek_reasoner**: DeepSeek's reasoning-focused model\n- **gemini_gemini_2_5_flash**: Google's fast, efficient model\n- **gemini_gemini_2_5_pro**: Google's most capable model\n- And 5 more models across all providers\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n- **Complete Response Display**: No truncation of results\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n- `/switch-deepseek` - Switch to DeepSeek Chat (legacy)\n- `/switch-reason` - Switch to DeepSeek Reasoner (legacy)\n- `/switch-gemini-flash` - Switch to Gemini Flash (legacy)\n- `/switch-gemini-pro` - Switch to Gemini Pro (legacy)\n- `/task` - Spawn a subagent for complex tasks\n- `/task-status` - Check status of running subagents\n\n## 📚 Examples\n\n### Example: MCP Model Server Usage\n\nUsing AI models via MCP (requires MCP client):\n\n```json\n// Start conversation with Claude\n{\n \"tool\": \"anthropic_claude_3_5_sonnet\",\n \"arguments\": {\n \"messages\": [{\"role\": \"user\", \"content\": \"Explain quantum computing\"}]\n }\n}\n\n// Continue conversation\n{\n \"tool\": \"anthropic_claude_3_5_sonnet\", \n \"arguments\": {\n \"conversation_id\": \"abc123\",\n \"messages\": [{\"role\": \"user\", \"content\": \"How does it compare to classical computing?\"}]\n }\n}\n```\n\n### Example: Basic File Operations\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\nYou: /task-status\n [Shows: \"1 subagent running: log-analysis-task\"]\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐ ┌──────────────────────┐ ┌─────────────────────┐\n│ CLI Interface │────│ BaseMCPAgent │────│ Provider-Model │\n│ │ │ (Centralized) │ │ Architecture │\n└─────────────────┘ └──────────────────────┘ │ ┌─────────────────┐ │\n │ │ │ MCPHost │ │\n ┌─────────────────┐ │ │ (Provider + │ │\n │ MCP Model Server│ │ │ Model) │ │\n │ │ │ └─────────────────┘ │\n │ ┌─────────────┐ │ │ ┌─────────────────┐ │\n │ │11 AI Models │ │ │ │ AnthropicProvider│ │\n │ │Conversations│ │ │ │ OpenAIProvider │ │\n │ │FastMCP Proto│ │ │ │ DeepSeekProvider│ │\n │ └─────────────┘ │ │ │ GoogleProvider │ │\n └─────────────────┘ │ │ OpenRouterProvider│ │\n │ │ └─────────────────┘ │\n ┌─────────────────┐ └─────────────────────┘\n │ Subagent Mgr │ │\n │ │ ┌─────────────────┐\n │ ┌─────────────┐ │ │ MCP Servers │\n │ │Focused Tasks│ │ │ │\n │ │Auto Cleanup │ │ │ ┌─────────────┐ │\n │ │Parallel Exec│ │ │ │ AI Models │ │\n │ └─────────────┘ │ │ │ File System │ │\n └─────────────────┘ │ │ APIs │ │\n │ │ │ Database │ │\n ┌─────────────────┐ │ │ Custom Tools│ │\n │ Built-in Tools │ │ └─────────────┘ │\n │ │ └─────────────────┘\n │ ┌─────────────┐ │\n │ │File Ops │ │\n │ │Bash Execute │ │\n │ │Todo Mgmt │ │\n │ │Web Fetch │ │\n │ │Task Spawn │ │\n │ └─────────────┘ │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables, never committed to git\n- **Configuration**: Automatically managed in user home directory (`~/.config/agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/agent/issues)\n- 💬 [Discussions](https://github.com/amranu/agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/agent/wiki)\n\n---\n\n**Happy coding with MCP Agent! 🤖✨**\n"}, "dbd8b6746e0fdbe1ddd46553b891822e5581d923": {"t": 1785764931.6275556, "n": 16430, "h": "9196b84acfd3775b", "c": "# MCP Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, and OpenRouter with easy extensibility\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/cli-agent.git\n cd cli-agent\n ```\n\n2. **Install the package**:\n ```bash\n pip install -e .\n ```\n\n3. **Configure API keys** (environment variables):\n ```bash\n # Set environment variables (required for the providers you want to use)\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Example usage\n agent chat --model deepseek:deepseek-chat\n ```\n\n Configuration is automatically saved to `~/.config/agent/config.json` and persists across sessions.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI\nagent mcp serve\n\n# Start with TCP transport (useful for debugging)\nagent mcp serve --port 3000 --host localhost\n```\n\nThe model server exposes 11 AI models across 5 providers:\n- **Anthropic**: claude-3.5-sonnet, claude-3.5-haiku, claude-3-opus\n- **OpenAI**: gpt-4-turbo, gpt-3.5-turbo, o1-preview \n- **DeepSeek**: deepseek-chat, deepseek-reasoner\n- **Gemini**: gemini-2.5-flash, gemini-2.5-pro, gemini-1.5-pro\n- **OpenRouter**: Multi-provider access\n\n#### MCP Model Server Usage\n\nEach model tool supports persistent conversations:\n\n```json\n// Start new conversation\n{\n \"messages\": [{\"role\": \"user\", \"content\": \"Hello\"}]\n}\n// Returns: {\"response\": \"Hi! How can I help?\", \"conversation_id\": \"abc123\"}\n\n// Continue conversation\n{\n \"conversation_id\": \"abc123\",\n \"messages\": [{\"role\": \"user\", \"content\": \"What's 2+2?\"}]\n}\n\n// Clear conversation and restart\n{\n \"conversation_id\": \"abc123\", \n \"clear_conversation\": true,\n \"messages\": [{\"role\": \"user\", \"content\": \"New topic\"}]\n}\n```\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\nagent mcp add myserver:node:/path/to/server.js\nagent mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\nagent mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\nagent mcp list\n```\n\n#### Remove a server\n\n```bash\nagent mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\nagent ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\nagent switch anthropic:claude-3.5-sonnet\nagent switch openai:gpt-4-turbo-preview\nagent switch deepseek:deepseek-chat\nagent switch gemini:gemini-2.5-flash\n\n# Legacy model switching (still supported)\nagent switch-deepseek # DeepSeek Chat model\nagent switch-reason # DeepSeek Reasoner model\nagent switch-gemini-flash # Google Gemini Flash\nagent switch-gemini-pro # Google Gemini Pro\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n# Legacy commands (still supported)\n/switch-deepseek\n/switch-reason\n/switch-gemini-flash\n/switch-gemini-pro\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/agent/config.json`:\n\n- **API Keys**: Set via environment variables\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Host Configuration (optional)\nHOST_NAME=mcp-agent # defaults to 'mcp-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n### MCP Server Tools\n\nConnect external MCP servers to add functionality like:\n\n- **AI Model Access**: All 11 AI models via the built-in MCP model server\n- **API Integrations**: Connect to various web APIs\n- **File System**: Advanced file operations\n- **Database Connectors**: PostgreSQL, MySQL, SQLite\n- **Development Tools**: Git operations, code analysis\n- **Custom Services**: Your own MCP-compatible tools\n\n### AI Model Tools (via MCP Server)\n\nEach AI model is exposed as an MCP tool with persistent conversation support:\n\n- **anthropic_claude_3_5_sonnet**: Anthropic's flagship model for complex reasoning\n- **openai_gpt_4_turbo_preview**: OpenAI's most capable model\n- **deepseek_deepseek_chat**: DeepSeek's standard chat model\n- **deepseek_deepseek_reasoner**: DeepSeek's reasoning-focused model\n- **gemini_gemini_2_5_flash**: Google's fast, efficient model\n- **gemini_gemini_2_5_pro**: Google's most capable model\n- And 5 more models across all providers\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n- **Complete Response Display**: No truncation of results\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n- `/switch-deepseek` - Switch to DeepSeek Chat (legacy)\n- `/switch-reason` - Switch to DeepSeek Reasoner (legacy)\n- `/switch-gemini-flash` - Switch to Gemini Flash (legacy)\n- `/switch-gemini-pro` - Switch to Gemini Pro (legacy)\n- `/task` - Spawn a subagent for complex tasks\n- `/task-status` - Check status of running subagents\n\n## 📚 Examples\n\n### Example: MCP Model Server Usage\n\nUsing AI models via MCP (requires MCP client):\n\n```json\n// Start conversation with Claude\n{\n \"tool\": \"anthropic_claude_3_5_sonnet\",\n \"arguments\": {\n \"messages\": [{\"role\": \"user\", \"content\": \"Explain quantum computing\"}]\n }\n}\n\n// Continue conversation\n{\n \"tool\": \"anthropic_claude_3_5_sonnet\", \n \"arguments\": {\n \"conversation_id\": \"abc123\",\n \"messages\": [{\"role\": \"user\", \"content\": \"How does it compare to classical computing?\"}]\n }\n}\n```\n\n### Example: Basic File Operations\n\n```bash\nagent chat --model deepseek:deepseek-chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\nYou: /task-status\n [Shows: \"1 subagent running: log-analysis-task\"]\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐ ┌──────────────────────┐ ┌─────────────────────┐\n│ CLI Interface │────│ BaseMCPAgent │────│ Provider-Model │\n│ │ │ (Centralized) │ │ Architecture │\n└─────────────────┘ └──────────────────────┘ │ ┌─────────────────┐ │\n │ │ │ MCPHost │ │\n ┌─────────────────┐ │ │ (Provider + │ │\n │ MCP Model Server│ │ │ Model) │ │\n │ │ │ └─────────────────┘ │\n │ ┌─────────────┐ │ │ ┌─────────────────┐ │\n │ │11 AI Models │ │ │ │ AnthropicProvider│ │\n │ │Conversations│ │ │ │ OpenAIProvider │ │\n │ │FastMCP Proto│ │ │ │ DeepSeekProvider│ │\n │ └─────────────┘ │ │ │ GoogleProvider │ │\n └─────────────────┘ │ │ OpenRouterProvider│ │\n │ │ └─────────────────┘ │\n ┌─────────────────┐ └─────────────────────┘\n │ Subagent Mgr │ │\n │ │ ┌─────────────────┐\n │ ┌─────────────┐ │ │ MCP Servers │\n │ │Focused Tasks│ │ │ │\n │ │Auto Cleanup │ │ │ ┌─────────────┐ │\n │ │Parallel Exec│ │ │ │ AI Models │ │\n │ └─────────────┘ │ │ │ File System │ │\n └─────────────────┘ │ │ APIs │ │\n │ │ │ Database │ │\n ┌─────────────────┐ │ │ Custom Tools│ │\n │ Built-in Tools │ │ └─────────────┘ │\n │ │ └─────────────────┘\n │ ┌─────────────┐ │\n │ │File Ops │ │\n │ │Bash Execute │ │\n │ │Todo Mgmt │ │\n │ │Web Fetch │ │\n │ │Task Spawn │ │\n │ └─────────────┘ │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables, never committed to git\n- **Configuration**: Automatically managed in user home directory (`~/.config/agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/agent/issues)\n- 💬 [Discussions](https://github.com/amranu/agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/agent/wiki)\n\n---\n\n**Happy coding with MCP Agent! 🤖✨**\n"}, "a7fcc210e19ab4776481238901c51cd88c7ec564": {"t": 1785764933.319408, "n": 16595, "h": "f3069f5af88ce5bf", "c": "# MCP Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, and OpenRouter with easy extensibility\n- **MCP Model Server**: Expose all AI models as standardized MCP tools with persistent conversations\n- **Modular Architecture**: Provider-model separation with centralized base agent for maximum flexibility\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Conversations**: Maintain conversation context across multiple tool calls for each AI model\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n- **Enhanced Tool Display**: Full parameter visibility and complete response output (no truncation)\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/agent.git\n cd agent\n ```\n\n2. **Install dependencies**:\n ```bash\n pip install -r requirements.txt\n ```\n\n3. **Configure API keys** (environment variables or interactive setup):\n ```bash\n # Set environment variables (recommended)\n export ANTHROPIC_API_KEY=your_anthropic_api_key_here\n export OPENAI_API_KEY=your_openai_api_key_here\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n export OPENROUTER_API_KEY=your_openrouter_api_key_here\n\n # Or use interactive configuration\n python agent.py chat # Will prompt for missing keys\n ```\n\n Configuration is automatically saved to `~/.config/agent/config.py` and persists across sessions.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\npython agent.py chat\n```\n\n### MCP Model Server\n\nStart the MCP model server to expose all AI models as standardized MCP tools with persistent conversations:\n\n```bash\n# Start via stdio transport (recommended for MCP clients)\npython mcp_server.py --stdio\n\n# Or start via agent CLI\npython agent.py mcp serve\n\n# Start with TCP transport (useful for debugging)\npython agent.py mcp serve --port 3000 --host localhost\n```\n\nThe model server exposes 11 AI models across 5 providers:\n- **Anthropic**: claude-3.5-sonnet, claude-3.5-haiku, claude-3-opus\n- **OpenAI**: gpt-4-turbo, gpt-3.5-turbo, o1-preview \n- **DeepSeek**: deepseek-chat, deepseek-reasoner\n- **Gemini**: gemini-2.5-flash, gemini-2.5-pro, gemini-1.5-pro\n- **OpenRouter**: Multi-provider access\n\n#### MCP Model Server Usage\n\nEach model tool supports persistent conversations:\n\n```json\n// Start new conversation\n{\n \"messages\": [{\"role\": \"user\", \"content\": \"Hello\"}]\n}\n// Returns: {\"response\": \"Hi! How can I help?\", \"conversation_id\": \"abc123\"}\n\n// Continue conversation\n{\n \"conversation_id\": \"abc123\",\n \"messages\": [{\"role\": \"user\", \"content\": \"What's 2+2?\"}]\n}\n\n// Clear conversation and restart\n{\n \"conversation_id\": \"abc123\", \n \"clear_conversation\": true,\n \"messages\": [{\"role\": \"user\", \"content\": \"New topic\"}]\n}\n```\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\npython agent.py mcp add myserver:node:/path/to/server.js\npython agent.py mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n\n# Add the AI models server to your MCP configuration\npython agent.py mcp add ai-models:python:mcp_server.py:--stdio\n```\n\n#### List configured servers\n\n```bash\npython agent.py mcp list\n```\n\n#### Remove a server\n\n```bash\npython agent.py mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\npython agent.py ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models using the provider-model format (configuration persists automatically):\n\n```bash\n# Provider-model format switching\npython agent.py switch anthropic:claude-3.5-sonnet\npython agent.py switch openai:gpt-4-turbo-preview\npython agent.py switch deepseek:deepseek-chat\npython agent.py switch gemini:gemini-2.5-flash\n\n# Legacy model switching (still supported)\npython agent.py switch-deepseek # DeepSeek Chat model\npython agent.py switch-reason # DeepSeek Reasoner model\npython agent.py switch-gemini-flash # Google Gemini Flash\npython agent.py switch-gemini-pro # Google Gemini Pro\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch anthropic:claude-3.5-sonnet\n/switch openai:gpt-4-turbo-preview\n/switch deepseek:deepseek-reasoner\n/switch gemini:gemini-2.5-pro\n\n# Legacy commands (still supported)\n/switch-deepseek\n/switch-reason\n/switch-gemini-flash\n/switch-gemini-pro\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/agent/config.py`:\n\n- **API Keys**: Set via environment variables or interactive prompts\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# Anthropic Configuration (required for Claude models)\nANTHROPIC_API_KEY=your_key_here\nANTHROPIC_MODEL=claude-3-5-sonnet-20241022 # optional, defaults to claude-3-5-sonnet-20241022\nANTHROPIC_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenAI Configuration (required for GPT models) \nOPENAI_API_KEY=your_key_here\nOPENAI_MODEL=gpt-4-turbo-preview # optional, defaults to gpt-4-turbo-preview\nOPENAI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.6 # optional, defaults to 0.6\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# OpenRouter Configuration (optional for multi-provider access)\nOPENROUTER_API_KEY=your_key_here\nOPENROUTER_MODEL=anthropic/claude-3.5-sonnet # optional\nOPENROUTER_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Provider-Model Selection (new format)\nDEFAULT_PROVIDER_MODEL=anthropic:claude-3.5-sonnet # defaults to deepseek:deepseek-chat\n\n# Host Configuration (optional)\nHOST_NAME=mcp-agent # defaults to 'mcp-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n### MCP Server Tools\n\nConnect external MCP servers to add functionality like:\n\n- **AI Model Access**: All 11 AI models via the built-in MCP model server\n- **API Integrations**: Connect to various web APIs\n- **File System**: Advanced file operations\n- **Database Connectors**: PostgreSQL, MySQL, SQLite\n- **Development Tools**: Git operations, code analysis\n- **Custom Services**: Your own MCP-compatible tools\n\n### AI Model Tools (via MCP Server)\n\nEach AI model is exposed as an MCP tool with persistent conversation support:\n\n- **anthropic_claude_3_5_sonnet**: Anthropic's flagship model for complex reasoning\n- **openai_gpt_4_turbo_preview**: OpenAI's most capable model\n- **deepseek_deepseek_chat**: DeepSeek's standard chat model\n- **deepseek_deepseek_reasoner**: DeepSeek's reasoning-focused model\n- **gemini_gemini_2_5_flash**: Google's fast, efficient model\n- **gemini_gemini_2_5_pro**: Google's most capable model\n- And 5 more models across all providers\n\nAll model tools support:\n- **Persistent Conversations**: Maintain context across calls\n- **Conversation Management**: Create, continue, or clear conversations\n- **Full Parameter Control**: Temperature, max_tokens, system prompts\n- **Complete Response Display**: No truncation of results\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch <provider>:<model>` - Switch to any provider-model combination\n- `/switch-deepseek` - Switch to DeepSeek Chat (legacy)\n- `/switch-reason` - Switch to DeepSeek Reasoner (legacy)\n- `/switch-gemini-flash` - Switch to Gemini Flash (legacy)\n- `/switch-gemini-pro` - Switch to Gemini Pro (legacy)\n- `/task` - Spawn a subagent for complex tasks\n- `/task-status` - Check status of running subagents\n\n## 📚 Examples\n\n### Example: MCP Model Server Usage\n\nUsing AI models via MCP (requires MCP client):\n\n```json\n// Start conversation with Claude\n{\n \"tool\": \"anthropic_claude_3_5_sonnet\",\n \"arguments\": {\n \"messages\": [{\"role\": \"user\", \"content\": \"Explain quantum computing\"}]\n }\n}\n\n// Continue conversation\n{\n \"tool\": \"anthropic_claude_3_5_sonnet\", \n \"arguments\": {\n \"conversation_id\": \"abc123\",\n \"messages\": [{\"role\": \"user\", \"content\": \"How does it compare to classical computing?\"}]\n }\n}\n```\n\n### Example: Basic File Operations\n\n```bash\npython agent.py chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\nYou: /task-status\n [Shows: \"1 subagent running: log-analysis-task\"]\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Provider-Model Architecture\n\n```\n┌─────────────────┐ ┌──────────────────────┐ ┌─────────────────────┐\n│ CLI Interface │────│ BaseMCPAgent │────│ Provider-Model │\n│ │ │ (Centralized) │ │ Architecture │\n└─────────────────┘ └──────────────────────┘ │ ┌─────────────────┐ │\n │ │ │ MCPHost │ │\n ┌─────────────────┐ │ │ (Provider + │ │\n │ MCP Model Server│ │ │ Model) │ │\n │ │ │ └─────────────────┘ │\n │ ┌─────────────┐ │ │ ┌─────────────────┐ │\n │ │11 AI Models │ │ │ │ AnthropicProvider│ │\n │ │Conversations│ │ │ │ OpenAIProvider │ │\n │ │FastMCP Proto│ │ │ │ DeepSeekProvider│ │\n │ └─────────────┘ │ │ │ GoogleProvider │ │\n └─────────────────┘ │ │ OpenRouterProvider│ │\n │ │ └─────────────────┘ │\n ┌─────────────────┐ └─────────────────────┘\n │ Subagent Mgr │ │\n │ │ ┌─────────────────┐\n │ ┌─────────────┐ │ │ MCP Servers │\n │ │Focused Tasks│ │ │ │\n │ │Auto Cleanup │ │ │ ┌─────────────┐ │\n │ │Parallel Exec│ │ │ │ AI Models │ │\n │ └─────────────┘ │ │ │ File System │ │\n └─────────────────┘ │ │ APIs │ │\n │ │ │ Database │ │\n ┌─────────────────┐ │ │ Custom Tools│ │\n │ Built-in Tools │ │ └─────────────┘ │\n │ │ └─────────────────┘\n │ ┌─────────────┐ │\n │ │File Ops │ │\n │ │Bash Execute │ │\n │ │Todo Mgmt │ │\n │ │Web Fetch │ │\n │ │Task Spawn │ │\n │ └─────────────┘ │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Provider-Model Separation**: API providers decoupled from model characteristics\n- **MCP Model Server**: Standardized access to all AI models via MCP protocol\n- **Persistent Conversations**: Conversation context maintained across tool calls\n- **Easy Extensibility**: Adding new providers or models requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Multi-Provider Access**: Same model accessible through different providers\n- **Enhanced Visibility**: Full parameter display and complete response output\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- API keys for desired providers:\n - Anthropic API key (for Claude models)\n - OpenAI API key (for GPT models)\n - DeepSeek API key (for DeepSeek models)\n - Google AI Studio API key (for Gemini models)\n - OpenRouter API key (for multi-provider access)\n- FastMCP for MCP server functionality\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables, never committed to git\n- **Configuration**: Automatically managed in user home directory (`~/.config/agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/agent/issues)\n- 💬 [Discussions](https://github.com/amranu/agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/agent/wiki)\n\n---\n\n**Happy coding with MCP Agent! 🤖✨**\n"}, "cc10d6d3f20b780cf281cd8f35c0199fe19ad81e": {"t": 1785764935.0922499, "n": 10748, "h": "0e8695b9a9a13444", "c": "# MCP Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for DeepSeek and Google Gemini models with easy extensibility\n- **Modular Architecture**: Centralized base agent with provider-specific implementations\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Configuration**: Automatic configuration management in `~/.config/agent/`\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/agent.git\n cd agent\n ```\n\n2. **Install dependencies**:\n ```bash\n pip install -r requirements.txt\n ```\n\n3. **Configure API keys** (environment variables or interactive setup):\n ```bash\n # Set environment variables (recommended)\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n\n # Or use interactive configuration\n python agent.py chat # Will prompt for missing keys\n ```\n\n Configuration is automatically saved to `~/.config/agent/config.py` and persists across sessions.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\npython agent.py chat\n```\n\n### MCP Server Management\n\n#### Add a new MCP server\n\n```bash\n# Format: name:command:arg1:arg2:...\npython agent.py mcp add myserver:node:/path/to/server.js\npython agent.py mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n```\n\n#### List configured servers\n\n```bash\npython agent.py mcp list\n```\n\n#### Remove a server\n\n```bash\npython agent.py mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\npython agent.py ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models (configuration persists automatically):\n\n```bash\npython agent.py switch-deepseek # DeepSeek Chat model\npython agent.py switch-reason # DeepSeek Reasoner model\npython agent.py switch-gemini-flash # Google Gemini Flash\npython agent.py switch-gemini-pro # Google Gemini Pro\n```\n\nOr use slash commands within interactive chat:\n\n```\n/switch-deepseek\n/switch-reason\n/switch-gemini-flash\n/switch-gemini-pro\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/agent/config.py`:\n\n- **API Keys**: Set via environment variables or interactive prompts\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Host Configuration (optional)\nHOST_NAME=mcp-agent # defaults to 'mcp-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n### MCP Server Tools\n\nConnect external MCP servers to add functionality like:\n\n- **API Integrations**: Connect to various web APIs\n- **File System**: Advanced file operations\n- **Database Connectors**: PostgreSQL, MySQL, SQLite\n- **Development Tools**: Git operations, code analysis\n- **Custom Services**: Your own MCP-compatible tools\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch-deepseek` - Switch to DeepSeek Chat\n- `/switch-reason` - Switch to DeepSeek Reasoner\n- `/switch-gemini-flash` - Switch to Gemini Flash\n- `/switch-gemini-pro` - Switch to Gemini Pro\n- `/task` - Spawn a subagent for complex tasks\n- `/task-status` - Check status of running subagents\n\n## 📚 Examples\n\n### Example: Basic File Operations\n\n```bash\npython agent.py chat\n```\n\nIn chat:\n\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies\n\nYou: Can you analyze this large log file and find any error patterns?\n [Agent automatically spawns subagent for file analysis]\n\nYou: /task-status\n [Shows: \"1 subagent running: log-analysis-task\"]\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Modular Agent Architecture\n\n```\n┌─────────────────┐ ┌──────────────────────┐ ┌─────────────────┐\n│ CLI Interface │────│ BaseMCPAgent │────│ AI Backends │\n│ │ │ (Centralized) │ │ │\n└─────────────────┘ └──────────────────────┘ │ ┌─────────────┐ │\n │ │ │DeepSeek Host│ │\n │ │ │Gemini Host │ │\n ┌─────────────────┐ │ │[Easy to │ │\n │ Subagent Mgr │ │ │ extend] │ │\n │ │ │ └─────────────┘ │\n │ ┌─────────────┐ │ └─────────────────┘\n │ │Focused Tasks│ │ │\n │ │Auto Cleanup │ │ ┌─────────────────┐\n │ │Parallel Exec│ │ │ MCP Servers │\n │ └─────────────┘ │ │ │\n └─────────────────┘ │ ┌─────────────┐ │\n │ │ │ File System │ │\n ┌─────────────────┐ │ │ APIs │ │\n │ Built-in Tools │ │ │ Database │ │\n │ │ │ │ Custom Tools│ │\n │ ┌─────────────┐ │ │ └─────────────┘ │\n │ │File Ops │ │ └─────────────────┘\n │ │Bash Execute │ │\n │ │Todo Mgmt │ │\n │ │Web Fetch │ │\n │ │Task Spawn │ │\n │ └─────────────┘ │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Centralized Base Agent**: Shared functionality across all LLM providers\n- **Easy Extensibility**: Adding new LLM backends requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Persistent Configuration**: No manual file editing required\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- DeepSeek API key (for DeepSeek models)\n- Google AI Studio API key (for Gemini models)\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables, never committed to git\n- **Configuration**: Automatically managed in user home directory (`~/.config/agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/agent/issues)\n- 💬 [Discussions](https://github.com/amranu/agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/agent/wiki)\n\n---\n\n**Happy coding with MCP Agent! 🤖✨**\n"}, "4a6e574127a53463608d5bc769c05787ee71acbc": {"t": 1785764936.6928205, "n": 10624, "h": "8b87c51fca7003a4", "c": "# MCP Agent\n\nA powerful, modular command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Features a centralized architecture that makes it easy to add new LLM providers while providing robust tool integration and subagent management capabilities.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for DeepSeek and Google Gemini models with easy extensibility\n- **Modular Architecture**: Centralized base agent with provider-specific implementations\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Configuration**: Automatic configuration management in `~/.config/agent/`\n- **Interactive Chat**: Real-time conversation with AI models and comprehensive tool access\n- **Subagent System**: Spawn focused subagents for complex tasks with automatic coordination\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, todo management, and task delegation\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/agent.git\n cd agent\n ```\n\n2. **Install dependencies**:\n ```bash\n pip install -r requirements.txt\n ```\n\n3. **Configure API keys** (environment variables or interactive setup):\n ```bash\n # Set environment variables (recommended)\n export DEEPSEEK_API_KEY=your_deepseek_api_key_here\n export GEMINI_API_KEY=your_gemini_api_key_here\n \n # Or use interactive configuration\n python agent.py chat # Will prompt for missing keys\n ```\n\n Configuration is automatically saved to `~/.config/agent/config.py` and persists across sessions.\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\npython agent.py chat\n```\n\n### MCP Server Management\n\n#### Add a new MCP server\n```bash\n# Format: name:command:arg1:arg2:...\npython agent.py mcp add myserver:node:/path/to/server.js\npython agent.py mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n```\n\n#### List configured servers\n```bash\npython agent.py mcp list\n```\n\n#### Remove a server\n```bash\npython agent.py mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\npython agent.py ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models (configuration persists automatically):\n\n```bash\npython agent.py switch-deepseek # DeepSeek Chat model\npython agent.py switch-reason # DeepSeek Reasoner model\npython agent.py switch-gemini-flash # Google Gemini Flash\npython agent.py switch-gemini-pro # Google Gemini Pro\n```\n\nOr use slash commands within interactive chat:\n```\n/switch-deepseek\n/switch-reason\n/switch-gemini-flash\n/switch-gemini-pro\n```\n\n## 🔧 Configuration\n\n### Persistent Configuration System\n\nThe agent uses an automatic persistent configuration system that saves settings to `~/.config/agent/config.py`:\n\n- **API Keys**: Set via environment variables or interactive prompts\n- **Model Preferences**: Automatically saved when using switch commands\n- **MCP Servers**: Managed through the CLI and persisted across sessions\n- **Tool Permissions**: Configurable with session-based approval system\n\n### Environment Variables\n\nConfigure the agent through environment variables:\n\n```bash\n# DeepSeek Configuration (required for DeepSeek models)\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat # optional, defaults to deepseek-chat\nDEEPSEEK_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Gemini Configuration (required for Gemini models)\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash # optional, defaults to gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7 # optional, defaults to 0.7\n\n# Host Configuration (optional)\nHOST_NAME=mcp-agent # defaults to 'mcp-agent'\nLOG_LEVEL=INFO # defaults to INFO\n```\n\nConfiguration changes made via commands (like model switching) are automatically persisted and don't require manual `.env` file editing.\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with comprehensive built-in tools:\n\n- **File Operations**: Read, write, edit, and search files with surgical precision\n- **Directory Operations**: List directories, get current path, navigate filesystem\n- **Shell Execution**: Run bash commands with full output capture\n- **Web Fetching**: Download and process web content\n- **Todo Management**: Organize and track tasks across sessions\n- **Task Delegation**: Spawn focused subagents for complex or context-heavy tasks\n- **Text Processing**: Search, replace, and manipulate text content\n\n### MCP Server Tools\n\nConnect external MCP servers to add functionality like:\n\n- **API Integrations**: Connect to various web APIs\n- **File System**: Advanced file operations\n- **Database Connectors**: PostgreSQL, MySQL, SQLite\n- **Development Tools**: Git operations, code analysis\n- **Custom Services**: Your own MCP-compatible tools\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch-deepseek` - Switch to DeepSeek Chat\n- `/switch-reason` - Switch to DeepSeek Reasoner \n- `/switch-gemini-flash` - Switch to Gemini Flash\n- `/switch-gemini-pro` - Switch to Gemini Pro\n- `/task` - Spawn a subagent for complex tasks\n- `/task-status` - Check status of running subagents\n\n## 📚 Examples\n\n### Example: Basic File Operations\n\n```bash\npython agent.py chat\n```\n\nIn chat:\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n### Example: Subagent Task Delegation\n\nFor complex or context-heavy tasks, delegate to focused subagents:\n\n```\nYou: /task Analyze all Python files in the src/ directory and create a summary of the class structure and dependencies\n\nYou: Can you analyze this large log file and find any error patterns? \n [Agent automatically spawns subagent for file analysis]\n\nYou: /task-status\n [Shows: \"1 subagent running: log-analysis-task\"]\n```\n\nSubagents work independently and automatically return results to the main conversation.\n\n## 🏗️ Architecture\n\n### Modular Agent Architecture\n\n```\n┌─────────────────┐ ┌──────────────────────┐ ┌─────────────────┐\n│ CLI Interface │────│ BaseMCPAgent │────│ AI Backends │\n│ │ │ (Centralized) │ │ │\n└─────────────────┘ └──────────────────────┘ │ ┌─────────────┐ │\n │ │ │DeepSeek Host│ │\n │ │ │Gemini Host │ │\n ┌─────────────────┐ │ │[Easy to │ │\n │ Subagent Mgr │ │ │ extend] │ │\n │ │ │ └─────────────┘ │\n │ ┌─────────────┐ │ └─────────────────┘\n │ │Focused Tasks│ │ │\n │ │Auto Cleanup │ │ ┌─────────────────┐\n │ │Parallel Exec│ │ │ MCP Servers │\n │ └─────────────┘ │ │ │\n └─────────────────┘ │ ┌─────────────┐ │\n │ │ │ File System │ │\n ┌─────────────────┐ │ │ APIs │ │\n │ Built-in Tools │ │ │ Database │ │\n │ │ │ │ Custom Tools│ │\n │ ┌─────────────┐ │ │ └─────────────┘ │\n │ │File Ops │ │ └─────────────────┘\n │ │Bash Execute │ │\n │ │Todo Mgmt │ │\n │ │Web Fetch │ │\n │ │Task Spawn │ │\n │ └─────────────┘ │\n └─────────────────┘\n```\n\n### Key Architectural Benefits\n\n- **Centralized Base Agent**: Shared functionality across all LLM providers\n- **Easy Extensibility**: Adding new LLM backends requires minimal code\n- **Robust Tool Integration**: Unified tool execution with provider-specific optimizations\n- **Intelligent Subagent System**: Automatic task delegation and coordination\n- **Persistent Configuration**: No manual file editing required\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- DeepSeek API key (for DeepSeek models)\n- Google AI Studio API key (for Gemini models)\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- **API Keys**: Stored as environment variables, never committed to git\n- **Configuration**: Automatically managed in user home directory (`~/.config/agent/`)\n- **MCP Servers**: Local configurations with session-based tool permissions\n- **Tool Execution**: Built-in permission system for sensitive operations\n- **Subagent Isolation**: Subagents run in controlled environments with specific tool access\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/agent/issues)\n- 💬 [Discussions](https://github.com/amranu/agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/agent/wiki)\n\n---\n\n**Happy coding with MCP Agent! 🤖✨**"}, "366a6ca928a27d6280937fe93299694e85e819e9": {"t": 1785764938.655781, "n": 6431, "h": "0b21d4aa1faa83fc", "c": "# MCP Agent\n\nA powerful command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Connect multiple MCP servers to extend your AI agent with external APIs, file systems, databases, and more.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for DeepSeek and Google Gemini models\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Configuration**: Save and manage MCP server configurations\n- **Interactive Chat**: Real-time conversation with AI models and tool access\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, and todo management\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/agent.git\n cd agent\n ```\n\n2. **Install dependencies**:\n ```bash\n pip install -r requirements.txt\n ```\n\n3. **Initialize configuration**:\n ```bash\n python agent.py init\n ```\n\n4. **Configure API keys** by editing the generated `.env` file:\n ```bash\n # DeepSeek API Configuration\n DEEPSEEK_API_KEY=your_deepseek_api_key_here\n \n # Gemini API Configuration \n GEMINI_API_KEY=your_gemini_api_key_here\n ```\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\npython agent.py chat\n```\n\n### MCP Server Management\n\n#### Add a new MCP server\n```bash\n# Format: name:command:arg1:arg2:...\npython agent.py mcp add myserver:node:/path/to/server.js\npython agent.py mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n```\n\n#### List configured servers\n```bash\npython agent.py mcp list\n```\n\n#### Remove a server\n```bash\npython agent.py mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\npython agent.py ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models:\n\n```bash\npython agent.py switch-chat # DeepSeek Chat model\npython agent.py switch-reason # DeepSeek Reasoner model\npython agent.py switch-gemini # Google Gemini Flash\npython agent.py switch-gemini-pro # Google Gemini Pro\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n\nConfigure the agent through environment variables in your `.env` file:\n\n```bash\n# DeepSeek Configuration\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat\nDEEPSEEK_TEMPERATURE=0.7\n\n# Gemini Configuration\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7\n\n# Host Configuration\nHOST_NAME=mcp-agent\nLOG_LEVEL=INFO\n```\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with several built-in tools:\n\n- **File Operations**: Read, write, edit files\n- **Directory Operations**: List directories, get current path \n- **Shell Execution**: Run bash commands\n- **Web Fetching**: Download web content\n- **Todo Management**: Manage task lists\n\n### MCP Server Tools\n\nConnect external MCP servers to add functionality like:\n\n- **API Integrations**: Connect to various web APIs\n- **File System**: Advanced file operations\n- **Database Connectors**: PostgreSQL, MySQL, SQLite\n- **Development Tools**: Git operations, code analysis\n- **Custom Services**: Your own MCP-compatible tools\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch-chat` - Switch to DeepSeek Chat\n- `/switch-reason` - Switch to DeepSeek Reasoner\n- `/switch-gemini` - Switch to Gemini Flash\n- `/switch-gemini-pro` - Switch to Gemini Pro\n\n## 📚 Examples\n\n### Example: Basic File Operations\n\n```bash\npython agent.py chat\n```\n\nIn chat:\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n## 🏗️ Architecture\n\n```\n┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐\n│ CLI Interface │────│ Agent Core │────│ AI Backends │\n│ │ │ │ │ (DeepSeek/Gemini)│\n└─────────────────┘ └─────────────────┘ └─────────────────┘\n │\n │\n ┌─────────────────┐\n │ MCP Servers │\n │ │\n │ ┌─────────────┐ │\n │ │ File System │ │\n │ │ APIs │ │\n │ │ Database │ │\n │ │ Custom Tools│ │\n │ └─────────────┘ │\n └─────────────────┘\n```\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.10+\n- DeepSeek API key (for DeepSeek models)\n- Google AI Studio API key (for Gemini models)\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- API keys are stored in `.env` files (not committed to git)\n- MCP server configurations are stored locally\n- All sensitive files are excluded via `.gitignore`\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/agent/issues)\n- 💬 [Discussions](https://github.com/amranu/agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/agent/wiki)\n\n---\n\n**Happy coding with MCP Agent! 🤖✨**"}, "2da405c53f88f53255bc89335fc2882277351c58": {"t": 1785764940.8906941, "n": 6430, "h": "e1cf9be77b9f2251", "c": "# MCP Agent\n\nA powerful command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Connect multiple MCP servers to extend your AI agent with external APIs, file systems, databases, and more.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for DeepSeek and Google Gemini models\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Configuration**: Save and manage MCP server configurations\n- **Interactive Chat**: Real-time conversation with AI models and tool access\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, and todo management\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/agent.git\n cd agent\n ```\n\n2. **Install dependencies**:\n ```bash\n pip install -r requirements.txt\n ```\n\n3. **Initialize configuration**:\n ```bash\n python agent.py init\n ```\n\n4. **Configure API keys** by editing the generated `.env` file:\n ```bash\n # DeepSeek API Configuration\n DEEPSEEK_API_KEY=your_deepseek_api_key_here\n \n # Gemini API Configuration \n GEMINI_API_KEY=your_gemini_api_key_here\n ```\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\npython agent.py chat\n```\n\n### MCP Server Management\n\n#### Add a new MCP server\n```bash\n# Format: name:command:arg1:arg2:...\npython agent.py mcp add myserver:node:/path/to/server.js\npython agent.py mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n```\n\n#### List configured servers\n```bash\npython agent.py mcp list\n```\n\n#### Remove a server\n```bash\npython agent.py mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\npython agent.py ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models:\n\n```bash\npython agent.py switch-chat # DeepSeek Chat model\npython agent.py switch-reason # DeepSeek Reasoner model\npython agent.py switch-gemini # Google Gemini Flash\npython agent.py switch-gemini-pro # Google Gemini Pro\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n\nConfigure the agent through environment variables in your `.env` file:\n\n```bash\n# DeepSeek Configuration\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat\nDEEPSEEK_TEMPERATURE=0.7\n\n# Gemini Configuration\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7\n\n# Host Configuration\nHOST_NAME=mcp-agent\nLOG_LEVEL=INFO\n```\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with several built-in tools:\n\n- **File Operations**: Read, write, edit files\n- **Directory Operations**: List directories, get current path \n- **Shell Execution**: Run bash commands\n- **Web Fetching**: Download web content\n- **Todo Management**: Manage task lists\n\n### MCP Server Tools\n\nConnect external MCP servers to add functionality like:\n\n- **API Integrations**: Connect to various web APIs\n- **File System**: Advanced file operations\n- **Database Connectors**: PostgreSQL, MySQL, SQLite\n- **Development Tools**: Git operations, code analysis\n- **Custom Services**: Your own MCP-compatible tools\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch-chat` - Switch to DeepSeek Chat\n- `/switch-reason` - Switch to DeepSeek Reasoner\n- `/switch-gemini` - Switch to Gemini Flash\n- `/switch-gemini-pro` - Switch to Gemini Pro\n\n## 📚 Examples\n\n### Example: Basic File Operations\n\n```bash\npython agent.py chat\n```\n\nIn chat:\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n## 🏗️ Architecture\n\n```\n┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐\n│ CLI Interface │────│ Agent Core │────│ AI Backends │\n│ │ │ │ │ (DeepSeek/Gemini)│\n└─────────────────┘ └─────────────────┘ └─────────────────┘\n │\n │\n ┌─────────────────┐\n │ MCP Servers │\n │ │\n │ ┌─────────────┐ │\n │ │ File System │ │\n │ │ APIs │ │\n │ │ Database │ │\n │ │ Custom Tools│ │\n │ └─────────────┘ │\n └─────────────────┘\n```\n\n## 🤝 Contributing\n\nPlease read our [CONTRIBUTING.md](CONTRIBUTING.md) file for more details on our code of conduct and the process for submitting pull requests.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.8+\n- DeepSeek API key (for DeepSeek models)\n- Google AI Studio API key (for Gemini models)\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- API keys are stored in `.env` files (not committed to git)\n- MCP server configurations are stored locally\n- All sensitive files are excluded via `.gitignore`\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/agent/issues)\n- 💬 [Discussions](https://github.com/amranu/agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/agent/wiki)\n\n---\n\n**Happy coding with MCP Agent! 🤖✨**"}, "980d12cd4fa991aec7f2f7ce0e22688209354f0e": {"t": 1785764942.3608615, "n": 6287, "h": "bcd13d34f3d43385", "c": "# MCP Agent\n\nA powerful command-line interface for interacting with AI models enhanced with Model Context Protocol (MCP) tool integration. Connect multiple MCP servers to extend your AI agent with external APIs, file systems, databases, and more.\n\n## 🚀 Features\n\n- **Multiple AI Backends**: Support for DeepSeek and Google Gemini models\n- **MCP Server Integration**: Connect to multiple MCP servers for extended functionality\n- **Persistent Configuration**: Save and manage MCP server configurations\n- **Interactive Chat**: Real-time conversation with AI models and tool access\n- **Command-Line Tools**: Manage MCP servers and query models directly\n- **Built-in Tools**: File operations, bash execution, web fetching, and todo management\n\n## 📦 Installation\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/amranu/agent.git\n cd agent\n ```\n\n2. **Install dependencies**:\n ```bash\n pip install -r requirements.txt\n ```\n\n3. **Initialize configuration**:\n ```bash\n python agent.py init\n ```\n\n4. **Configure API keys** by editing the generated `.env` file:\n ```bash\n # DeepSeek API Configuration\n DEEPSEEK_API_KEY=your_deepseek_api_key_here\n \n # Gemini API Configuration \n GEMINI_API_KEY=your_gemini_api_key_here\n ```\n\n## 🛠️ Usage\n\n### Interactive Chat\n\nStart an interactive chat session with your configured AI model and MCP tools:\n\n```bash\npython agent.py chat\n```\n\n### MCP Server Management\n\n#### Add a new MCP server\n```bash\n# Format: name:command:arg1:arg2:...\npython agent.py mcp add myserver:node:/path/to/server.js\npython agent.py mcp add filesystem:python:-m:mcp.server.stdio:filesystem:--root:.\n```\n\n#### List configured servers\n```bash\npython agent.py mcp list\n```\n\n#### Remove a server\n```bash\npython agent.py mcp remove myserver\n```\n\n### Single Query\n\nAsk a one-time question without entering interactive mode:\n\n```bash\npython agent.py ask \"What's the weather like today?\"\n```\n\n### Model Switching\n\nSwitch between different AI models:\n\n```bash\npython agent.py switch-chat # DeepSeek Chat model\npython agent.py switch-reason # DeepSeek Reasoner model\npython agent.py switch-gemini # Google Gemini Flash\npython agent.py switch-gemini-pro # Google Gemini Pro\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n\nConfigure the agent through environment variables in your `.env` file:\n\n```bash\n# DeepSeek Configuration\nDEEPSEEK_API_KEY=your_key_here\nDEEPSEEK_MODEL=deepseek-chat\nDEEPSEEK_TEMPERATURE=0.7\n\n# Gemini Configuration\nGEMINI_API_KEY=your_key_here\nGEMINI_MODEL=gemini-2.5-flash\nGEMINI_TEMPERATURE=0.7\n\n# Host Configuration\nHOST_NAME=mcp-agent\nLOG_LEVEL=INFO\n```\n\n## 🎯 Available Tools\n\n### Built-in Tools\n\nThe agent comes with several built-in tools:\n\n- **File Operations**: Read, write, edit files\n- **Directory Operations**: List directories, get current path \n- **Shell Execution**: Run bash commands\n- **Web Fetching**: Download web content\n- **Todo Management**: Manage task lists\n\n### MCP Server Tools\n\nConnect external MCP servers to add functionality like:\n\n- **API Integrations**: Connect to various web APIs\n- **File System**: Advanced file operations\n- **Database Connectors**: PostgreSQL, MySQL, SQLite\n- **Development Tools**: Git operations, code analysis\n- **Custom Services**: Your own MCP-compatible tools\n\n## 🔍 Interactive Chat Commands\n\nWithin the interactive chat, use these slash commands:\n\n- `/help` - Show available commands\n- `/tools` - List all available tools\n- `/clear` - Clear conversation history\n- `/model` - Show current model\n- `/tokens` - Show token usage\n- `/compact` - Compact conversation history\n- `/switch-chat` - Switch to DeepSeek Chat\n- `/switch-reason` - Switch to DeepSeek Reasoner\n- `/switch-gemini` - Switch to Gemini Flash\n- `/switch-gemini-pro` - Switch to Gemini Pro\n\n## 📚 Examples\n\n### Example: Basic File Operations\n\n```bash\npython agent.py chat\n```\n\nIn chat:\n```\nYou: List all files in this directory\nYou: Read the contents of agent.py\nYou: Create a new file called hello.py with a simple function\n```\n\n### Example: System Operations\n\nIn chat:\n```\nYou: Show me the current directory\nYou: Run \"git status\" to check repository status\nYou: What's the disk usage of this folder?\n```\n\n## 🏗️ Architecture\n\n```\n┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐\n│ CLI Interface │────│ Agent Core │────│ AI Backends │\n│ │ │ │ │ (DeepSeek/Gemini)│\n└─────────────────┘ └─────────────────┘ └─────────────────┘\n │\n │\n ┌─────────────────┐\n │ MCP Servers │\n │ │\n │ ┌─────────────┐ │\n │ │ File System │ │\n │ │ APIs │ │\n │ │ Database │ │\n │ │ Custom Tools│ │\n │ └─────────────┘ │\n └─────────────────┘\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit your changes: `git commit -m 'Add feature'`\n6. Push to the branch: `git push origin feature-name`\n7. Submit a pull request\n\n## 📋 Requirements\n\n- Python 3.8+\n- DeepSeek API key (for DeepSeek models)\n- Google AI Studio API key (for Gemini models)\n- Node.js (for MCP servers that require it)\n\n## 🔒 Security\n\n- API keys are stored in `.env` files (not committed to git)\n- MCP server configurations are stored locally\n- All sensitive files are excluded via `.gitignore`\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the extensible tool integration framework\n- [DeepSeek](https://www.deepseek.com/) for the powerful reasoning models\n- [Google AI](https://ai.google.dev/) for Gemini model access\n- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP client implementation\n\n## 📞 Support\n\n- 🐛 [Report Issues](https://github.com/amranu/agent/issues)\n- 💬 [Discussions](https://github.com/amranu/agent/discussions)\n- 📖 [Wiki](https://github.com/amranu/agent/wiki)\n\n---\n\n**Happy coding with MCP Agent! 🤖✨**"}}}} |