MCP-DEMO

# MCP-DEMO: My Learning Journey with Model Context Protocol ## Introduction This repository documents my learning journey with the Model Context Protocol (MCP). As I explore and understand this innovative technology, I’m implementing various examples and documenting my findings. MCP is a fascinating protocol that enables seamless interaction between Large Language Models (LLMs) and local tools/services. ## What is MCP? The Model Context Protocol (MCP) is a protocol designed to facilitate communication between language models and local tools/services. It provides: - A standardized way to expose local tools to LLMs. - Multiple transport layers (stdio and Server-Sent Events). - Integration with various LLMs (e.g., OpenAI and Groq). - Tool discovery and registration mechanisms. - Asynchronous support for enhanced performance. ## Learning Path Structure My learning journey is organized into several key areas: ### 1. Simple Examples (`learning/simple/`) Start here to understand the basics: - [`server_stdio.py`](learning/simple/server_stdio.py): Basic MCP server using stdio transport. - [`client_stdio.py`](learning/simple/client_stdio.py): Corresponding stdio client. - [`server_sse.py`](learning/simple/server_sse.py): MCP server using SSE transport. - [`client_sse.py`](learning/simple/client_sse.py): SSE client implementation. - [README](learning/simple/README.md): More details about the Simple Examples. ### 2. Groq Integration (`learning/groq/`) Exploring MCP with Groq's LLM: - Server implementation for knowledge base access. - Various client implementations (async, SSE, simple). - Example of tool usage and LLM interactions. - [README](learning/groq/README.md): More details about the Groq Integration. ### 3. Servers (`learning/Servers/`) Different server implementations: - PostgreSQL database server. - Web search server using Tavily. - File system server. - Asynchronous implementations. - [README](learning/Servers/README.md): More details about the Server Implementations. ### 4. Clients (`learning/Clients/`) Advanced client implementations: - Multi-server client. - Agent implementations. - Asynchronous patterns. - [README](learning/Clients/README.md): More details about the Client Implementations. ### 5. Asynchronous Python (`learning/asynchronous python/`) Learning async programming with Python: - Basic async concepts. - Task management. - Event loops. - Real-world async patterns. - [README](learning/asynchronous python/README.md): More details about Asynchronous Python. ## Project Setup ### Prerequisites - Python 3.12 or higher. - `uv` package manager. - PostgreSQL (for database examples). - API keys for Groq and Tavily (optional, depending on examples). ### Installation 1. Clone the repository: ```bash git clone https://github.com/yourusername/mcp-demo.git cd mcp-demo ``` 2. Create a virtual environment and install dependencies using `uv`: ```bash uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install -r requirements.txt ``` 3. Set up environment variables: ```bash cp .env.example .env # Edit .env with your API keys (e.g., GROQ_API_KEY, TAVILY_API_KEY) and configuration ``` ## Learning Guide 1. **Start with Basics**: - Read through `learning/simple/` examples. - Run the stdio examples first (simpler setup). - Understand the basic client-server interaction. 2. **Progress to SSE Transport**: - Move to SSE examples for web-based communication. - Learn about real-time updates and streaming. 3. **Explore LLM Integration**: - Study the Groq examples. - Understand tool registration and discovery. - Learn about prompt engineering with tools. 4. **Advanced Topics**: - Explore multi-server architectures. - Study async patterns and best practices. - Implement complex tool examples. ## Project Structure ``` mcp-demo/ ├── learning/ │ ├── simple/ # Basic examples │ ├── groq/ # Groq LLM integration │ ├── Servers/ # Various server implementations │ ├── Clients/ # Client implementations │ └── asynchronous python/ # Async programming examples ├── main.py # Project entry point (CLI interface) ├── browser_documentation.py # Web-based interface ├── requirements.txt # Project dependencies ├── templates/ # HTML templates for web interface ├── .env # Environment variables └── README.md # This file ``` ## Using the Project ### Console-Based Interface Run `python main.py` to explore the MCP learning journey via a command-line interface. Features include: - Interactive menu to view full module documentation (`README.md` files). - Listing and running Python scripts in each module. - Console-based navigation for quick access. ### Web-Based Interface Run `python browser_documentation.py` to launch a browser-based documentation site at `http://localhost:5000`. Features include: - Full rendering of module documentation as HTML. - Sidebar navigation for modules (`simple`, `groq`, `Servers`, etc.). - Interactive script execution with outputs displayed via "Run" buttons on module pages (e.g., `/module/groq`). - View script source code directly in the browser via links in `README.md` (e.g., `/learning/groq/simple_async_groq_client.py`) or module pages (e.g., `/module/groq/script/simple_async_groq_client.py`). - Environment variable configuration at `/env` to set keys like `GROQ_API_KEY`, `DATABASE_URL`, etc. - Responsive design with Tailwind CSS. *Note*: Links in `README.md` (e.g., `learning/groq/simple_async_groq_client.py`) are intended to display script content in the web interface. If links redirect incorrectly (e.g., adding `/module/`), ensure the latest `browser_documentation.py` is used, or see the Troubleshooting section. ## Dependencies Key dependencies include: - `mcp[cli]`: Core MCP functionality. - `groq`: Groq LLM API client. - `asyncpg`: Asynchronous PostgreSQL driver. - `httpx`: Asynchronous HTTP client. - `python-dotenv`: Environment management. - `tavily-python`: Web search API client. - `flask`: Web framework for the browser interface. - `markdown`: Markdown processing for documentation. ## Contributing Feel free to: - Open issues for questions or bugs. - Submit pull requests (PRs) for improvements. - Share your own learning experiences. - Add more examples or modules. ## Troubleshooting - **Link Redirection Issues**: If clicking a link (e.g., `learning/groq/simple_async_groq_client.py`) redirects to an incorrect URL (e.g., `/module/learning/groq/simple_async_groq_client.py` and shows a 404 error), update `browser_documentation.py` with the latest version from the repository or this documentation’s history. The file includes a fix to rewrite links to `/learning/<module>/<file>`. - **Script Not Found**: Ensure the script file exists in the corresponding `learning/<module>/` directory and matches the name in `README.md`. - **Environment Errors**: Verify `.env` contains all required variables (e.g., `GROQ_API_KEY`) and that the virtual environment is activated. - **Web Interface Not Loading**: Check that `templates/` contains the required HTML files (`base.html`, `index.html`, `module.html`, `error.html`, `env.html`) and that `python browser_documentation.py` runs without errors. ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## Resources - [MCP Documentation](https://mcp.readthedocs.io/) - [Groq Documentation](https://docs.groq.com/) - [AsyncIO Documentation](https://docs.python.org/3/library/asyncio.html) - [Flask Documentation](https://flask.palletsprojects.com/)