What is Mcp Demo

MCP-DEMO is a project that documents the author’s learning journey with the Model Context Protocol (MCP), which facilitates seamless communication between Large Language Models (LLMs) and local tools/services.

Use cases

Use cases for MCP include building applications that require LLMs to access local databases, web services, or file systems, as well as creating interactive tools that leverage LLM capabilities.

How to use

To use MCP-DEMO, explore the provided examples in the repository. Start with simple examples to understand the basics, then move on to Groq integration and various server implementations.

Key features

Key features of MCP include standardized exposure of local tools to LLMs, multiple transport layers (stdio and Server-Sent Events), integration with various LLMs, tool discovery and registration mechanisms, and asynchronous support for enhanced performance.

Where to use

MCP can be utilized in fields that require interaction between language models and local services, such as AI development, data processing, and tool integration.

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: Basic MCP server using stdio transport.
• client_stdio.py: Corresponding stdio client.
• server_sse.py: MCP server using SSE transport.
• client_sse.py: SSE client implementation.
• README: 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: 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: More details about the Server Implementations.

4. Clients (learning/Clients/)

Advanced client implementations:

• Multi-server client.
• Agent implementations.
• Asynchronous patterns.
• README: 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](https://github.com/Dadiya-Harsh-wappnet/MCP-DEMO/blob/master/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:

   git clone https://github.com/yourusername/mcp-demo.git
   cd mcp-demo
   

2. Create a virtual environment and install dependencies using uv:

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv pip install -r requirements.txt
   

3. Set up environment variables:

   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 file for details.

Resources

• MCP Documentation
• Groq Documentation
• AsyncIO Documentation
• Flask Documentation