git clone git@github.com:keli-wen/mcp_chatbot.git
cd mcp_chatbot

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:

   {
       "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 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 scripts/check.sh

Usage

Unit Test

You can run the following command to run the unit test:

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

   python example/single_prompt/single_prompt.py
   

2. Streaming Mode: Process a single prompt with real-time streaming output

   python example/single_prompt/single_prompt_stream.py
   

Both examples accept an optional --llm parameter to specify which LLM provider to use:

python example/single_prompt/single_prompt.py --llm=ollama

[!NOTE] For more details, see the Single Prompt Example README.

Terminal Chatbot Examples

The project includes two interactive terminal chatbot examples:

1. Regular Mode: Interactive terminal chat with complete responses

   python example/chatbot_terminal/chatbot_terminal.py
   

2. Streaming Mode: Interactive terminal chat with streaming responses

   python example/chatbot_terminal/chatbot_terminal_stream.py
   

Both examples accept an optional --llm parameter to specify which LLM provider to use:

python example/chatbot_terminal/chatbot_terminal.py --llm=ollama

[!NOTE] For more details, see the Terminal Chatbot Example README.

Streamlit Web Chatbot Example

The project includes an interactive web-based chatbot example using Streamlit:

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.

[!NOTE] For more details, see the Streamlit Chatbot Example README.

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:

{
    "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