{"id":22889318,"url":"https://github.com/3choff/mcp-chatbot","last_synced_at":"2025-08-17T09:32:57.033Z","repository":{"id":266729476,"uuid":"899179080","full_name":"3choff/mcp-chatbot","owner":"3choff","description":"A simple CLI chatbot that demonstrates the integration of the Model Context Protocol (MCP).","archived":false,"fork":false,"pushed_at":"2024-12-05T20:15:04.000Z","size":12,"stargazers_count":14,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-13T21:30:20.547Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/3choff.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":"3choff","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"custom":null}},"created_at":"2024-12-05T19:07:56.000Z","updated_at":"2024-12-13T01:58:18.000Z","dependencies_parsed_at":"2024-12-05T20:33:41.739Z","dependency_job_id":null,"html_url":"https://github.com/3choff/mcp-chatbot","commit_stats":null,"previous_names":["3choff/mcp-chatbot"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3choff%2Fmcp-chatbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3choff%2Fmcp-chatbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3choff%2Fmcp-chatbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3choff%2Fmcp-chatbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/3choff","download_url":"https://codeload.github.com/3choff/mcp-chatbot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230113664,"owners_count":18175221,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-13T21:28:09.232Z","updated_at":"2024-12-17T12:11:59.703Z","avatar_url":"https://github.com/3choff.png","language":"Python","funding_links":["https://ko-fi.com/3choff"],"categories":["MCP Clients","🔌 Integration Tools","📚 Projects (1974 total)","Clients","🤖 AI/ML","Other Tools and Integrations","クライアント","Table of Contents","MCP Servers \u0026 Protocol"],"sub_categories":["Weather","Clients \u0026 Interfaces","MCP Servers","🎧 \u003ca name=\"text-to-speech\"\u003e\u003c/a\u003eテキスト読み上げ","🧪 Development \u0026 Testing Tools","Command Line","CLI Tools"],"readme":"# MCP Chatbot\n\nThis chatbot example demonstrates how to integrate the Model Context Protocol (MCP) into a simple CLI chatbot. The implementation showcases MCP's flexibility by supporting multiple tools through MCP servers and is compatible with any LLM provider that follows OpenAI API standards.\n\nIf you find this project helpful, don’t forget to ⭐ star the [repository](https://github.com/3choff/mcp-chatbot) or buy me a ☕ [coffee](https://ko-fi.com/3choff).\n\n## Key Features\n\n- **LLM Provider Flexibility**: Works with any LLM that follows OpenAI API standards (tested with Llama 3.2 90b on Groq and GPT-4o mini on GitHub Marketplace).\n- **Dynamic Tool Integration**: Tools are declared in the system prompt, ensuring maximum compatibility across different LLMs.\n- **Server Configuration**: Supports multiple MCP servers through a simple JSON configuration file like the Claude Desktop App.\n\n## Requirements\n\n- Python 3.10\n- `python-dotenv`\n- `requests`\n- `mcp`\n- `uvicorn`\n\n## Installation\n\n1. **Clone the repository:**\n\n   ```bash\n   git clone https://github.com/3choff/mcp-chatbot.git\n   cd mcp-chatbot\n   ```\n\n2. **Install the dependencies:**\n\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. **Set up environment variables:**\n\n   Create a `.env` file in the root directory and add your API key:\n\n   ```plaintext\n   LLM_API_KEY=your_api_key_here\n   ```\n\n4. **Configure servers:**\n\n   The `servers_config.json` follows the same structure as Claude Desktop, allowing for easy integration of multiple servers. \n   Here's an example:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"sqlite\": {\n         \"command\": \"uvx\",\n         \"args\": [\"mcp-server-sqlite\", \"--db-path\", \"./test.db\"]\n       },\n       \"puppeteer\": {\n         \"command\": \"npx\",\n         \"args\": [\"-y\", \"@modelcontextprotocol/server-puppeteer\"]\n       }\n     }\n   }\n   ```\n   Environment variables are supported as well. Pass them as you would with the Claude Desktop App.\n\n   Example:\n   ```json\n   {\n     \"mcpServers\": {\n       \"server_name\": {\n         \"command\": \"uvx\",\n         \"args\": [\"mcp-server-name\", \"--additional-args\"],\n         \"env\": {\n           \"API_KEY\": \"your_api_key_here\"\n         }\n       }\n     }\n   }\n   ```\n\n## Usage\n\n1. **Run the client:**\n\n   ```bash\n   python main.py\n   ```\n\n2. **Interact with the assistant:**\n   \n   The assistant will automatically detect available tools and can respond to queries based on the tools provided by the configured servers.\n\n3. **Exit the session:**\n\n   Type `quit` or `exit` to end the session.\n\n## Architecture\n\n- **Tool Discovery**: Tools are automatically discovered from configured servers.\n- **System Prompt**: Tools are dynamically included in the system prompt, allowing the LLM to understand available capabilities.\n- **Server Integration**: Supports any MCP-compatible server, tested with various server implementations including Uvicorn and Node.js.\n\n### Class Structure\n- **Configuration**: Manages environment variables and server configurations\n- **Server**: Handles MCP server initialization, tool discovery, and execution\n- **Tool**: Represents individual tools with their properties and formatting\n- **LLMClient**: Manages communication with the LLM provider\n- **ChatSession**: Orchestrates the interaction between user, LLM, and tools\n\n### Logic Flow\n\n```mermaid\nflowchart TD\n    A[Start] --\u003e B[Load Configuration]\n    B --\u003e C[Initialize Servers]\n    C --\u003e D[Discover Tools]\n    D --\u003e E[Format Tools for LLM]\n    E --\u003e F[Wait for User Input]\n    \n    F --\u003e G{User Input}\n    G --\u003e H[Send Input to LLM]\n    H --\u003e I{LLM Decision}\n    I --\u003e|Tool Call| J[Execute Tool]\n    I --\u003e|Direct Response| K[Return Response to User]\n    \n    J --\u003e L[Return Tool Result]\n    L --\u003e M[Send Result to LLM]\n    M --\u003e N[LLM Interprets Result]\n    N --\u003e O[Present Final Response to User]\n    \n    K --\u003e O\n    O --\u003e F\n```\n\n1. **Initialization**:\n   - Configuration loads environment variables and server settings\n   - Servers are initialized with their respective tools\n   - Tools are discovered and formatted for LLM understanding\n\n2. **Runtime Flow**:\n   - User input is received\n   - Input is sent to LLM with context of available tools\n   - LLM response is parsed:\n     - If it's a tool call → execute tool and return result\n     - If it's a direct response → return to user\n   - Tool results are sent back to LLM for interpretation\n   - Final response is presented to user\n\n3. **Tool Integration**:\n   - Tools are dynamically discovered from MCP servers\n   - Tool descriptions are automatically included in system prompt\n   - Tool execution is handled through standardized MCP protocol\n\n## Contributing\n\nFeedback and contributions are welcome. If you encounter any issues or have suggestions for improvements, please create a new [issue](https://github.com/3choff/mcp-chatbot/issues) on the GitHub repository.\n\nIf you'd like to contribute to the development of the project, feel free to submit a pull request with your changes.\n\n## License\n\nThis project is licensed under the [MIT License](https://github.com/3choff/mcp-chatbot/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F3choff%2Fmcp-chatbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F3choff%2Fmcp-chatbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F3choff%2Fmcp-chatbot/lists"}