{"id":27772101,"url":"https://github.com/keli-wen/mcp_chatbot","last_synced_at":"2025-04-29T23:03:59.903Z","repository":{"id":282850110,"uuid":"949816048","full_name":"keli-wen/mcp_chatbot","owner":"keli-wen","description":"A chatbot implementation compatible with MCP (terminal / streamlit supported)","archived":false,"fork":false,"pushed_at":"2025-04-29T08:23:41.000Z","size":8715,"stargazers_count":97,"open_issues_count":3,"forks_count":19,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-29T23:03:52.623Z","etag":null,"topics":["chatbot","mcp","mcp-host","mcp-server","python","streamlit"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/keli-wen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-03-17T07:25:07.000Z","updated_at":"2025-04-29T12:28:53.000Z","dependencies_parsed_at":"2025-03-17T09:49:20.441Z","dependency_job_id":null,"html_url":"https://github.com/keli-wen/mcp_chatbot","commit_stats":null,"previous_names":["keli-wen/mcp_chatbot"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keli-wen%2Fmcp_chatbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keli-wen%2Fmcp_chatbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keli-wen%2Fmcp_chatbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keli-wen%2Fmcp_chatbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/keli-wen","download_url":"https://codeload.github.com/keli-wen/mcp_chatbot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251596699,"owners_count":21615018,"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":["chatbot","mcp","mcp-host","mcp-server","python","streamlit"],"created_at":"2025-04-29T23:03:59.477Z","updated_at":"2025-04-29T23:03:59.895Z","avatar_url":"https://github.com/keli-wen.png","language":"Python","funding_links":[],"categories":["📚 Projects (1974 total)","MCP Frameworks and libraries"],"sub_categories":["MCP Servers","Python"],"readme":"# MCPChatbot Example\n\n![MCP Chatbot](assets/mcp_chatbot_logo.png)\n\nThis project demonstrates how to integrate the Model Context Protocol (MCP) with customized LLM (e.g. Qwen), creating a powerful chatbot that can interact with various tools through MCP servers. The implementation showcases the flexibility of MCP by enabling LLMs to use external tools seamlessly.\n\n\u003e [!TIP]\n\u003e For Chinese version, please refer to [README_ZH.md](README_ZH.md).\n\n## Overview\n\n**Chatbot Streamlit Example**\n\n\u003cimg src=\"assets/mcp_chatbot_streamlit_demo_low.gif\" width=\"800\"\u003e\n\n**Workflow Tracer Example**\n\n\u003cimg src=\"assets/single_prompt_demo.png\" width=\"800\"\u003e\n\n- 🚩 Update (2025-04-11):\n  - Added chatbot streamlit example.\n- 🚩 Update (2025-04-10): \n  - More complex LLM response parsing, supporting multiple MCP tool calls and multiple chat iterations.\n  - Added single prompt examples with both regular and streaming modes.\n  - Added interactive terminal chatbot examples.\n\nThis project includes:\n\n- Simple/Complex CLI chatbot interface\n- Integration with some builtin MCP Server like (Markdown processing tools)\n- Support for customized LLM (e.g. Qwen) and Ollama\n- Example scripts for single prompt processing in both regular and streaming modes\n- Interactive terminal chatbot with regular and streaming response modes\n\n## Requirements\n\n- Python 3.10+\n- Dependencies (automatically installed via requirements):\n  - python-dotenv\n  - mcp[cli]\n  - openai\n  - colorama\n\n## Installation\n\n1. **Clone the repository:**\n\n   ```bash\n   git clone git@github.com:keli-wen/mcp_chatbot.git\n   cd mcp_chatbot\n   ```\n\n2. **Set up a virtual environment (recommended):**\n\n   ```bash\n   cd folder\n   \n   # Install uv if you don't have it already\n   pip install uv\n\n   # Create a virtual environment and install dependencies\n   uv venv .venv --python=3.10\n\n   # Activate the virtual environment\n   # For macOS/Linux\n   source .venv/bin/activate\n   # For Windows\n   .venv\\Scripts\\activate\n\n   # Deactivate the virtual environment\n   deactivate\n   ```\n\n3. **Install dependencies:**\n\n   ```bash\n   pip install -r requirements.txt\n   # or use uv for faster installation\n   uv pip install -r requirements.txt\n   ```\n\n4. **Configure your environment:**\n   - Copy the `.env.example` file to `.env`:\n\n     ```bash\n     cp .env.example .env\n     ```\n\n   - Edit the `.env` file to add your Qwen API key (just for demo, you can use any LLM API key, remember to set the base_url and api_key in the .env file) and set the paths:\n\n     ```\n     LLM_MODEL_NAME=your_llm_model_name_here\n     LLM_BASE_URL=your_llm_base_url_here\n     LLM_API_KEY=your_llm_api_key_here\n     OLLAMA_MODEL_NAME=your_ollama_model_name_here\n     OLLAMA_BASE_URL=your_ollama_base_url_here\n     MARKDOWN_FOLDER_PATH=/path/to/your/markdown/folder\n     RESULT_FOLDER_PATH=/path/to/your/result/folder\n     ```\n\n## Important Configuration Notes ⚠️\n\nBefore running the application, you need to modify the following:\n\n1. **MCP Server Configuration**:\n   Edit `mcp_servers/servers_config.json` to match your local setup:\n\n   ```json\n   {\n       \"mcpServers\": {\n           \"markdown_processor\": {\n               \"command\": \"/path/to/your/uv\",\n               \"args\": [\n                   \"--directory\",\n                   \"/path/to/your/project/mcp_servers\",\n                   \"run\",\n                   \"markdown_processor.py\"\n               ]\n           }\n       }\n   }\n   ```\n\n   Replace `/path/to/your/uv` with the actual path to your uv executable. **You can use `which uv` to get the path**.\n   Replace `/path/to/your/project/mcp_servers` with the absolute path to the mcp_servers directory in your project.\n\n2. **Environment Variables**:\n   Make sure to set proper paths in your `.env` file:\n\n   ```\n   MARKDOWN_FOLDER_PATH=\"/path/to/your/markdown/folder\"\n   RESULT_FOLDER_PATH=\"/path/to/your/result/folder\"\n   ```\n\n   The application will validate these paths and throw an error if they contain placeholder values.\n\nYou can run the following command to check your configuration:\n\n```bash\nbash scripts/check.sh\n```\n\n## Usage\n\n### Unit Test\n\nYou can run the following command to run the unit test:\n\n```bash\nbash scripts/unittest.sh\n```\n\n### Examples\n\n#### Single Prompt Examples\n\nThe project includes two single prompt examples:\n\n1. **Regular Mode**: Process a single prompt and display the complete response\n   ```bash\n   python example/single_prompt/single_prompt.py\n   ```\n\n2. **Streaming Mode**: Process a single prompt with real-time streaming output\n   ```bash\n   python example/single_prompt/single_prompt_stream.py\n   ```\n\nBoth examples accept an optional `--llm` parameter to specify which LLM provider to use:\n```bash\npython example/single_prompt/single_prompt.py --llm=ollama\n```\n\n\u003e [!NOTE]\n\u003e For more details, see the [Single Prompt Example README](example/single_prompt/README.md).\n\n#### Terminal Chatbot Examples\n\nThe project includes two interactive terminal chatbot examples:\n\n1. **Regular Mode**: Interactive terminal chat with complete responses\n   ```bash\n   python example/chatbot_terminal/chatbot_terminal.py\n   ```\n\n2. **Streaming Mode**: Interactive terminal chat with streaming responses\n   ```bash\n   python example/chatbot_terminal/chatbot_terminal_stream.py\n   ```\n\nBoth examples accept an optional `--llm` parameter to specify which LLM provider to use:\n```bash\npython example/chatbot_terminal/chatbot_terminal.py --llm=ollama\n```\n\n\u003e [!NOTE]\n\u003e For more details, see the [Terminal Chatbot Example README](example/chatbot_terminal/README.md).\n\n#### Streamlit Web Chatbot Example\n\nThe project includes an interactive web-based chatbot example using Streamlit:\n\n```bash\nstreamlit run example/chatbot_streamlit/app.py\n```\n\nThis example features:\n- Interactive chat interface.\n- Real-time streaming responses.\n- Detailed MCP tool workflow visualization.\n- Configurable LLM settings (OpenAI/Ollama) and MCP tool display via the sidebar.\n\n![MCP Chatbot Streamlit Demo](assets/chatbot_streamlit_demo_light.png)\n\n\u003e [!NOTE]\n\u003e For more details, see the [Streamlit Chatbot Example README](example/chatbot_streamlit/README.md).\n\n\u003c/details\u003e\n\n## Project Structure\n\n- `mcp_chatbot/`: Core library code\n  - `chat/`: Chat session management\n  - `config/`: Configuration handling\n  - `llm/`: LLM client implementation\n  - `mcp/`: MCP client and tool integration\n  - `utils/`: Utility functions (e.g. `WorkflowTrace` and `StreamPrinter`)\n- `mcp_servers/`: Custom MCP servers implementation\n  - `markdown_processor.py`: Server for processing Markdown files\n  - `servers_config.json`: Configuration for MCP servers\n- `data-example/`: Example Markdown files for testing\n- `example/`: Example scripts for different use cases\n  - `single_prompt/`: Single prompt processing examples (regular and streaming)\n  - `chatbot_terminal/`: Interactive terminal chatbot examples (regular and streaming)\n  - `chatbot_streamlit/`: Interactive web chatbot example using Streamlit\n\n## Extending the Project\n\nYou can extend this project by:\n\n1. Adding new MCP servers in the `mcp_servers/` directory\n2. Updating the `servers_config.json` to include your new servers\n3. Implementing new functionalities in the existing servers\n4. Creating new examples based on the provided templates\n\n## Troubleshooting\n\n- **Path Issues**: Ensure all paths in the configuration files are absolute paths appropriate for your system\n- **MCP Server Errors**: Make sure the tools are properly installed and configured\n- **API Key Errors**: Verify your API key is correctly set in the `.env` file\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeli-wen%2Fmcp_chatbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkeli-wen%2Fmcp_chatbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeli-wen%2Fmcp_chatbot/lists"}