mseep-mcp-simple-chatbot 0.1.1__tar.gz

mseep_mcp_simple_chatbot-0.1.1/.env.example

@@ -0,0 +1,9 @@
+LLM_API_KEY="your_llm_api_key_here"
+LLM_BASE_URL="your_llm_base_url_here"
+LLM_MODEL_NAME="your_llm_model_name_here"
+
+OLLAMA_MODEL_NAME="your_ollama_model_name_here"
+OLLAMA_BASE_URL="your_ollama_base_url_here"
+
+MARKDOWN_FOLDER_PATH="/path/to/your/markdown/folder"
+RESULT_FOLDER_PATH="/path/to/your/result/folder"

mseep_mcp_simple_chatbot-0.1.1/.gitai/config.yaml

@@ -0,0 +1,35 @@
+llm:
+    default:
+        provider: openai
+        model: gpt-4o-mini
+        # apiKey: 'sk-...' # Highly recommended to set via environment variable, not hard-coded in the config file
+        apiKeyEnvVar: 'OPENAI_API_KEY' # Set it in your environment variables or .env file
+        # baseUrl: 'your-custom-base-url'
+        baseUrlEnvVar: 'OPENAI_BASE_URL' # Set it in your environment variables or .env file
+        ollamaBaseUrl: 'http://localhost:11434' # Only needed when provider is ollama
+        temperature: 0.7
+
+    commands: # Can override the default settings for each command
+        commit:
+            provider: openai
+            model: gpt-4o-mini
+            apiKeyEnvVar: 'OPENAI_API_KEY'
+            baseUrlEnvVar: 'OPENAI_BASE_URL'
+        pr:
+            provider: deepseek    # Can be changed to 'deepseek' or 'ollama' ...
+            model: deepseek-chat
+            apiKeyEnvVar: 'DEEPSEEK_API_KEY'
+            baseUrlEnvVar: 'DEEPSEEK_BASE_URL'
+            temperature: 0.4
+
+commit:
+    suggestions: 3
+    prompt_template: './prompts/commit_prompt.txt'
+
+pr:
+    base_branch: main          # When user doesn't pass --target
+    include_file_tree: true    # Whether to include the file tree generated by ls-files
+    include_unstaged: false    # Corresponds to --unstaged
+    max_lines_per_file: 300    # Diff truncation threshold
+    warn_on_conflict: true     # Whether to interrupt when merge conflicts are detected
+    prompt_template: ./prompts/pr_prompt.txt

mseep_mcp_simple_chatbot-0.1.1/.gitai/prompts/commit_prompt.txt

@@ -0,0 +1,51 @@
+You are an AI assistant specialized in crafting Git commit messages according to the Conventional Commits specification (v1.0.0). Your task is to generate {{ suggestions }} distinct commit messages based on the provided file diff.
+
+**Conventional Commits Structure:**
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+
+**Key Types:**
+- `fix`: A bug fix (correlates with PATCH in SemVer).
+- `feat`: A new feature (correlates with MINOR in SemVer).
+- Other allowed types (non-exhaustive): `build`, `chore`, `ci`, `docs`, `style`, `refactor`, `perf`, `test`.
+
+**Breaking Changes:**
+- Indicated by appending `!` to the type/scope (e.g., `feat!:` or `refactor(api)!:`).
+- OR by including a `BREAKING CHANGE:` footer.
+- If a breaking change is present, ensure the `!` marker or the footer is included.
+
+**Scope:**
+- Optional, enclosed in parentheses, providing context (e.g., `feat(parser): ...`).
+- Infer a relevant scope if possible from the file paths or changes. If no specific scope is clear, omit it.
+
+**Description:**
+- Concise summary of the change, in the imperative mood (e.g., "add feature" not "added feature").
+- Keep the description short, ideally under 50 characters.
+
+**Body & Footer (Optional for this task):**
+- For this task, focus on generating the header line (<type>[scope]: <description>). Do NOT include a body or footers unless it's a `BREAKING CHANGE:` footer, which should be part of the description if you choose that method for indicating a breaking change and it's brief. Otherwise, prefer the `!` marker.
+
+**IMPORTANT - Output Format:**
+- Your ENTIRE response must be ONLY a JSON array of objects, with NO wrapping object.
+- DO NOT wrap the array in a JSON object with a "suggestions" key.
+- Each object in the array MUST have a "message" property containing the commit message.
+- The array must contain exactly {{ suggestions }} objects.
+- DO NOT include any explanations, markdown, or additional text before or after the JSON array.
+- DO NOT use triple backticks to format the JSON.
+
+**CORRECT format:**
+[
+  { "message": "feat(api): add user profile endpoint" },
+  { "message": "docs: update API documentation for user profile" }
+]
+
+**INCORRECT format (DO NOT USE):**
+{
+  "suggestions": [
+    { "message": "feat(api): add user profile endpoint" },
+    { "message": "docs: update API documentation for user profile" }
+  ]
+}

