Metadata-Version: 2.4
Name: mcp-commons
Version: 1.0.1
Summary: Shared infrastructure library for MCP (Model Context Protocol) servers
Author: MCP Commons Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/dawsonlp/mcp-commons
Project-URL: Repository, https://github.com/dawsonlp/mcp-commons.git
Project-URL: Documentation, https://github.com/dawsonlp/mcp-commons#readme
Project-URL: Issues, https://github.com/dawsonlp/mcp-commons/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.11.9
Requires-Dist: PyYAML>=6.0.3
Requires-Dist: mcp>=1.15.0
Provides-Extra: dev
Requires-Dist: pytest>=8.4.2; extra == "dev"
Requires-Dist: pytest-asyncio>=1.2.0; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Requires-Dist: black>=25.9.0; extra == "dev"
Requires-Dist: isort>=6.0.1; extra == "dev"
Requires-Dist: ruff>=0.13.2; extra == "dev"

# MCP Commons

A Python library that simplifies building MCP (Model Context Protocol) servers by providing reusable infrastructure and eliminating repetitive boilerplate code.

## Why MCP Commons?

Building MCP servers often requires writing the same patterns repeatedly:
- Converting your business logic to MCP-compatible formats
- Handling errors consistently across tools
- Registering multiple tools with similar patterns
- Testing MCP tool implementations

MCP Commons solves these problems by providing a clean adapter pattern and bulk registration utilities, letting you focus on your core logic instead of MCP plumbing.

## Key Features

🔧 **Smart Adapters** - Automatically convert your functions to MCP-compatible tools
📦 **Bulk Registration** - Register multiple tools at once with consistent patterns  
🛡️ **Type Safety** - Preserve function signatures and type hints
🧪 **Testing Support** - Built-in utilities for testing your MCP tools
⚡ **Zero Dependencies** - Minimal footprint, works with any MCP setup

## Installation

```bash
pip install mcp-commons
```

## Quick Start

### Basic Adapter Usage

Instead of manually wrapping every function for MCP compatibility:

```python
from mcp_commons import create_mcp_adapter, UseCaseResult
from mcp import Tool

# Your business logic
async def search_documents(query: str, limit: int = 10) -> UseCaseResult:
    # Your implementation here
    results = await document_service.search(query, limit)
    return UseCaseResult.success_with_data(results)

# Convert to MCP tool automatically
search_tool = Tool.from_function(
    create_mcp_adapter(search_documents), 
    name="search_documents"
)
```

### Bulk Registration

Register multiple related tools at once:

```python
from mcp_commons import bulk_register_tools

# Define your tools
tools_config = [
    ("list_projects", list_projects_use_case),
    ("create_project", create_project_use_case), 
    ("delete_project", delete_project_use_case),
]

# Register them all with consistent error handling
tools = bulk_register_tools(tools_config)
```

### Error Handling

The adapter automatically handles errors and provides consistent response formats:

```python
async def might_fail() -> UseCaseResult:
    try:
        result = await risky_operation()
        return UseCaseResult.success_with_data(result)
    except ValidationError as e:
        return UseCaseResult.failure(f"Invalid input: {e}")
    except Exception as e:
        return UseCaseResult.failure(f"Operation failed: {e}")

# Errors are automatically converted to proper MCP error responses
safe_tool = Tool.from_function(create_mcp_adapter(might_fail), name="safe_operation")
```

## Use Cases

- **Enterprise MCP Servers**: Standardize tool creation across multiple servers
- **Rapid Prototyping**: Quickly convert existing functions to MCP tools
- **Testing & Development**: Mock and test MCP tools without complex setup
- **Legacy Integration**: Adapt existing business logic to MCP without rewrites

## Documentation

- [API Reference](https://github.com/dawsonlp/mcp-commons/wiki)
- [Examples](https://github.com/dawsonlp/mcp-commons/tree/main/examples)
- [Contributing](https://github.com/dawsonlp/mcp-commons/blob/main/CONTRIBUTING.md)

## Requirements

- Python 3.11+ (Python 3.13 recommended for optimal performance)
- MCP SDK 1.15.0+
- Pydantic 2.11.9+
- PyYAML 6.0.3+

**Note**: This library has been updated with the latest dependency versions as of September 2025. All dependencies are compatible with Python 3.11-3.13.

## License

MIT License - see [LICENSE](LICENSE) for details.
