mcp-commons 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mcp_commons-1.0.0/PKG-INFO +139 -0
- mcp_commons-1.0.0/README.md +108 -0
- mcp_commons-1.0.0/pyproject.toml +93 -0
- mcp_commons-1.0.0/setup.cfg +4 -0
- mcp_commons-1.0.0/src/mcp_commons/__init__.py +61 -0
- mcp_commons-1.0.0/src/mcp_commons/adapters.py +315 -0
- mcp_commons-1.0.0/src/mcp_commons/base.py +182 -0
- mcp_commons-1.0.0/src/mcp_commons/bulk_registration.py +348 -0
- mcp_commons-1.0.0/src/mcp_commons/config.py +334 -0
- mcp_commons-1.0.0/src/mcp_commons/exceptions.py +80 -0
- mcp_commons-1.0.0/src/mcp_commons/server.py +272 -0
- mcp_commons-1.0.0/src/mcp_commons.egg-info/PKG-INFO +139 -0
- mcp_commons-1.0.0/src/mcp_commons.egg-info/SOURCES.txt +15 -0
- mcp_commons-1.0.0/src/mcp_commons.egg-info/dependency_links.txt +1 -0
- mcp_commons-1.0.0/src/mcp_commons.egg-info/requires.txt +11 -0
- mcp_commons-1.0.0/src/mcp_commons.egg-info/top_level.txt +1 -0
- mcp_commons-1.0.0/tests/test_adapters.py +303 -0
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: mcp-commons
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Shared infrastructure library for MCP (Model Context Protocol) servers
|
|
5
|
+
Author: MCP Commons Contributors
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/dawsonlp/mcp-commons
|
|
8
|
+
Project-URL: Repository, https://github.com/dawsonlp/mcp-commons.git
|
|
9
|
+
Project-URL: Documentation, https://github.com/dawsonlp/mcp-commons#readme
|
|
10
|
+
Project-URL: Issues, https://github.com/dawsonlp/mcp-commons/issues
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
18
|
+
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
|
|
19
|
+
Requires-Python: >=3.11
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
Requires-Dist: pydantic>=2.0.0
|
|
22
|
+
Requires-Dist: PyYAML>=6.0.0
|
|
23
|
+
Requires-Dist: mcp>=1.13.1
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Requires-Dist: pytest>=7.0.0; extra == "dev"
|
|
26
|
+
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
|
|
27
|
+
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
|
|
28
|
+
Requires-Dist: black>=23.0.0; extra == "dev"
|
|
29
|
+
Requires-Dist: isort>=5.0.0; extra == "dev"
|
|
30
|
+
Requires-Dist: ruff>=0.1.0; extra == "dev"
|
|
31
|
+
|
|
32
|
+
# MCP Commons
|
|
33
|
+
|
|
34
|
+
A Python library that simplifies building MCP (Model Context Protocol) servers by providing reusable infrastructure and eliminating repetitive boilerplate code.
|
|
35
|
+
|
|
36
|
+
## Why MCP Commons?
|
|
37
|
+
|
|
38
|
+
Building MCP servers often requires writing the same patterns repeatedly:
|
|
39
|
+
- Converting your business logic to MCP-compatible formats
|
|
40
|
+
- Handling errors consistently across tools
|
|
41
|
+
- Registering multiple tools with similar patterns
|
|
42
|
+
- Testing MCP tool implementations
|
|
43
|
+
|
|
44
|
+
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.
|
|
45
|
+
|
|
46
|
+
## Key Features
|
|
47
|
+
|
|
48
|
+
🔧 **Smart Adapters** - Automatically convert your functions to MCP-compatible tools
|
|
49
|
+
📦 **Bulk Registration** - Register multiple tools at once with consistent patterns
|
|
50
|
+
🛡️ **Type Safety** - Preserve function signatures and type hints
|
|
51
|
+
🧪 **Testing Support** - Built-in utilities for testing your MCP tools
|
|
52
|
+
⚡ **Zero Dependencies** - Minimal footprint, works with any MCP setup
|
|
53
|
+
|
|
54
|
+
## Installation
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
pip install mcp-commons
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Quick Start
|
|
61
|
+
|
|
62
|
+
### Basic Adapter Usage
|
|
63
|
+
|
|
64
|
+
Instead of manually wrapping every function for MCP compatibility:
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
from mcp_commons import create_mcp_adapter, UseCaseResult
|
|
68
|
+
from mcp import Tool
|
|
69
|
+
|
|
70
|
+
# Your business logic
|
|
71
|
+
async def search_documents(query: str, limit: int = 10) -> UseCaseResult:
|
|
72
|
+
# Your implementation here
|
|
73
|
+
results = await document_service.search(query, limit)
|
|
74
|
+
return UseCaseResult.success_with_data(results)
|
|
75
|
+
|
|
76
|
+
# Convert to MCP tool automatically
|
|
77
|
+
search_tool = Tool.from_function(
|
|
78
|
+
create_mcp_adapter(search_documents),
|
|
79
|
+
name="search_documents"
|
|
80
|
+
)
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### Bulk Registration
|
|
84
|
+
|
|
85
|
+
Register multiple related tools at once:
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
from mcp_commons import bulk_register_tools
|
|
89
|
+
|
|
90
|
+
# Define your tools
|
|
91
|
+
tools_config = [
|
|
92
|
+
("list_projects", list_projects_use_case),
|
|
93
|
+
("create_project", create_project_use_case),
|
|
94
|
+
("delete_project", delete_project_use_case),
|
|
95
|
+
]
|
|
96
|
+
|
|
97
|
+
# Register them all with consistent error handling
|
|
98
|
+
tools = bulk_register_tools(tools_config)
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### Error Handling
|
|
102
|
+
|
|
103
|
+
The adapter automatically handles errors and provides consistent response formats:
|
|
104
|
+
|
|
105
|
+
```python
|
|
106
|
+
async def might_fail() -> UseCaseResult:
|
|
107
|
+
try:
|
|
108
|
+
result = await risky_operation()
|
|
109
|
+
return UseCaseResult.success_with_data(result)
|
|
110
|
+
except ValidationError as e:
|
|
111
|
+
return UseCaseResult.failure(f"Invalid input: {e}")
|
|
112
|
+
except Exception as e:
|
|
113
|
+
return UseCaseResult.failure(f"Operation failed: {e}")
|
|
114
|
+
|
|
115
|
+
# Errors are automatically converted to proper MCP error responses
|
|
116
|
+
safe_tool = Tool.from_function(create_mcp_adapter(might_fail), name="safe_operation")
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## Use Cases
|
|
120
|
+
|
|
121
|
+
- **Enterprise MCP Servers**: Standardize tool creation across multiple servers
|
|
122
|
+
- **Rapid Prototyping**: Quickly convert existing functions to MCP tools
|
|
123
|
+
- **Testing & Development**: Mock and test MCP tools without complex setup
|
|
124
|
+
- **Legacy Integration**: Adapt existing business logic to MCP without rewrites
|
|
125
|
+
|
|
126
|
+
## Documentation
|
|
127
|
+
|
|
128
|
+
- [API Reference](https://github.com/dawsonlp/mcp-commons/wiki)
|
|
129
|
+
- [Examples](https://github.com/dawsonlp/mcp-commons/tree/main/examples)
|
|
130
|
+
- [Contributing](https://github.com/dawsonlp/mcp-commons/blob/main/CONTRIBUTING.md)
|
|
131
|
+
|
|
132
|
+
## Requirements
|
|
133
|
+
|
|
134
|
+
- Python 3.11+
|
|
135
|
+
- MCP SDK 1.13.1+
|
|
136
|
+
|
|
137
|
+
## License
|
|
138
|
+
|
|
139
|
+
MIT License - see [LICENSE](LICENSE) for details.
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# MCP Commons
|
|
2
|
+
|
|
3
|
+
A Python library that simplifies building MCP (Model Context Protocol) servers by providing reusable infrastructure and eliminating repetitive boilerplate code.
|
|
4
|
+
|
|
5
|
+
## Why MCP Commons?
|
|
6
|
+
|
|
7
|
+
Building MCP servers often requires writing the same patterns repeatedly:
|
|
8
|
+
- Converting your business logic to MCP-compatible formats
|
|
9
|
+
- Handling errors consistently across tools
|
|
10
|
+
- Registering multiple tools with similar patterns
|
|
11
|
+
- Testing MCP tool implementations
|
|
12
|
+
|
|
13
|
+
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.
|
|
14
|
+
|
|
15
|
+
## Key Features
|
|
16
|
+
|
|
17
|
+
🔧 **Smart Adapters** - Automatically convert your functions to MCP-compatible tools
|
|
18
|
+
📦 **Bulk Registration** - Register multiple tools at once with consistent patterns
|
|
19
|
+
🛡️ **Type Safety** - Preserve function signatures and type hints
|
|
20
|
+
🧪 **Testing Support** - Built-in utilities for testing your MCP tools
|
|
21
|
+
⚡ **Zero Dependencies** - Minimal footprint, works with any MCP setup
|
|
22
|
+
|
|
23
|
+
## Installation
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
pip install mcp-commons
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Quick Start
|
|
30
|
+
|
|
31
|
+
### Basic Adapter Usage
|
|
32
|
+
|
|
33
|
+
Instead of manually wrapping every function for MCP compatibility:
|
|
34
|
+
|
|
35
|
+
```python
|
|
36
|
+
from mcp_commons import create_mcp_adapter, UseCaseResult
|
|
37
|
+
from mcp import Tool
|
|
38
|
+
|
|
39
|
+
# Your business logic
|
|
40
|
+
async def search_documents(query: str, limit: int = 10) -> UseCaseResult:
|
|
41
|
+
# Your implementation here
|
|
42
|
+
results = await document_service.search(query, limit)
|
|
43
|
+
return UseCaseResult.success_with_data(results)
|
|
44
|
+
|
|
45
|
+
# Convert to MCP tool automatically
|
|
46
|
+
search_tool = Tool.from_function(
|
|
47
|
+
create_mcp_adapter(search_documents),
|
|
48
|
+
name="search_documents"
|
|
49
|
+
)
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### Bulk Registration
|
|
53
|
+
|
|
54
|
+
Register multiple related tools at once:
|
|
55
|
+
|
|
56
|
+
```python
|
|
57
|
+
from mcp_commons import bulk_register_tools
|
|
58
|
+
|
|
59
|
+
# Define your tools
|
|
60
|
+
tools_config = [
|
|
61
|
+
("list_projects", list_projects_use_case),
|
|
62
|
+
("create_project", create_project_use_case),
|
|
63
|
+
("delete_project", delete_project_use_case),
|
|
64
|
+
]
|
|
65
|
+
|
|
66
|
+
# Register them all with consistent error handling
|
|
67
|
+
tools = bulk_register_tools(tools_config)
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### Error Handling
|
|
71
|
+
|
|
72
|
+
The adapter automatically handles errors and provides consistent response formats:
|
|
73
|
+
|
|
74
|
+
```python
|
|
75
|
+
async def might_fail() -> UseCaseResult:
|
|
76
|
+
try:
|
|
77
|
+
result = await risky_operation()
|
|
78
|
+
return UseCaseResult.success_with_data(result)
|
|
79
|
+
except ValidationError as e:
|
|
80
|
+
return UseCaseResult.failure(f"Invalid input: {e}")
|
|
81
|
+
except Exception as e:
|
|
82
|
+
return UseCaseResult.failure(f"Operation failed: {e}")
|
|
83
|
+
|
|
84
|
+
# Errors are automatically converted to proper MCP error responses
|
|
85
|
+
safe_tool = Tool.from_function(create_mcp_adapter(might_fail), name="safe_operation")
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Use Cases
|
|
89
|
+
|
|
90
|
+
- **Enterprise MCP Servers**: Standardize tool creation across multiple servers
|
|
91
|
+
- **Rapid Prototyping**: Quickly convert existing functions to MCP tools
|
|
92
|
+
- **Testing & Development**: Mock and test MCP tools without complex setup
|
|
93
|
+
- **Legacy Integration**: Adapt existing business logic to MCP without rewrites
|
|
94
|
+
|
|
95
|
+
## Documentation
|
|
96
|
+
|
|
97
|
+
- [API Reference](https://github.com/dawsonlp/mcp-commons/wiki)
|
|
98
|
+
- [Examples](https://github.com/dawsonlp/mcp-commons/tree/main/examples)
|
|
99
|
+
- [Contributing](https://github.com/dawsonlp/mcp-commons/blob/main/CONTRIBUTING.md)
|
|
100
|
+
|
|
101
|
+
## Requirements
|
|
102
|
+
|
|
103
|
+
- Python 3.11+
|
|
104
|
+
- MCP SDK 1.13.1+
|
|
105
|
+
|
|
106
|
+
## License
|
|
107
|
+
|
|
108
|
+
MIT License - see [LICENSE](LICENSE) for details.
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "mcp-commons"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "Shared infrastructure library for MCP (Model Context Protocol) servers"
|
|
9
|
+
authors = [
|
|
10
|
+
{name = "MCP Commons Contributors"}
|
|
11
|
+
]
|
|
12
|
+
readme = "README.md"
|
|
13
|
+
license = "MIT"
|
|
14
|
+
requires-python = ">=3.11"
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 4 - Beta",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Programming Language :: Python :: 3",
|
|
19
|
+
"Programming Language :: Python :: 3.11",
|
|
20
|
+
"Programming Language :: Python :: 3.12",
|
|
21
|
+
"Programming Language :: Python :: 3.13",
|
|
22
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
23
|
+
"Topic :: Internet :: WWW/HTTP :: HTTP Servers",
|
|
24
|
+
]
|
|
25
|
+
dependencies = [
|
|
26
|
+
"pydantic>=2.0.0",
|
|
27
|
+
"PyYAML>=6.0.0",
|
|
28
|
+
"mcp>=1.13.1",
|
|
29
|
+
]
|
|
30
|
+
|
|
31
|
+
[project.optional-dependencies]
|
|
32
|
+
dev = [
|
|
33
|
+
"pytest>=7.0.0",
|
|
34
|
+
"pytest-asyncio>=0.21.0",
|
|
35
|
+
"pytest-cov>=4.0.0",
|
|
36
|
+
"black>=23.0.0",
|
|
37
|
+
"isort>=5.0.0",
|
|
38
|
+
"ruff>=0.1.0",
|
|
39
|
+
]
|
|
40
|
+
|
|
41
|
+
[project.urls]
|
|
42
|
+
Homepage = "https://github.com/dawsonlp/mcp-commons"
|
|
43
|
+
Repository = "https://github.com/dawsonlp/mcp-commons.git"
|
|
44
|
+
Documentation = "https://github.com/dawsonlp/mcp-commons#readme"
|
|
45
|
+
Issues = "https://github.com/dawsonlp/mcp-commons/issues"
|
|
46
|
+
|
|
47
|
+
[tool.setuptools.packages.find]
|
|
48
|
+
where = ["src"]
|
|
49
|
+
|
|
50
|
+
[tool.setuptools.package-dir]
|
|
51
|
+
"" = "src"
|
|
52
|
+
|
|
53
|
+
[tool.pytest.ini_options]
|
|
54
|
+
testpaths = ["tests"]
|
|
55
|
+
python_files = ["test_*.py"]
|
|
56
|
+
python_classes = ["Test*"]
|
|
57
|
+
python_functions = ["test_*"]
|
|
58
|
+
addopts = [
|
|
59
|
+
"--strict-markers",
|
|
60
|
+
"--strict-config",
|
|
61
|
+
"--cov=mcp_commons",
|
|
62
|
+
"--cov-report=term-missing",
|
|
63
|
+
"--cov-report=html",
|
|
64
|
+
]
|
|
65
|
+
|
|
66
|
+
[tool.black]
|
|
67
|
+
line-length = 88
|
|
68
|
+
target-version = ['py311']
|
|
69
|
+
include = '\.pyi?$'
|
|
70
|
+
|
|
71
|
+
[tool.isort]
|
|
72
|
+
profile = "black"
|
|
73
|
+
line_length = 88
|
|
74
|
+
multi_line_output = 3
|
|
75
|
+
|
|
76
|
+
[tool.ruff]
|
|
77
|
+
line-length = 88
|
|
78
|
+
target-version = "py311"
|
|
79
|
+
|
|
80
|
+
[tool.ruff.lint]
|
|
81
|
+
select = [
|
|
82
|
+
"E", # pycodestyle errors
|
|
83
|
+
"W", # pycodestyle warnings
|
|
84
|
+
"F", # pyflakes
|
|
85
|
+
"I", # isort
|
|
86
|
+
"B", # flake8-bugbear
|
|
87
|
+
"C4", # flake8-comprehensions
|
|
88
|
+
"UP", # pyupgrade
|
|
89
|
+
]
|
|
90
|
+
ignore = [
|
|
91
|
+
"E501", # line too long, handled by black
|
|
92
|
+
"B904", # raise from within except blocks - too strict for infrastructure code
|
|
93
|
+
]
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
"""
|
|
2
|
+
MCP Commons - Shared infrastructure for MCP servers.
|
|
3
|
+
|
|
4
|
+
This library provides reusable components for building MCP (Model Context Protocol) servers,
|
|
5
|
+
eliminating boilerplate and ensuring consistency across server implementations.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from .adapters import AdapterStats, create_mcp_adapter, validate_use_case_result
|
|
9
|
+
from .base import BaseUseCase, UseCaseResult
|
|
10
|
+
from .bulk_registration import (
|
|
11
|
+
BulkRegistrationError,
|
|
12
|
+
bulk_register_tools,
|
|
13
|
+
bulk_register_tuple_format,
|
|
14
|
+
bulk_register_with_adapter_pattern,
|
|
15
|
+
log_registration_summary,
|
|
16
|
+
register_tools,
|
|
17
|
+
validate_tools_config,
|
|
18
|
+
)
|
|
19
|
+
from .config import ConfigurationError, MCPConfig, create_config, load_dotenv_file
|
|
20
|
+
from .exceptions import AdapterError, McpCommonsError, UseCaseError
|
|
21
|
+
from .server import (
|
|
22
|
+
MCPServerBuilder,
|
|
23
|
+
create_mcp_app,
|
|
24
|
+
print_mcp_help,
|
|
25
|
+
run_mcp_server,
|
|
26
|
+
setup_logging,
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
__version__ = "1.0.0"
|
|
30
|
+
__all__ = [
|
|
31
|
+
# Core adapter functionality
|
|
32
|
+
"create_mcp_adapter",
|
|
33
|
+
"validate_use_case_result",
|
|
34
|
+
"AdapterStats",
|
|
35
|
+
# Base classes
|
|
36
|
+
"UseCaseResult",
|
|
37
|
+
"BaseUseCase",
|
|
38
|
+
# Bulk registration functionality
|
|
39
|
+
"bulk_register_tools",
|
|
40
|
+
"bulk_register_with_adapter_pattern",
|
|
41
|
+
"bulk_register_tuple_format",
|
|
42
|
+
"log_registration_summary",
|
|
43
|
+
"validate_tools_config",
|
|
44
|
+
"register_tools",
|
|
45
|
+
"BulkRegistrationError",
|
|
46
|
+
# Server utilities
|
|
47
|
+
"MCPServerBuilder",
|
|
48
|
+
"setup_logging",
|
|
49
|
+
"run_mcp_server",
|
|
50
|
+
"create_mcp_app",
|
|
51
|
+
"print_mcp_help",
|
|
52
|
+
# Configuration management
|
|
53
|
+
"MCPConfig",
|
|
54
|
+
"ConfigurationError",
|
|
55
|
+
"create_config",
|
|
56
|
+
"load_dotenv_file",
|
|
57
|
+
# Exceptions
|
|
58
|
+
"McpCommonsError",
|
|
59
|
+
"UseCaseError",
|
|
60
|
+
"AdapterError",
|
|
61
|
+
]
|