mseep_mcp_simple_chatbot-0.1.1/.gitai/prompts/pr_prompt.txt

@@ -0,0 +1,56 @@
+You are an expert developer writing a Pull-Request description for code reviewers.
+
+##############################
+##        INPUT DATA        ##
+##############################
+
+<<<DIFF>>>
+{{ diff }}
+<<<END DIFF>>>
+
+{{#if tree}}
+<<<FILE_TREE>>>
+{{ tree }}
+<<<END FILE_TREE>>>
+{{/if}}
+
+Branch  : {{ branch }}
+Target  : {{ target }}
+
+{{#if commits}}
+<<<COMMITS>>>
+{{ commits }}
+<<<END COMMITS>>>
+{{/if}}
+
+##############################
+##          TASK            ##
+##############################
+
+Generate **one** PR draft that:
+
+1. Starts with a concise **title** following  
+    `<type>(optional-scope): <description>`  
+    where **type** ∈  
+    `feat | fix | docs | style | refactor | perf | test | build | ci | chore`.
+
+2. Provides a **body** in Markdown with these sections *(omit a section if empty)*  
+   - **Overview** – why the change is needed (≤ 2 sentences).  
+   - **Key Changes** – bullet list of the most important code areas / commits.  
+   - **Implementation Notes** – notable design decisions.  
+   - **Migration / Checklist** – steps for users or follow-ups (optional).
+
+Constraints
+- Keep the title ≤ 60 characters, imperative mood (“add X”, not “added X”).
+- Summarise; do **not** dump the entire diff again.
+
+##############################
+##        OUTPUT ONLY       ##
+##############################
+
+Return **exactly** one JSON object **without** markdown fences or extra text:
+
+{
+    "title": "<generated-title>",
+    "body": "<markdown-body>"
+}

mseep_mcp_simple_chatbot-0.1.1/.gitignore

@@ -0,0 +1,5 @@
+# Local environment variables
+.env
+__pycache__
+.venv
+.gitai/pr_docs

mseep_mcp_simple_chatbot-0.1.1/.python-version

@@ -0,0 +1 @@
+3.10

mseep_mcp_simple_chatbot-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 mcp_chatbot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mseep_mcp_simple_chatbot-0.1.1/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: mseep-mcp-simple-chatbot
+Version: 0.1.1
+Summary: A simple CLI chatbot using the Model Context Protocol (MCP)
+Author-email: mseep <support@skydeck.ai>
+License: MIT
+License-File: LICENSE
+Keywords: chatbot,cli,llm,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: openai>=1.66.3
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: streamlit>=1.43.2
+Requires-Dist: uvicorn>=0.32.1
+Description-Content-Type: text/plain
+
+Package managed by MseeP.ai

mseep_mcp_simple_chatbot-0.1.1/README.md

@@ -0,0 +1,268 @@
+# MCPChatbot Example
+
+![MCP Chatbot](assets/mcp_chatbot_logo.png)
+
+This 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.
+
+> [!TIP]
+> For Chinese version, please refer to [README_ZH.md](README_ZH.md).
+
+## Overview
+
+**Chatbot Streamlit Example**
+
+<img src="assets/mcp_chatbot_streamlit_demo_low.gif" width="800">
+
+**Workflow Tracer Example**
+
+<img src="assets/single_prompt_demo.png" width="800">
+
+- 🚩 Update (2025-04-11):
+  - Added chatbot streamlit example.
+- 🚩 Update (2025-04-10): 
+  - More complex LLM response parsing, supporting multiple MCP tool calls and multiple chat iterations.
+  - Added single prompt examples with both regular and streaming modes.
+  - Added interactive terminal chatbot examples.
+
+This project includes:
+
+- Simple/Complex CLI chatbot interface
+- Integration with some builtin MCP Server like (Markdown processing tools)
+- Support for customized LLM (e.g. Qwen) and Ollama
+- Example scripts for single prompt processing in both regular and streaming modes
+- Interactive terminal chatbot with regular and streaming response modes
+
+## Requirements
+
+- Python 3.10+
+- Dependencies (automatically installed via requirements):
+  - python-dotenv
+  - mcp[cli]
+  - openai
+  - colorama
+
+## Installation
+
+1. **Clone the repository:**
+
+   ```bash
+   git clone git@github.com:keli-wen/mcp_chatbot.git
+   cd mcp_chatbot
+   ```
+
+2. **Set up a virtual environment (recommended):**
+
+   ```bash
+   cd folder
+   
+   # Install uv if you don't have it already
+   pip install uv
+
+   # Create a virtual environment and install dependencies
+   uv venv .venv --python=3.10
+
+   # Activate the virtual environment
+   # For macOS/Linux
+   source .venv/bin/activate
+   # For Windows
+   .venv\Scripts\activate
+
+   # Deactivate the virtual environment
+   deactivate
+   ```
+
+3. **Install dependencies:**
+
+   ```bash
+   pip install -r requirements.txt
+   # or use uv for faster installation
+   uv pip install -r requirements.txt
+   ```
+
+4. **Configure your environment:**
+   - Copy the `.env.example` file to `.env`:
+
+     ```bash
+     cp .env.example .env
+     ```
+
+   - 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:
+
+     ```
+     LLM_MODEL_NAME=your_llm_model_name_here
+     LLM_BASE_URL=your_llm_base_url_here
+     LLM_API_KEY=your_llm_api_key_here
+     OLLAMA_MODEL_NAME=your_ollama_model_name_here
+     OLLAMA_BASE_URL=your_ollama_base_url_here
+     MARKDOWN_FOLDER_PATH=/path/to/your/markdown/folder
+     RESULT_FOLDER_PATH=/path/to/your/result/folder
+     ```
+
+## Important Configuration Notes ⚠️
+
+Before running the application, you need to modify the following:
+
+1. **MCP Server Configuration**:
+   Edit `mcp_servers/servers_config.json` to match your local setup:
+
+   ```json
+   {
+       "mcpServers": {
+           "markdown_processor": {
+               "command": "/path/to/your/uv",
+               "args": [
+                   "--directory",
+                   "/path/to/your/project/mcp_servers",
+                   "run",
+                   "markdown_processor.py"
+               ]
+           }
+       }
+   }
+   ```
+
+   Replace `/path/to/your/uv` with the actual path to your uv executable. **You can use `which uv` to get the path**.
+   Replace `/path/to/your/project/mcp_servers` with the absolute path to the mcp_servers directory in your project. (For **Windows** users, you can take a look at the example in the [Troubleshooting](#troubleshooting) section)
+
+2. **Environment Variables**:
+   Make sure to set proper paths in your `.env` file:
+
+   ```
+   MARKDOWN_FOLDER_PATH="/path/to/your/markdown/folder"
+   RESULT_FOLDER_PATH="/path/to/your/result/folder"
+   ```
+
+   The application will validate these paths and throw an error if they contain placeholder values.
+
+You can run the following command to check your configuration:
+
+```bash
+bash scripts/check.sh
+```
+
+## Usage
+
+### Unit Test
+
+You can run the following command to run the unit test:
+
+```bash
+bash scripts/unittest.sh
+```
+
+### Examples
+
+#### Single Prompt Examples
+
+The project includes two single prompt examples:
+
+1. **Regular Mode**: Process a single prompt and display the complete response
+   ```bash
+   python example/single_prompt/single_prompt.py
+   ```
+
+2. **Streaming Mode**: Process a single prompt with real-time streaming output
+   ```bash
+   python example/single_prompt/single_prompt_stream.py
+   ```
+
+Both examples accept an optional `--llm` parameter to specify which LLM provider to use:
+```bash
+python example/single_prompt/single_prompt.py --llm=ollama
+```
+
+> [!NOTE]
+> For more details, see the [Single Prompt Example README](example/single_prompt/README.md).
+
+#### Terminal Chatbot Examples
+
+The project includes two interactive terminal chatbot examples:
+
+1. **Regular Mode**: Interactive terminal chat with complete responses
+   ```bash
+   python example/chatbot_terminal/chatbot_terminal.py
+   ```
+
+2. **Streaming Mode**: Interactive terminal chat with streaming responses
+   ```bash
+   python example/chatbot_terminal/chatbot_terminal_stream.py
+   ```
+
+Both examples accept an optional `--llm` parameter to specify which LLM provider to use:
+```bash
+python example/chatbot_terminal/chatbot_terminal.py --llm=ollama
+```
+
+> [!NOTE]
+> For more details, see the [Terminal Chatbot Example README](example/chatbot_terminal/README.md).
+
+#### Streamlit Web Chatbot Example
+
+The project includes an interactive web-based chatbot example using Streamlit:
+
+```bash
+streamlit run example/chatbot_streamlit/app.py
+```
+
+This example features:
+- Interactive chat interface.
+- Real-time streaming responses.
+- Detailed MCP tool workflow visualization.
+- Configurable LLM settings (OpenAI/Ollama) and MCP tool display via the sidebar.
+
+![MCP Chatbot Streamlit Demo](assets/chatbot_streamlit_demo_light.png)
+
+> [!NOTE]
+> For more details, see the [Streamlit Chatbot Example README](example/chatbot_streamlit/README.md).
+
+</details>
+
+## Project Structure
+
+- `mcp_chatbot/`: Core library code
+  - `chat/`: Chat session management
+  - `config/`: Configuration handling
+  - `llm/`: LLM client implementation
+  - `mcp/`: MCP client and tool integration
+  - `utils/`: Utility functions (e.g. `WorkflowTrace` and `StreamPrinter`)
+- `mcp_servers/`: Custom MCP servers implementation
+  - `markdown_processor.py`: Server for processing Markdown files
+  - `servers_config.json`: Configuration for MCP servers
+- `data-example/`: Example Markdown files for testing
+- `example/`: Example scripts for different use cases
+  - `single_prompt/`: Single prompt processing examples (regular and streaming)
+  - `chatbot_terminal/`: Interactive terminal chatbot examples (regular and streaming)
+  - `chatbot_streamlit/`: Interactive web chatbot example using Streamlit
+
+## Extending the Project
+
+You can extend this project by:
+
+1. Adding new MCP servers in the `mcp_servers/` directory
+2. Updating the `servers_config.json` to include your new servers
+3. Implementing new functionalities in the existing servers
+4. Creating new examples based on the provided templates
+
+## Troubleshooting
+
+For Windows users, you can take the following `servers_config.json` as an example:
+
+```json
+{
+    "mcpServers": {
+        "markdown_processor": {
+            "command": "C:\\Users\\13430\\.local\\bin\\uv.exe",
+            "args": [
+                "--directory",
+                "C:\\Users\\13430\\mcp_chatbot\\mcp_servers",
+                "run", 
+                "markdown_processor.py"
+            ]
+        }
+    }
+}
+```
+
+- **Path Issues**: Ensure all paths in the configuration files are absolute paths appropriate for your system
+- **MCP Server Errors**: Make sure the tools are properly installed and configured
+- **API Key Errors**: Verify your API key is correctly set in the `.env` file