Name | chuk-mcp JSON |
Version |
0.5.1
JSON |
| download |
home_page | None |
Summary | Model Context Protocol Client with Optional Pydantic Support |
upload_time | 2025-07-28 13:27:34 |
maintainer | None |
docs_url | None |
author | None |
requires_python | >=3.11 |
license | MIT |
keywords |
llm
openai
claude
mcp
client
protocol
|
VCS |
 |
bugtrack_url |
|
requirements |
No requirements were recorded.
|
Travis-CI |
No Travis.
|
coveralls test coverage |
No coveralls.
|
# chuk-mcp
A comprehensive Python client implementation for the **Model Context Protocol (MCP)** - the open standard for connecting AI assistants to external data and tools.
[](https://badge.fury.io/py/chuk-mcp)
[](https://pypi.org/project/chuk-mcp/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/astral-sh/uv)
## ๐ฏ Project Overview
**chuk-mcp** is a complete Model Context Protocol (MCP) implementation providing both client and server capabilities with a modern, layered architecture. It supports multiple transport protocols, maintains backward compatibility, and implements cutting-edge features including browser-native operation and structured tool outputs.
## What is the Model Context Protocol?
The **Model Context Protocol (MCP)** is an open standard that enables AI applications to securely access external data and tools. Instead of every AI app building custom integrations, MCP provides a universal interface for:
- **๐ง Tools**: Functions AI can call (APIs, file operations, calculations)
- **๐ Resources**: Data sources AI can read (files, databases, web content)
- **๐ฌ Prompts**: Reusable prompt templates with parameters
- **๐ฏ Real-time Data**: Live information that changes frequently
**Key Benefits:**
- **Standardized**: One protocol for all integrations
- **Secure**: User-controlled access to sensitive data
- **Extensible**: Easy to add new capabilities
- **Language-Agnostic**: Works across different programming languages
## Why Use This Client?
`chuk-mcp` is a production-ready Python implementation that provides:
โ
**Comprehensive MCP Protocol Support** - Core features including tools, resources, prompts, with advanced features like sampling and completion
โ
**Browser-Native Operation** - First-of-kind Pyodide/WebAssembly compatibility
โ
**Type Safety** - Full type annotations with optional Pydantic integration or graceful fallback
โ
**Robust Error Handling** - Automatic retries, connection recovery, and detailed error reporting
โ
**Multi-Transport Architecture** - stdio, HTTP, SSE with extensible interface
โ
**Version-Aware Features** - Automatic protocol negotiation and graceful degradation
โ
**Smart Fallback System** - Works with or without dependencies
โ
**Production Ready** - Battle-tested with proper logging, monitoring, and performance optimization
โ
**UV Optimized** - First-class support for modern Python packaging with UV
## ๐๏ธ Architecture Overview
### Layer Structure
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ CLI & Demo Layer โ โ __main__.py, demos
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Client/Server API โ โ High-level abstractions
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Protocol Layer โ โ Messages, types, features
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Transport Layer โ โ stdio, HTTP, SSE
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Base Layer โ โ Pydantic fallback, config
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
**Benefits of This Architecture:**
- **๐ Pluggable Transports**: Easy to add HTTP, WebSocket, or other transports
- **โป๏ธ Reusable Protocol Layer**: Can be used by servers, proxies, or other tools
- **๐งช Testable Components**: Each layer can be tested independently
- **๐ฆ Clean Dependencies**: Minimal coupling between layers
- **โก Smart Validation**: Optional Pydantic with intelligent fallback
```
chuk_mcp/
โโโ protocol/ # ๐๏ธ Shared protocol layer
โ โโโ types/ # Type definitions and validation
โ โโโ messages/ # Feature-organized messaging
โ โโโ mcp_pydantic_base.py # Type system foundation with fallback
โโโ transports/ # ๐ Transport implementations
โ โโโ stdio/ # Process-based communication
โ โโโ http/ # Modern streamable HTTP
โ โโโ sse/ # Legacy Server-Sent Events
โโโ client/ # ๐ง High-level client API
โโโ server/ # ๐ญ Server framework
```
## ๐ Key Features
### โ
**Comprehensive MCP Protocol Support**
- **Protocol Versions**: 2025-06-18 (current), 2025-03-26, 2024-11-05
- **Core Features**: Tools, Resources, Prompts, Logging, Progress, Cancellation
- **Advanced Features**: Sampling, Completion, Roots, Elicitation (version-dependent)
- **Structured Output**: NEW in 2025-06-18 - tools can return structured data + schemas
- **Version Negotiation**: Automatic protocol version detection and fallback
### ๐ **Multi-Transport Architecture**
- **stdio**: Process-based communication (always available)
- **HTTP**: Modern Streamable HTTP (replaces SSE)
- **SSE**: Server-Sent Events (deprecated but supported for compatibility)
- **Extensible**: Clean transport interface for future protocols
### ๐ง **Smart Fallback System**
- **Pydantic Detection**: Auto-detects and uses Pydantic if available
- **Fallback Mode**: Complete validation system when Pydantic unavailable
- **Browser Compatible**: Works in Pyodide/WebAssembly environments
- **Zero Dependencies**: Core functionality works with stdlib only
## Installation
### Quick Start with UV (Recommended)
[UV](https://github.com/astral-sh/uv) is the fastest Python package manager. Choose your installation based on your needs:
```bash
# ๐ Minimal installation (uses lightweight fallback validation)
uv add chuk-mcp
# ๐ง With Pydantic validation (recommended for production)
uv add chuk-mcp[pydantic]
# ๐ Full features (Pydantic + HTTP transport + all extras)
uv add chuk-mcp[full]
# ๐ ๏ธ Development installation (includes testing and examples)
uv add chuk-mcp[dev]
```
### Traditional Installation
```bash
# Using pip (if UV not available)
pip install chuk-mcp
# With Pydantic support
pip install chuk-mcp[pydantic]
# Full features
pip install chuk-mcp[full]
```
### Installation Options Explained
| Option | Dependencies | Use Case | Performance |
|--------|-------------|----------|-------------|
| `chuk-mcp` | Core only | Minimal deployments, testing | Fast startup, lightweight validation |
| `chuk-mcp[pydantic]` | + Pydantic | Production use, type safety | Enhanced validation, better errors |
| `chuk-mcp[full]` | + All features | Maximum functionality | Full feature set |
| `chuk-mcp[dev]` | + Dev tools | Development, testing | All tools included |
> **๐ก Performance Note:** The lightweight fallback validation is ~20x slower than Pydantic (0.010ms vs 0.000ms per operation) but still excellent for most use cases. Use `[pydantic]` for high-throughput applications.
### Verify Installation
```bash
# Quick test with UV
uv run python -c "import chuk_mcp; print('โ
chuk-mcp installed successfully')"
# Or test full functionality
uv run --with chuk-mcp[pydantic] python -c "
from chuk_mcp.protocol.mcp_pydantic_base import PYDANTIC_AVAILABLE
print(f'โ
Pydantic available: {PYDANTIC_AVAILABLE}')
"
```
## Protocol Compliance
`chuk-mcp` provides comprehensive compliance with the MCP specification across multiple protocol versions:
### ๐ Supported Protocol Versions
- **Latest**: `2025-06-18` (primary support)
- **Stable**: `2025-03-26` (full compatibility)
- **Legacy**: `2024-11-05` (backward compatibility)
### ๐ Protocol Compliance Matrix
| Feature Category | 2024-11-05 | 2025-03-26 | 2025-06-18 | Implementation Status |
|-----------------|------------|------------|------------|---------------------|
| **Core Operations** | | | | |
| Tools (list/call) | โ
| โ
| โ
| โ
Complete |
| Resources (list/read/subscribe) | โ
| โ
| โ
| โ
Complete |
| Prompts (list/get) | โ
| โ
| โ
| โ
Complete |
| **Transport** | | | | |
| Stdio | โ
| โ
| โ
| โ
Complete |
| SSE | โ
| โ ๏ธ Deprecated | โ Removed | โ
Legacy Support |
| HTTP Streaming | โ | โ
| โ
| โ
Complete |
| **Advanced Features** | | | | |
| Sampling | โ
| โ
| โ
| โ
Complete |
| Completion | โ
| โ
| โ
| โ
Complete |
| Roots | โ
| โ
| โ
| โ
Complete |
| Elicitation | โ | โ | โ
| โ
Complete |
| **Quality Features** | | | | |
| Progress Tracking | โ
| โ
| โ
| โ
Complete |
| Cancellation | โ
| โ
| โ
| โ
Complete |
| Notifications | โ
| โ
| โ
| โ
Complete |
| Batching | โ
| โ
| โ Deprecated | โ
Legacy Support |
## Quick Start
### Simple Demo
```python
import anyio
from chuk_mcp import stdio_client, StdioServerParameters
from chuk_mcp.protocol.messages import send_initialize
async def main():
# Demo with minimal echo server (no external dependencies)
server_params = StdioServerParameters(
command="python",
args=["-c", """
import json, sys
init = json.loads(input())
response = {
"id": init["id"],
"result": {
"serverInfo": {"name": "Demo", "version": "1.0"},
"protocolVersion": "2025-06-18",
"capabilities": {}
}
}
print(json.dumps(response))
"""]
)
async with stdio_client(server_params) as (read, write):
result = await send_initialize(read, write)
print(f"โ
Connected to {result.serverInfo.name}")
if __name__ == "__main__":
anyio.run(main)
```
Run with UV:
```bash
uv run --with chuk-mcp[pydantic] python demo.py
```
### Basic Usage with Real Server
```python
import anyio
from chuk_mcp import stdio_client, StdioServerParameters
from chuk_mcp.protocol.messages import send_initialize
async def main():
# Configure connection to an MCP server
server_params = StdioServerParameters(
command="uvx", # Use uvx to run Python tools
args=["mcp-server-sqlite", "--db-path", "example.db"]
)
# Connect and initialize
async with stdio_client(server_params) as (read_stream, write_stream):
# Initialize the MCP session
init_result = await send_initialize(read_stream, write_stream)
if init_result:
print(f"โ
Connected to {init_result.serverInfo.name}")
print(f"๐ Protocol version: {init_result.protocolVersion}")
else:
print("โ Failed to initialize connection")
anyio.run(main)
```
### Using the CLI
Test server connectivity instantly:
```bash
# Test with quickstart demo
uv run examples/quickstart.py
# Run comprehensive demos
uv run examples/e2e_smoke_test_example.py --demo all
# Test specific server configurations
uv run examples/e2e_smoke_test_example.py --smoke
```
## ๐ฏ Innovation Highlights
### 1. **Browser-Native MCP** ๐
- **Pyodide Compatible**: Runs completely in browser via WebAssembly
- **Zero Network Dependencies**: Works offline in browser
- **Progressive Enhancement**: Uses Pydantic when available, fallback otherwise
- **First-of-Kind**: First browser-native MCP implementation
### 2. **Version-Aware Features** ๐
- **Automatic Adaptation**: Features enable/disable based on protocol version
- **Graceful Degradation**: Older servers work with newer clients
- **Forward Compatibility**: Ready for future MCP versions
### 3. **Transport Abstraction** ๐
```python
# Same API across all transports
async with stdio_client(stdio_params) as streams:
response = await send_message(*streams, "ping")
async with http_client(http_params) as streams:
response = await send_message(*streams, "ping") # Same API!
```
## ๐ Latest Features
### Structured Tool Output (2025-06-18)
Tools can now return both human-readable text and machine-processable structured data:
```python
# NEW in 2025-06-18: Tools return structured data + schemas
result = await tool_call("analyze_text", {"text": "Hello world"})
# Text summary for humans
print(result.content[0].text) # "Analyzed 2 words, positive sentiment"
# Structured data for machines
data = result.structuredContent[0].data
sentiment_score = data["sentiment"]["score"] # 0.85
word_count = data["statistics"]["word_count"] # 2
```
This enables AI assistants to process tool outputs programmatically while still providing clear summaries for users.
## Core Concepts
### ๐ง Tools - Functions AI Can Call
Tools are functions that AI can execute on your behalf. Examples include file operations, API calls, calculations, or any custom logic.
```python
from chuk_mcp.protocol.messages import send_tools_list, send_tools_call
async def explore_tools(read_stream, write_stream):
# List available tools
tools_response = await send_tools_list(read_stream, write_stream)
for tool in tools_response.get("tools", []):
print(f"๐ง {tool['name']}: {tool['description']}")
# Call a specific tool
result = await send_tools_call(
read_stream, write_stream,
name="execute_sql",
arguments={"query": "SELECT COUNT(*) FROM users"}
)
print(f"๐ Query result: {result}")
```
### ๐ Resources - Data AI Can Access
Resources are data sources like files, database records, API responses, or any URI-addressable content.
```python
from chuk_mcp.protocol.messages import send_resources_list, send_resources_read
async def explore_resources(read_stream, write_stream):
# Discover available resources
resources_response = await send_resources_list(read_stream, write_stream)
for resource in resources_response.get("resources", []):
print(f"๐ {resource['name']} ({resource.get('mimeType', 'unknown')})")
print(f" URI: {resource['uri']}")
# Read specific resource content
if resources_response.get("resources"):
first_resource = resources_response["resources"][0]
content = await send_resources_read(read_stream, write_stream, first_resource["uri"])
for item in content.get("contents", []):
if "text" in item:
print(f"๐ Content preview: {item['text'][:200]}...")
```
### ๐ฌ Prompts - Reusable Templates
Prompts are parameterized templates that help generate consistent, high-quality AI interactions.
```python
from chuk_mcp.protocol.messages import send_prompts_list, send_prompts_get
async def use_prompts(read_stream, write_stream):
# List available prompt templates
prompts_response = await send_prompts_list(read_stream, write_stream)
for prompt in prompts_response.get("prompts", []):
print(f"๐ฌ {prompt['name']}: {prompt['description']}")
# Get a prompt with custom arguments
prompt_result = await send_prompts_get(
read_stream, write_stream,
name="analyze_data",
arguments={"dataset": "sales_2024", "metric": "revenue"}
)
# The result contains formatted messages ready for AI
for message in prompt_result.get("messages", []):
print(f"๐ค {message['role']}: {message['content']}")
```
## Configuration
### Server Configuration
Create a `server_config.json` file to define your MCP servers:
```json
{
"mcpServers": {
"sqlite": {
"command": "uvx",
"args": ["mcp-server-sqlite", "--db-path", "database.db"]
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
},
"github": {
"command": "uvx",
"args": ["mcp-server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
},
"python": {
"command": "uv",
"args": ["run", "--with", "mcp-server-python", "mcp-server-python"],
"env": {
"PYTHONPATH": "/custom/python/path"
}
}
}
}
```
### Configuration Loading
```python
from chuk_mcp.transports.stdio import stdio_client, StdioServerParameters
from chuk_mcp.protocol.messages import send_initialize
async def connect_configured_server():
# Load server configuration
server_params = StdioServerParameters(
command="uvx",
args=["mcp-server-sqlite", "--db-path", "database.db"]
)
async with stdio_client(server_params) as (read_stream, write_stream):
init_result = await send_initialize(read_stream, write_stream)
print(f"Connected to configured server: {init_result.serverInfo.name}")
```
## Advanced Features
### ๐ฏ Intelligent Sampling
Let servers request AI to generate content on their behalf (with user approval):
```python
from chuk_mcp.protocol.messages.sampling import (
send_sampling_create_message,
create_sampling_message
)
async def ai_content_generation(read_stream, write_stream):
# Server can request AI to generate content
messages = [
create_sampling_message("user", "Explain quantum computing in simple terms")
]
result = await send_sampling_create_message(
read_stream, write_stream,
messages=messages,
max_tokens=1000,
temperature=0.7
)
print(f"๐ค AI Generated: {result['content']['text']}")
```
### ๐ฏ Argument Completion
Provide intelligent autocompletion for tool arguments:
```python
from chuk_mcp.protocol.messages.completion import (
send_completion_complete,
create_resource_reference,
create_argument_info
)
async def smart_completion(read_stream, write_stream):
# Get completion suggestions for a resource argument
response = await send_completion_complete(
read_stream, write_stream,
ref=create_resource_reference("file:///project/data/"),
argument=create_argument_info("filename", "sales_202")
)
completions = response.get("completion", {}).get("values", [])
print(f"๐ก Suggestions: {completions}")
```
### ๐ Multi-Server Orchestration
Connect to multiple servers simultaneously:
```python
from chuk_mcp.transports.stdio import stdio_client, StdioServerParameters
from chuk_mcp.protocol.messages import send_tools_list
async def multi_server_task():
"""Process data using multiple MCP servers."""
servers = [
StdioServerParameters(command="uvx", args=["mcp-server-sqlite", "--db-path", "data.db"]),
StdioServerParameters(command="npx", args=["-y", "@modelcontextprotocol/server-filesystem", "/data"]),
]
for i, server_params in enumerate(servers):
async with stdio_client(server_params) as (read_stream, write_stream):
print(f"Processing with server {i+1}")
# Each server can have different capabilities
tools = await send_tools_list(read_stream, write_stream)
print(f" Available tools: {len(tools.get('tools', []))}")
```
### ๐ก Real-time Subscriptions
Subscribe to resource changes for live updates:
```python
from chuk_mcp.protocol.messages.resources import send_resources_subscribe
async def live_monitoring(read_stream, write_stream):
# Subscribe to file changes
success = await send_resources_subscribe(
read_stream, write_stream,
uri="file:///project/logs/app.log"
)
if success:
print("๐ก Subscribed to log file changes")
# Handle notifications in your message loop
# (implementation depends on your notification handling)
```
## Error Handling & Resilience
`chuk-mcp` provides robust error handling with automatic retries:
```python
from chuk_mcp.protocol.messages import RetryableError, NonRetryableError
from chuk_mcp.protocol.messages import send_tools_call
async def resilient_operations(read_stream, write_stream):
try:
# Operations automatically retry on transient failures
result = await send_tools_call(
read_stream, write_stream,
name="network_operation",
arguments={"url": "https://api.example.com/data"},
timeout=30.0, # Extended timeout for slow operations
retries=5 # More retries for critical operations
)
except RetryableError as e:
print(f"โ ๏ธ Transient error after retries: {e}")
# Handle gracefully - maybe try alternative approach
except NonRetryableError as e:
print(f"โ Permanent error: {e}")
# Handle definitively - operation cannot succeed
except Exception as e:
print(f"๐จ Unexpected error: {e}")
# Handle unknown errors
```
## ๐งช Testing & Demos
### Comprehensive Test Suite
1. **Working Smoke Tests**: Full E2E validation with real servers
2. **Pyodide Browser Demo**: Live browser testing environment
3. **Tools Demo**: Structured output feature showcase
4. **Performance Tests**: Throughput and latency benchmarks
### Demo Applications
- **CLI Tools**: Ready-to-use command-line utilities
- **Interactive Explorer**: Hands-on tool testing
- **Protocol Validator**: Real-time MCP compliance checking
- **Browser Demo**: WebAssembly-based MCP in the browser
### Testing & Validation
```bash
# Quick validation
uv run examples/quickstart.py
# Run comprehensive tests
uv run examples/e2e_smoke_test_example.py --demo all
# Validate installation scenarios
uv run diagnostics/installation_scenarios_diagnostic.py
# Test specific functionality
uv run examples/e2e_smoke_test_example.py --smoke
# Performance benchmarks
uv run examples/e2e_smoke_test_example.py --performance
```
## Available MCP Servers
The MCP ecosystem includes servers for popular services:
### ๐ Install with UV (Recommended)
```bash
# Popular Python servers
uv tool install mcp-server-sqlite
uv tool install mcp-server-github
uv tool install mcp-server-postgres
# Or run directly without installation
uv run --with mcp-server-sqlite mcp-server-sqlite --db-path data.db
```
### ๐ข Node.js Servers
```bash
# Use npx for Node.js servers
npx -y @modelcontextprotocol/server-filesystem /path/to/files
npx -y @modelcontextprotocol/server-brave-search
```
### ๐ Available Servers
- **๐ Filesystem**: `@modelcontextprotocol/server-filesystem`
- **๐๏ธ SQLite**: `mcp-server-sqlite`
- **๐ GitHub**: `mcp-server-github`
- **โ๏ธ Google Drive**: `mcp-server-gdrive`
- **๐ Web Search**: `mcp-server-brave-search`
- **๐ PostgreSQL**: `mcp-server-postgres`
- **๐ Analytics**: Various data analytics servers
- **๐ง Custom**: Build your own with the MCP SDK
Find more at: [MCP Servers Directory](https://github.com/modelcontextprotocol/servers)
## Building MCP Servers
Want to create your own MCP server? Check out:
- **Python**: [`mcp` package](https://pypi.org/project/mcp/)
- **TypeScript**: [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
- **Specification**: [MCP Protocol Documentation](https://spec.modelcontextprotocol.io/)
## Performance & Monitoring
`chuk-mcp` includes built-in performance monitoring:
```python
import logging
# Enable detailed logging for debugging
logging.basicConfig(level=logging.DEBUG)
# Performance is optimized for:
# - Concurrent server connections
# - Efficient message routing
# - Minimal memory allocation
# - Fast JSON serialization
```
### ๐ Performance Characteristics
**Benchmarks (from smoke tests):**
- **Connection Setup**: ~200ms (fast)
- **Request Throughput**: >50 req/sec concurrent
- **Memory Usage**: Minimal footprint
- **Browser Performance**: <2s load time, instant operations
**Performance Highlights:**
- **๐ Fast Startup**: < 1 second connection time
- **โก High Throughput**: 50+ requests/second per connection
- **๐ Concurrent Operations**: Full async/await support
- **๐พ Memory Efficient**: Minimal overhead per connection
### Installation Performance Matrix
| Installation | Startup Time | Validation Speed | Memory Usage | Dependencies |
|-------------|-------------|------------------|--------------|--------------|
| `chuk-mcp` | < 0.5s | 0.010ms/op | 15MB | Core only |
| `chuk-mcp[pydantic]` | < 1.0s | 0.000ms/op | 25MB | + Pydantic |
| `chuk-mcp[full]` | < 1.5s | 0.000ms/op | 35MB | All features |
## Intelligent Dependency Management
`chuk-mcp` includes intelligent dependency handling with graceful fallbacks:
```python
# Check validation backend
from chuk_mcp.protocol.mcp_pydantic_base import PYDANTIC_AVAILABLE
if PYDANTIC_AVAILABLE:
print("โ
Using Pydantic for enhanced validation")
print(" โข Better error messages")
print(" โข Faster validation (Rust-based)")
print(" โข Advanced type coercion")
else:
print("๐ฆ Using lightweight fallback validation")
print(" โข Pure Python implementation")
print(" โข No external dependencies")
print(" โข ~20x slower but still fast")
# Force fallback mode for testing
import os
os.environ["MCP_FORCE_FALLBACK"] = "1"
```
## Development
### Setup with UV
```bash
git clone https://github.com/chrishayuk/chuk-mcp
cd chuk-mcp
# Install with development dependencies
uv sync
# Activate the virtual environment
source .venv/bin/activate # Linux/Mac
# or .venv\Scripts\activate # Windows
```
### Traditional Setup
```bash
# Alternative setup with pip
pip install -e ".[dev]"
```
### Development Features
```bash
# Test with fallback validation
UV_MCP_FORCE_FALLBACK=1 uv run examples/quickstart.py
# Test with different Python versions
uv run --python 3.11 examples/quickstart.py
uv run --python 3.12 examples/quickstart.py
```
### Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for your changes
4. Ensure all tests pass with `uv run diagnostics/installation_scenarios_diagnostic.py`
5. Submit a pull request
## UV Integration Features
### Project Templates
```bash
# Start a new MCP client project
uv init my-mcp-client
cd my-mcp-client
# Add chuk-mcp with dependencies
uv add chuk-mcp[pydantic]
# Add development tools
uv add --dev pytest black isort
# Create example
cat > main.py << 'EOF'
import anyio
from chuk_mcp import stdio_client, StdioServerParameters
async def main():
# Your MCP client code here
pass
if __name__ == "__main__":
anyio.run(main)
EOF
```
### UV Scripts
Add to your `pyproject.toml`:
```toml
[tool.uv]
dev-dependencies = [
"chuk-mcp[dev]",
]
[project.scripts]
mcp-client = "my_mcp_client:main"
[tool.uv.scripts]
test-mcp = "uv run examples/quickstart.py"
validate = "uv run diagnostics/installation_scenarios_diagnostic.py"
```
## ๐๏ธ Production Readiness
### โ
**Enterprise Features**
- **Error Recovery**: Comprehensive error handling and retry logic
- **Logging**: Structured logging with configurable levels
- **Monitoring**: Built-in health checks and metrics
- **Security**: Input validation and safe subprocess handling
### โ
**Deployment Options**
- **Standalone**: Direct process execution
- **Containerized**: Docker-ready with minimal dependencies
- **Browser**: Progressive Web App deployment via Pyodide
- **Cloud**: Stateless operation suitable for serverless
### โ
**Maintenance**
- **Documentation**: Comprehensive examples and type hints
- **Testing**: 100% working test coverage with real scenarios
- **Migration Support**: Clear upgrade paths for new features
## ๐ Future Roadmap
### Near Term
- **Additional Transports**: WebSocket, gRPC support
- **Enhanced Tooling**: Visual debugger, protocol inspector
- **Performance**: Further optimization for high-throughput scenarios
### Long Term
- **Protocol Extensions**: Custom capability negotiation
- **Distributed MCP**: Multi-server orchestration
- **Visual Builder**: GUI for MCP server development
## Support & Community
- **๐ Documentation**: [Full API Documentation](https://docs.example.com)
- **๐ Issues**: [GitHub Issues](https://github.com/chrishayuk/chuk-mcp/issues)
- **๐ฌ Discussions**: [GitHub Discussions](https://github.com/chrishayuk/chuk-mcp/discussions)
- **๐ง Email**: For private inquiries
- **๐ UV**: [UV Package Manager](https://github.com/astral-sh/uv)
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Acknowledgments
- Built on the [Model Context Protocol](https://modelcontextprotocol.io/) specification
- Inspired by the official [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- Thanks to the MCP community for feedback and contributions
- Special thanks to the [UV](https://github.com/astral-sh/uv) team for making Python package management fast and reliable
---
## ๐ Summary
**chuk-mcp** represents a **production-ready, comprehensive MCP implementation** that:
- โ
**Implements comprehensive MCP protocol features** including latest 2025-06-18 capabilities
- โ
**Provides clean, modern APIs** with intelligent fallback systems
- โ
**Supports multiple transports** with a unified interface
- โ
**Works everywhere** - server, desktop, and browser environments
- โ
**Delivers enterprise-grade reliability** with comprehensive error handling
- โ
**Enables innovation** through structured outputs and extensible architecture
This implementation sets a new standard for MCP libraries, being both **immediately practical** for production use and **forward-looking** for next-generation MCP applications.
Raw data
{
"_id": null,
"home_page": null,
"name": "chuk-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "llm, openai, claude, mcp, client, protocol",
"author": null,
"author_email": "Chris Hay <chrishayuk@somejunkmailbox.com>",
"download_url": "https://files.pythonhosted.org/packages/82/2b/71ddc6dc123426f92c06f62ff2400cd0d380b7e29f5e9f5277f43f0e6969/chuk_mcp-0.5.1.tar.gz",
"platform": null,
"description": "# chuk-mcp\n\nA comprehensive Python client implementation for the **Model Context Protocol (MCP)** - the open standard for connecting AI assistants to external data and tools.\n\n[](https://badge.fury.io/py/chuk-mcp)\n[](https://pypi.org/project/chuk-mcp/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/astral-sh/uv)\n\n## \ud83c\udfaf Project Overview\n\n**chuk-mcp** is a complete Model Context Protocol (MCP) implementation providing both client and server capabilities with a modern, layered architecture. It supports multiple transport protocols, maintains backward compatibility, and implements cutting-edge features including browser-native operation and structured tool outputs.\n\n## What is the Model Context Protocol?\n\nThe **Model Context Protocol (MCP)** is an open standard that enables AI applications to securely access external data and tools. Instead of every AI app building custom integrations, MCP provides a universal interface for:\n\n- **\ud83d\udd27 Tools**: Functions AI can call (APIs, file operations, calculations)\n- **\ud83d\udcc4 Resources**: Data sources AI can read (files, databases, web content) \n- **\ud83d\udcac Prompts**: Reusable prompt templates with parameters\n- **\ud83c\udfaf Real-time Data**: Live information that changes frequently\n\n**Key Benefits:**\n- **Standardized**: One protocol for all integrations\n- **Secure**: User-controlled access to sensitive data\n- **Extensible**: Easy to add new capabilities\n- **Language-Agnostic**: Works across different programming languages\n\n## Why Use This Client?\n\n`chuk-mcp` is a production-ready Python implementation that provides:\n\n\u2705 **Comprehensive MCP Protocol Support** - Core features including tools, resources, prompts, with advanced features like sampling and completion \n\u2705 **Browser-Native Operation** - First-of-kind Pyodide/WebAssembly compatibility \n\u2705 **Type Safety** - Full type annotations with optional Pydantic integration or graceful fallback \n\u2705 **Robust Error Handling** - Automatic retries, connection recovery, and detailed error reporting \n\u2705 **Multi-Transport Architecture** - stdio, HTTP, SSE with extensible interface \n\u2705 **Version-Aware Features** - Automatic protocol negotiation and graceful degradation \n\u2705 **Smart Fallback System** - Works with or without dependencies \n\u2705 **Production Ready** - Battle-tested with proper logging, monitoring, and performance optimization \n\u2705 **UV Optimized** - First-class support for modern Python packaging with UV\n\n## \ud83c\udfd7\ufe0f Architecture Overview\n\n### Layer Structure\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 CLI & Demo Layer \u2502 \u2190 __main__.py, demos\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 Client/Server API \u2502 \u2190 High-level abstractions\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 Protocol Layer \u2502 \u2190 Messages, types, features\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 Transport Layer \u2502 \u2190 stdio, HTTP, SSE\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 Base Layer \u2502 \u2190 Pydantic fallback, config\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n**Benefits of This Architecture:**\n- **\ud83d\udd0c Pluggable Transports**: Easy to add HTTP, WebSocket, or other transports\n- **\u267b\ufe0f Reusable Protocol Layer**: Can be used by servers, proxies, or other tools\n- **\ud83e\uddea Testable Components**: Each layer can be tested independently\n- **\ud83d\udce6 Clean Dependencies**: Minimal coupling between layers\n- **\u26a1 Smart Validation**: Optional Pydantic with intelligent fallback\n\n```\nchuk_mcp/\n\u251c\u2500\u2500 protocol/ # \ud83c\udfd7\ufe0f Shared protocol layer\n\u2502 \u251c\u2500\u2500 types/ # Type definitions and validation\n\u2502 \u251c\u2500\u2500 messages/ # Feature-organized messaging\n\u2502 \u2514\u2500\u2500 mcp_pydantic_base.py # Type system foundation with fallback\n\u251c\u2500\u2500 transports/ # \ud83d\ude80 Transport implementations \n\u2502 \u251c\u2500\u2500 stdio/ # Process-based communication\n\u2502 \u251c\u2500\u2500 http/ # Modern streamable HTTP\n\u2502 \u2514\u2500\u2500 sse/ # Legacy Server-Sent Events\n\u251c\u2500\u2500 client/ # \ud83d\udd27 High-level client API\n\u2514\u2500\u2500 server/ # \ud83c\udfed Server framework\n```\n\n## \ud83d\ude80 Key Features\n\n### \u2705 **Comprehensive MCP Protocol Support**\n- **Protocol Versions**: 2025-06-18 (current), 2025-03-26, 2024-11-05\n- **Core Features**: Tools, Resources, Prompts, Logging, Progress, Cancellation\n- **Advanced Features**: Sampling, Completion, Roots, Elicitation (version-dependent)\n- **Structured Output**: NEW in 2025-06-18 - tools can return structured data + schemas\n- **Version Negotiation**: Automatic protocol version detection and fallback\n\n### \ud83c\udf10 **Multi-Transport Architecture**\n- **stdio**: Process-based communication (always available)\n- **HTTP**: Modern Streamable HTTP (replaces SSE)\n- **SSE**: Server-Sent Events (deprecated but supported for compatibility)\n- **Extensible**: Clean transport interface for future protocols\n\n### \ud83e\udde0 **Smart Fallback System**\n- **Pydantic Detection**: Auto-detects and uses Pydantic if available\n- **Fallback Mode**: Complete validation system when Pydantic unavailable\n- **Browser Compatible**: Works in Pyodide/WebAssembly environments\n- **Zero Dependencies**: Core functionality works with stdlib only\n\n## Installation\n\n### Quick Start with UV (Recommended)\n\n[UV](https://github.com/astral-sh/uv) is the fastest Python package manager. Choose your installation based on your needs:\n\n```bash\n# \ud83d\ude80 Minimal installation (uses lightweight fallback validation)\nuv add chuk-mcp\n\n# \ud83d\udd27 With Pydantic validation (recommended for production)\nuv add chuk-mcp[pydantic]\n\n# \ud83c\udf1f Full features (Pydantic + HTTP transport + all extras)\nuv add chuk-mcp[full]\n\n# \ud83d\udee0\ufe0f Development installation (includes testing and examples)\nuv add chuk-mcp[dev]\n```\n\n### Traditional Installation\n\n```bash\n# Using pip (if UV not available)\npip install chuk-mcp\n\n# With Pydantic support\npip install chuk-mcp[pydantic]\n\n# Full features\npip install chuk-mcp[full]\n```\n\n### Installation Options Explained\n\n| Option | Dependencies | Use Case | Performance |\n|--------|-------------|----------|-------------|\n| `chuk-mcp` | Core only | Minimal deployments, testing | Fast startup, lightweight validation |\n| `chuk-mcp[pydantic]` | + Pydantic | Production use, type safety | Enhanced validation, better errors |\n| `chuk-mcp[full]` | + All features | Maximum functionality | Full feature set |\n| `chuk-mcp[dev]` | + Dev tools | Development, testing | All tools included |\n\n> **\ud83d\udca1 Performance Note:** The lightweight fallback validation is ~20x slower than Pydantic (0.010ms vs 0.000ms per operation) but still excellent for most use cases. Use `[pydantic]` for high-throughput applications.\n\n### Verify Installation\n\n```bash\n# Quick test with UV\nuv run python -c \"import chuk_mcp; print('\u2705 chuk-mcp installed successfully')\"\n\n# Or test full functionality\nuv run --with chuk-mcp[pydantic] python -c \"\nfrom chuk_mcp.protocol.mcp_pydantic_base import PYDANTIC_AVAILABLE\nprint(f'\u2705 Pydantic available: {PYDANTIC_AVAILABLE}')\n\"\n```\n\n## Protocol Compliance\n\n`chuk-mcp` provides comprehensive compliance with the MCP specification across multiple protocol versions:\n\n### \ud83d\udccb Supported Protocol Versions\n- **Latest**: `2025-06-18` (primary support)\n- **Stable**: `2025-03-26` (full compatibility)\n- **Legacy**: `2024-11-05` (backward compatibility)\n\n### \ud83d\udcca Protocol Compliance Matrix\n\n| Feature Category | 2024-11-05 | 2025-03-26 | 2025-06-18 | Implementation Status |\n|-----------------|------------|------------|------------|---------------------|\n| **Core Operations** | | | | |\n| Tools (list/call) | \u2705 | \u2705 | \u2705 | \u2705 Complete |\n| Resources (list/read/subscribe) | \u2705 | \u2705 | \u2705 | \u2705 Complete |\n| Prompts (list/get) | \u2705 | \u2705 | \u2705 | \u2705 Complete |\n| **Transport** | | | | |\n| Stdio | \u2705 | \u2705 | \u2705 | \u2705 Complete |\n| SSE | \u2705 | \u26a0\ufe0f Deprecated | \u274c Removed | \u2705 Legacy Support |\n| HTTP Streaming | \u274c | \u2705 | \u2705 | \u2705 Complete |\n| **Advanced Features** | | | | |\n| Sampling | \u2705 | \u2705 | \u2705 | \u2705 Complete |\n| Completion | \u2705 | \u2705 | \u2705 | \u2705 Complete |\n| Roots | \u2705 | \u2705 | \u2705 | \u2705 Complete |\n| Elicitation | \u274c | \u274c | \u2705 | \u2705 Complete |\n| **Quality Features** | | | | |\n| Progress Tracking | \u2705 | \u2705 | \u2705 | \u2705 Complete |\n| Cancellation | \u2705 | \u2705 | \u2705 | \u2705 Complete |\n| Notifications | \u2705 | \u2705 | \u2705 | \u2705 Complete |\n| Batching | \u2705 | \u2705 | \u274c Deprecated | \u2705 Legacy Support |\n\n## Quick Start\n\n### Simple Demo\n\n```python\nimport anyio\nfrom chuk_mcp import stdio_client, StdioServerParameters\nfrom chuk_mcp.protocol.messages import send_initialize\n\nasync def main():\n # Demo with minimal echo server (no external dependencies)\n server_params = StdioServerParameters(\n command=\"python\",\n args=[\"-c\", \"\"\"\nimport json, sys\ninit = json.loads(input())\nresponse = {\n \"id\": init[\"id\"], \n \"result\": {\n \"serverInfo\": {\"name\": \"Demo\", \"version\": \"1.0\"}, \n \"protocolVersion\": \"2025-06-18\", \n \"capabilities\": {}\n }\n}\nprint(json.dumps(response))\n \"\"\"]\n )\n \n async with stdio_client(server_params) as (read, write):\n result = await send_initialize(read, write)\n print(f\"\u2705 Connected to {result.serverInfo.name}\")\n\nif __name__ == \"__main__\":\n anyio.run(main)\n```\n\nRun with UV:\n```bash\nuv run --with chuk-mcp[pydantic] python demo.py\n```\n\n### Basic Usage with Real Server\n\n```python\nimport anyio\nfrom chuk_mcp import stdio_client, StdioServerParameters\nfrom chuk_mcp.protocol.messages import send_initialize\n\nasync def main():\n # Configure connection to an MCP server\n server_params = StdioServerParameters(\n command=\"uvx\", # Use uvx to run Python tools\n args=[\"mcp-server-sqlite\", \"--db-path\", \"example.db\"]\n )\n \n # Connect and initialize\n async with stdio_client(server_params) as (read_stream, write_stream):\n # Initialize the MCP session\n init_result = await send_initialize(read_stream, write_stream)\n \n if init_result:\n print(f\"\u2705 Connected to {init_result.serverInfo.name}\")\n print(f\"\ud83d\udccb Protocol version: {init_result.protocolVersion}\")\n else:\n print(\"\u274c Failed to initialize connection\")\n\nanyio.run(main)\n```\n\n### Using the CLI\n\nTest server connectivity instantly:\n\n```bash\n# Test with quickstart demo\nuv run examples/quickstart.py\n\n# Run comprehensive demos\nuv run examples/e2e_smoke_test_example.py --demo all\n\n# Test specific server configurations\nuv run examples/e2e_smoke_test_example.py --smoke\n```\n\n## \ud83c\udfaf Innovation Highlights\n\n### 1. **Browser-Native MCP** \ud83c\udf10\n- **Pyodide Compatible**: Runs completely in browser via WebAssembly\n- **Zero Network Dependencies**: Works offline in browser\n- **Progressive Enhancement**: Uses Pydantic when available, fallback otherwise\n- **First-of-Kind**: First browser-native MCP implementation\n\n### 2. **Version-Aware Features** \ud83d\udd04\n- **Automatic Adaptation**: Features enable/disable based on protocol version\n- **Graceful Degradation**: Older servers work with newer clients\n- **Forward Compatibility**: Ready for future MCP versions\n\n### 3. **Transport Abstraction** \ud83d\ude80\n```python\n# Same API across all transports\nasync with stdio_client(stdio_params) as streams:\n response = await send_message(*streams, \"ping\")\n\nasync with http_client(http_params) as streams: \n response = await send_message(*streams, \"ping\") # Same API!\n```\n\n## \ud83c\udd95 Latest Features\n\n### Structured Tool Output (2025-06-18)\nTools can now return both human-readable text and machine-processable structured data:\n\n```python\n# NEW in 2025-06-18: Tools return structured data + schemas\nresult = await tool_call(\"analyze_text\", {\"text\": \"Hello world\"})\n\n# Text summary for humans\nprint(result.content[0].text) # \"Analyzed 2 words, positive sentiment\"\n\n# Structured data for machines \ndata = result.structuredContent[0].data\nsentiment_score = data[\"sentiment\"][\"score\"] # 0.85\nword_count = data[\"statistics\"][\"word_count\"] # 2\n```\n\nThis enables AI assistants to process tool outputs programmatically while still providing clear summaries for users.\n\n## Core Concepts\n\n### \ud83d\udd27 Tools - Functions AI Can Call\n\nTools are functions that AI can execute on your behalf. Examples include file operations, API calls, calculations, or any custom logic.\n\n```python\nfrom chuk_mcp.protocol.messages import send_tools_list, send_tools_call\n\nasync def explore_tools(read_stream, write_stream):\n # List available tools\n tools_response = await send_tools_list(read_stream, write_stream)\n \n for tool in tools_response.get(\"tools\", []):\n print(f\"\ud83d\udd27 {tool['name']}: {tool['description']}\")\n \n # Call a specific tool\n result = await send_tools_call(\n read_stream, write_stream,\n name=\"execute_sql\",\n arguments={\"query\": \"SELECT COUNT(*) FROM users\"}\n )\n \n print(f\"\ud83d\udcca Query result: {result}\")\n```\n\n### \ud83d\udcc4 Resources - Data AI Can Access\n\nResources are data sources like files, database records, API responses, or any URI-addressable content.\n\n```python\nfrom chuk_mcp.protocol.messages import send_resources_list, send_resources_read\n\nasync def explore_resources(read_stream, write_stream):\n # Discover available resources\n resources_response = await send_resources_list(read_stream, write_stream)\n \n for resource in resources_response.get(\"resources\", []):\n print(f\"\ud83d\udcc4 {resource['name']} ({resource.get('mimeType', 'unknown')})\")\n print(f\" URI: {resource['uri']}\")\n \n # Read specific resource content\n if resources_response.get(\"resources\"):\n first_resource = resources_response[\"resources\"][0]\n content = await send_resources_read(read_stream, write_stream, first_resource[\"uri\"])\n \n for item in content.get(\"contents\", []):\n if \"text\" in item:\n print(f\"\ud83d\udcd6 Content preview: {item['text'][:200]}...\")\n```\n\n### \ud83d\udcac Prompts - Reusable Templates\n\nPrompts are parameterized templates that help generate consistent, high-quality AI interactions.\n\n```python\nfrom chuk_mcp.protocol.messages import send_prompts_list, send_prompts_get\n\nasync def use_prompts(read_stream, write_stream):\n # List available prompt templates\n prompts_response = await send_prompts_list(read_stream, write_stream)\n \n for prompt in prompts_response.get(\"prompts\", []):\n print(f\"\ud83d\udcac {prompt['name']}: {prompt['description']}\")\n \n # Get a prompt with custom arguments\n prompt_result = await send_prompts_get(\n read_stream, write_stream,\n name=\"analyze_data\",\n arguments={\"dataset\": \"sales_2024\", \"metric\": \"revenue\"}\n )\n \n # The result contains formatted messages ready for AI\n for message in prompt_result.get(\"messages\", []):\n print(f\"\ud83e\udd16 {message['role']}: {message['content']}\")\n```\n\n## Configuration\n\n### Server Configuration\n\nCreate a `server_config.json` file to define your MCP servers:\n\n```json\n{\n \"mcpServers\": {\n \"sqlite\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-server-sqlite\", \"--db-path\", \"database.db\"]\n },\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/path/to/files\"]\n },\n \"github\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-server-github\"],\n \"env\": {\n \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"${GITHUB_TOKEN}\"\n }\n },\n \"python\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"--with\", \"mcp-server-python\", \"mcp-server-python\"],\n \"env\": {\n \"PYTHONPATH\": \"/custom/python/path\"\n }\n }\n }\n}\n```\n\n### Configuration Loading\n\n```python\nfrom chuk_mcp.transports.stdio import stdio_client, StdioServerParameters\nfrom chuk_mcp.protocol.messages import send_initialize\n\nasync def connect_configured_server():\n # Load server configuration\n server_params = StdioServerParameters(\n command=\"uvx\",\n args=[\"mcp-server-sqlite\", \"--db-path\", \"database.db\"]\n )\n \n async with stdio_client(server_params) as (read_stream, write_stream):\n init_result = await send_initialize(read_stream, write_stream)\n print(f\"Connected to configured server: {init_result.serverInfo.name}\")\n```\n\n## Advanced Features\n\n### \ud83c\udfaf Intelligent Sampling\n\nLet servers request AI to generate content on their behalf (with user approval):\n\n```python\nfrom chuk_mcp.protocol.messages.sampling import (\n send_sampling_create_message, \n create_sampling_message\n)\n\nasync def ai_content_generation(read_stream, write_stream):\n # Server can request AI to generate content\n messages = [\n create_sampling_message(\"user\", \"Explain quantum computing in simple terms\")\n ]\n \n result = await send_sampling_create_message(\n read_stream, write_stream,\n messages=messages,\n max_tokens=1000,\n temperature=0.7\n )\n \n print(f\"\ud83e\udd16 AI Generated: {result['content']['text']}\")\n```\n\n### \ud83c\udfaf Argument Completion\n\nProvide intelligent autocompletion for tool arguments:\n\n```python\nfrom chuk_mcp.protocol.messages.completion import (\n send_completion_complete, \n create_resource_reference, \n create_argument_info\n)\n\nasync def smart_completion(read_stream, write_stream):\n # Get completion suggestions for a resource argument\n response = await send_completion_complete(\n read_stream, write_stream,\n ref=create_resource_reference(\"file:///project/data/\"),\n argument=create_argument_info(\"filename\", \"sales_202\")\n )\n \n completions = response.get(\"completion\", {}).get(\"values\", [])\n print(f\"\ud83d\udca1 Suggestions: {completions}\")\n```\n\n### \ud83d\udd04 Multi-Server Orchestration\n\nConnect to multiple servers simultaneously:\n\n```python\nfrom chuk_mcp.transports.stdio import stdio_client, StdioServerParameters\nfrom chuk_mcp.protocol.messages import send_tools_list\n\nasync def multi_server_task():\n \"\"\"Process data using multiple MCP servers.\"\"\"\n \n servers = [\n StdioServerParameters(command=\"uvx\", args=[\"mcp-server-sqlite\", \"--db-path\", \"data.db\"]),\n StdioServerParameters(command=\"npx\", args=[\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/data\"]),\n ]\n \n for i, server_params in enumerate(servers):\n async with stdio_client(server_params) as (read_stream, write_stream):\n print(f\"Processing with server {i+1}\")\n \n # Each server can have different capabilities\n tools = await send_tools_list(read_stream, write_stream)\n print(f\" Available tools: {len(tools.get('tools', []))}\")\n```\n\n### \ud83d\udce1 Real-time Subscriptions\n\nSubscribe to resource changes for live updates:\n\n```python\nfrom chuk_mcp.protocol.messages.resources import send_resources_subscribe\n\nasync def live_monitoring(read_stream, write_stream):\n # Subscribe to file changes\n success = await send_resources_subscribe(\n read_stream, write_stream,\n uri=\"file:///project/logs/app.log\"\n )\n \n if success:\n print(\"\ud83d\udce1 Subscribed to log file changes\")\n \n # Handle notifications in your message loop\n # (implementation depends on your notification handling)\n```\n\n## Error Handling & Resilience\n\n`chuk-mcp` provides robust error handling with automatic retries:\n\n```python\nfrom chuk_mcp.protocol.messages import RetryableError, NonRetryableError\nfrom chuk_mcp.protocol.messages import send_tools_call\n\nasync def resilient_operations(read_stream, write_stream):\n try:\n # Operations automatically retry on transient failures\n result = await send_tools_call(\n read_stream, write_stream,\n name=\"network_operation\",\n arguments={\"url\": \"https://api.example.com/data\"},\n timeout=30.0, # Extended timeout for slow operations\n retries=5 # More retries for critical operations\n )\n \n except RetryableError as e:\n print(f\"\u26a0\ufe0f Transient error after retries: {e}\")\n # Handle gracefully - maybe try alternative approach\n \n except NonRetryableError as e:\n print(f\"\u274c Permanent error: {e}\")\n # Handle definitively - operation cannot succeed\n \n except Exception as e:\n print(f\"\ud83d\udea8 Unexpected error: {e}\")\n # Handle unknown errors\n```\n\n## \ud83e\uddea Testing & Demos\n\n### Comprehensive Test Suite\n1. **Working Smoke Tests**: Full E2E validation with real servers\n2. **Pyodide Browser Demo**: Live browser testing environment \n3. **Tools Demo**: Structured output feature showcase\n4. **Performance Tests**: Throughput and latency benchmarks\n\n### Demo Applications\n- **CLI Tools**: Ready-to-use command-line utilities\n- **Interactive Explorer**: Hands-on tool testing\n- **Protocol Validator**: Real-time MCP compliance checking\n- **Browser Demo**: WebAssembly-based MCP in the browser\n\n### Testing & Validation\n\n```bash\n# Quick validation\nuv run examples/quickstart.py\n\n# Run comprehensive tests\nuv run examples/e2e_smoke_test_example.py --demo all\n\n# Validate installation scenarios\nuv run diagnostics/installation_scenarios_diagnostic.py\n\n# Test specific functionality\nuv run examples/e2e_smoke_test_example.py --smoke\n\n# Performance benchmarks\nuv run examples/e2e_smoke_test_example.py --performance\n```\n\n## Available MCP Servers\n\nThe MCP ecosystem includes servers for popular services:\n\n### \ud83d\ude80 Install with UV (Recommended)\n\n```bash\n# Popular Python servers\nuv tool install mcp-server-sqlite\nuv tool install mcp-server-github\nuv tool install mcp-server-postgres\n\n# Or run directly without installation\nuv run --with mcp-server-sqlite mcp-server-sqlite --db-path data.db\n```\n\n### \ud83d\udfe2 Node.js Servers\n\n```bash\n# Use npx for Node.js servers\nnpx -y @modelcontextprotocol/server-filesystem /path/to/files\nnpx -y @modelcontextprotocol/server-brave-search\n```\n\n### \ud83d\udcc1 Available Servers\n\n- **\ud83d\udcc1 Filesystem**: `@modelcontextprotocol/server-filesystem` \n- **\ud83d\uddc4\ufe0f SQLite**: `mcp-server-sqlite` \n- **\ud83d\udc19 GitHub**: `mcp-server-github`\n- **\u2601\ufe0f Google Drive**: `mcp-server-gdrive`\n- **\ud83d\udd0d Web Search**: `mcp-server-brave-search`\n- **\ud83d\udcca PostgreSQL**: `mcp-server-postgres`\n- **\ud83d\udcc8 Analytics**: Various data analytics servers\n- **\ud83d\udd27 Custom**: Build your own with the MCP SDK\n\nFind more at: [MCP Servers Directory](https://github.com/modelcontextprotocol/servers)\n\n## Building MCP Servers\n\nWant to create your own MCP server? Check out:\n\n- **Python**: [`mcp` package](https://pypi.org/project/mcp/)\n- **TypeScript**: [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk)\n- **Specification**: [MCP Protocol Documentation](https://spec.modelcontextprotocol.io/)\n\n## Performance & Monitoring\n\n`chuk-mcp` includes built-in performance monitoring:\n\n```python\nimport logging\n\n# Enable detailed logging for debugging\nlogging.basicConfig(level=logging.DEBUG)\n\n# Performance is optimized for:\n# - Concurrent server connections\n# - Efficient message routing \n# - Minimal memory allocation\n# - Fast JSON serialization\n```\n\n### \ud83d\udcc8 Performance Characteristics\n\n**Benchmarks (from smoke tests):**\n- **Connection Setup**: ~200ms (fast)\n- **Request Throughput**: >50 req/sec concurrent\n- **Memory Usage**: Minimal footprint\n- **Browser Performance**: <2s load time, instant operations\n\n**Performance Highlights:**\n- **\ud83d\ude80 Fast Startup**: < 1 second connection time\n- **\u26a1 High Throughput**: 50+ requests/second per connection\n- **\ud83d\udd04 Concurrent Operations**: Full async/await support\n- **\ud83d\udcbe Memory Efficient**: Minimal overhead per connection\n\n### Installation Performance Matrix\n\n| Installation | Startup Time | Validation Speed | Memory Usage | Dependencies |\n|-------------|-------------|------------------|--------------|--------------|\n| `chuk-mcp` | < 0.5s | 0.010ms/op | 15MB | Core only |\n| `chuk-mcp[pydantic]` | < 1.0s | 0.000ms/op | 25MB | + Pydantic |\n| `chuk-mcp[full]` | < 1.5s | 0.000ms/op | 35MB | All features |\n\n## Intelligent Dependency Management\n\n`chuk-mcp` includes intelligent dependency handling with graceful fallbacks:\n\n```python\n# Check validation backend\nfrom chuk_mcp.protocol.mcp_pydantic_base import PYDANTIC_AVAILABLE\n\nif PYDANTIC_AVAILABLE:\n print(\"\u2705 Using Pydantic for enhanced validation\")\n print(\" \u2022 Better error messages\")\n print(\" \u2022 Faster validation (Rust-based)\")\n print(\" \u2022 Advanced type coercion\")\nelse:\n print(\"\ud83d\udce6 Using lightweight fallback validation\")\n print(\" \u2022 Pure Python implementation\")\n print(\" \u2022 No external dependencies\")\n print(\" \u2022 ~20x slower but still fast\")\n\n# Force fallback mode for testing\nimport os\nos.environ[\"MCP_FORCE_FALLBACK\"] = \"1\"\n```\n\n## Development\n\n### Setup with UV\n\n```bash\ngit clone https://github.com/chrishayuk/chuk-mcp\ncd chuk-mcp\n\n# Install with development dependencies\nuv sync\n\n# Activate the virtual environment\nsource .venv/bin/activate # Linux/Mac\n# or .venv\\Scripts\\activate # Windows\n```\n\n### Traditional Setup\n\n```bash\n# Alternative setup with pip\npip install -e \".[dev]\"\n```\n\n### Development Features\n\n```bash\n# Test with fallback validation\nUV_MCP_FORCE_FALLBACK=1 uv run examples/quickstart.py\n\n# Test with different Python versions\nuv run --python 3.11 examples/quickstart.py\nuv run --python 3.12 examples/quickstart.py\n```\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for your changes\n4. Ensure all tests pass with `uv run diagnostics/installation_scenarios_diagnostic.py`\n5. Submit a pull request\n\n## UV Integration Features\n\n### Project Templates\n\n```bash\n# Start a new MCP client project\nuv init my-mcp-client\ncd my-mcp-client\n\n# Add chuk-mcp with dependencies\nuv add chuk-mcp[pydantic]\n\n# Add development tools\nuv add --dev pytest black isort\n\n# Create example\ncat > main.py << 'EOF'\nimport anyio\nfrom chuk_mcp import stdio_client, StdioServerParameters\n\nasync def main():\n # Your MCP client code here\n pass\n\nif __name__ == \"__main__\":\n anyio.run(main)\nEOF\n```\n\n### UV Scripts\n\nAdd to your `pyproject.toml`:\n\n```toml\n[tool.uv]\ndev-dependencies = [\n \"chuk-mcp[dev]\",\n]\n\n[project.scripts]\nmcp-client = \"my_mcp_client:main\"\n\n[tool.uv.scripts]\ntest-mcp = \"uv run examples/quickstart.py\"\nvalidate = \"uv run diagnostics/installation_scenarios_diagnostic.py\"\n```\n\n## \ud83c\udf96\ufe0f Production Readiness\n\n### \u2705 **Enterprise Features**\n- **Error Recovery**: Comprehensive error handling and retry logic\n- **Logging**: Structured logging with configurable levels \n- **Monitoring**: Built-in health checks and metrics\n- **Security**: Input validation and safe subprocess handling\n\n### \u2705 **Deployment Options**\n- **Standalone**: Direct process execution\n- **Containerized**: Docker-ready with minimal dependencies\n- **Browser**: Progressive Web App deployment via Pyodide\n- **Cloud**: Stateless operation suitable for serverless\n\n### \u2705 **Maintenance**\n- **Documentation**: Comprehensive examples and type hints\n- **Testing**: 100% working test coverage with real scenarios\n- **Migration Support**: Clear upgrade paths for new features\n\n## \ud83d\ude80 Future Roadmap\n\n### Near Term\n- **Additional Transports**: WebSocket, gRPC support\n- **Enhanced Tooling**: Visual debugger, protocol inspector\n- **Performance**: Further optimization for high-throughput scenarios\n\n### Long Term \n- **Protocol Extensions**: Custom capability negotiation\n- **Distributed MCP**: Multi-server orchestration\n- **Visual Builder**: GUI for MCP server development\n\n## Support & Community\n\n- **\ud83d\udcd6 Documentation**: [Full API Documentation](https://docs.example.com)\n- **\ud83d\udc1b Issues**: [GitHub Issues](https://github.com/chrishayuk/chuk-mcp/issues)\n- **\ud83d\udcac Discussions**: [GitHub Discussions](https://github.com/chrishayuk/chuk-mcp/discussions)\n- **\ud83d\udce7 Email**: For private inquiries\n- **\ud83d\ude80 UV**: [UV Package Manager](https://github.com/astral-sh/uv)\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built on the [Model Context Protocol](https://modelcontextprotocol.io/) specification\n- Inspired by the official [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)\n- Thanks to the MCP community for feedback and contributions\n- Special thanks to the [UV](https://github.com/astral-sh/uv) team for making Python package management fast and reliable\n\n---\n\n## \ud83c\udfc6 Summary\n\n**chuk-mcp** represents a **production-ready, comprehensive MCP implementation** that:\n\n- \u2705 **Implements comprehensive MCP protocol features** including latest 2025-06-18 capabilities\n- \u2705 **Provides clean, modern APIs** with intelligent fallback systems \n- \u2705 **Supports multiple transports** with a unified interface\n- \u2705 **Works everywhere** - server, desktop, and browser environments\n- \u2705 **Delivers enterprise-grade reliability** with comprehensive error handling\n- \u2705 **Enables innovation** through structured outputs and extensible architecture\n\nThis implementation sets a new standard for MCP libraries, being both **immediately practical** for production use and **forward-looking** for next-generation MCP applications.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Model Context Protocol Client with Optional Pydantic Support",
"version": "0.5.1",
"project_urls": {
"Bug Tracker": "https://github.com/chrishayuk/chuk-mcp/issues",
"Homepage": "https://github.com/chrishayuk/chuk-mcp",
"Repository": "https://github.com/chrishayuk/chuk-mcp"
},
"split_keywords": [
"llm",
" openai",
" claude",
" mcp",
" client",
" protocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a9ffe7037b5cbac95180f0dc45dac5617c24421631e9b9737a616a3a48a14794",
"md5": "969fcfeb92a73083cb4795e15664499f",
"sha256": "8a8926216f303059dccd6f3a9088f28058319baff0448812897d773da66a34d4"
},
"downloads": -1,
"filename": "chuk_mcp-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "969fcfeb92a73083cb4795e15664499f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 128317,
"upload_time": "2025-07-28T13:27:33",
"upload_time_iso_8601": "2025-07-28T13:27:33.485467Z",
"url": "https://files.pythonhosted.org/packages/a9/ff/e7037b5cbac95180f0dc45dac5617c24421631e9b9737a616a3a48a14794/chuk_mcp-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "822b71ddc6dc123426f92c06f62ff2400cd0d380b7e29f5e9f5277f43f0e6969",
"md5": "da6580cb8b693084ade7b9c1d5c9e47f",
"sha256": "ca29d99ac659e334b39e2d3740326da2c1dfbdc710a06d31c2ddae79f71e1268"
},
"downloads": -1,
"filename": "chuk_mcp-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "da6580cb8b693084ade7b9c1d5c9e47f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 105899,
"upload_time": "2025-07-28T13:27:34",
"upload_time_iso_8601": "2025-07-28T13:27:34.987983Z",
"url": "https://files.pythonhosted.org/packages/82/2b/71ddc6dc123426f92c06f62ff2400cd0d380b7e29f5e9f5277f43f0e6969/chuk_mcp-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 13:27:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "chrishayuk",
"github_project": "chuk-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "chuk-mcp"
}