backend2mcp 0.1.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.
- backend2mcp-0.1.0/.github/workflows/publish.yml +35 -0
- backend2mcp-0.1.0/.github/workflows/tests.yml +54 -0
- backend2mcp-0.1.0/LICENSE +21 -0
- backend2mcp-0.1.0/MANIFEST.in +2 -0
- backend2mcp-0.1.0/PKG-INFO +322 -0
- backend2mcp-0.1.0/README.md +273 -0
- backend2mcp-0.1.0/backend2mcp/__init__.py +5 -0
- backend2mcp-0.1.0/backend2mcp/cli/__init__.py +119 -0
- backend2mcp-0.1.0/backend2mcp/core/__init__.py +38 -0
- backend2mcp-0.1.0/backend2mcp/core/adapter.py +134 -0
- backend2mcp-0.1.0/backend2mcp/core/auth.py +257 -0
- backend2mcp-0.1.0/backend2mcp/core/exceptions.py +31 -0
- backend2mcp-0.1.0/backend2mcp/core/schema.py +137 -0
- backend2mcp-0.1.0/backend2mcp/core/server.py +72 -0
- backend2mcp-0.1.0/backend2mcp/django/__init__.py +5 -0
- backend2mcp-0.1.0/backend2mcp/django/adapter.py +356 -0
- backend2mcp-0.1.0/backend2mcp/fastapi/__init__.py +5 -0
- backend2mcp-0.1.0/backend2mcp/fastapi/adapter.py +298 -0
- backend2mcp-0.1.0/backend2mcp/flask/__init__.py +5 -0
- backend2mcp-0.1.0/backend2mcp/flask/adapter.py +315 -0
- backend2mcp-0.1.0/docs/.nojekyll +2 -0
- backend2mcp-0.1.0/docs/_config.yml +17 -0
- backend2mcp-0.1.0/docs/index.html +659 -0
- backend2mcp-0.1.0/pyproject.toml +80 -0
- backend2mcp-0.1.0/tests/__init__.py +1 -0
- backend2mcp-0.1.0/tests/conftest.py +34 -0
- backend2mcp-0.1.0/tests/test_auth.py +246 -0
- backend2mcp-0.1.0/tests/test_cli.py +67 -0
- backend2mcp-0.1.0/tests/test_core.py +54 -0
- backend2mcp-0.1.0/tests/test_django.py +166 -0
- backend2mcp-0.1.0/tests/test_fastapi.py +286 -0
- backend2mcp-0.1.0/tests/test_flask.py +258 -0
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
name: Publish to PyPI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
release:
|
|
5
|
+
types: [created]
|
|
6
|
+
|
|
7
|
+
jobs:
|
|
8
|
+
publish:
|
|
9
|
+
runs-on: ubuntu-latest
|
|
10
|
+
permissions:
|
|
11
|
+
id-token: write
|
|
12
|
+
contents: read
|
|
13
|
+
steps:
|
|
14
|
+
- uses: actions/checkout@v4
|
|
15
|
+
with:
|
|
16
|
+
fetch-depth: 0
|
|
17
|
+
|
|
18
|
+
- name: Set up Python
|
|
19
|
+
uses: actions/setup-python@v5
|
|
20
|
+
with:
|
|
21
|
+
python-version: "3.12"
|
|
22
|
+
|
|
23
|
+
- name: Install dependencies
|
|
24
|
+
run: |
|
|
25
|
+
python -m pip install --upgrade pip
|
|
26
|
+
pip install build twine
|
|
27
|
+
|
|
28
|
+
- name: Build package
|
|
29
|
+
run: |
|
|
30
|
+
python -m build
|
|
31
|
+
|
|
32
|
+
- name: Publish to PyPI
|
|
33
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
34
|
+
with:
|
|
35
|
+
password: ${{ secrets.PYPI_API_TOKEN }}
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
name: Tests
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [main]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
test:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
strategy:
|
|
13
|
+
matrix:
|
|
14
|
+
python-version: ["3.11", "3.12", "3.13"]
|
|
15
|
+
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v4
|
|
18
|
+
|
|
19
|
+
- name: Set up Python ${{ matrix.python-version }}
|
|
20
|
+
uses: actions/setup-python@v5
|
|
21
|
+
with:
|
|
22
|
+
python-version: ${{ matrix.python-version }}
|
|
23
|
+
|
|
24
|
+
- name: Install dependencies
|
|
25
|
+
run: |
|
|
26
|
+
pip install -e ".[dev]"
|
|
27
|
+
|
|
28
|
+
- name: Run tests
|
|
29
|
+
run: |
|
|
30
|
+
pytest --cov=backend2mcp --cov-report=xml
|
|
31
|
+
|
|
32
|
+
- name: Upload coverage
|
|
33
|
+
uses: codecov/codecov-action@v4
|
|
34
|
+
with:
|
|
35
|
+
file: ./coverage.xml
|
|
36
|
+
fail_ci_if_error: false
|
|
37
|
+
|
|
38
|
+
typecheck:
|
|
39
|
+
runs-on: ubuntu-latest
|
|
40
|
+
steps:
|
|
41
|
+
- uses: actions/checkout@v4
|
|
42
|
+
|
|
43
|
+
- name: Set up Python
|
|
44
|
+
uses: actions/setup-python@v5
|
|
45
|
+
with:
|
|
46
|
+
python-version: "3.12"
|
|
47
|
+
|
|
48
|
+
- name: Install mypy
|
|
49
|
+
run: |
|
|
50
|
+
pip install mypy
|
|
51
|
+
|
|
52
|
+
- name: Run mypy
|
|
53
|
+
run: |
|
|
54
|
+
mypy backend2mcp
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 backend2mcp Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,322 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: backend2mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Convert any Python web backend into a fully functional MCP server automatically
|
|
5
|
+
Project-URL: homepage, https://github.com/SatyamSingh8306/backend2mcp
|
|
6
|
+
Project-URL: repository, https://github.com/SatyamSingh8306/backend2mcp
|
|
7
|
+
Author-email: backend2mcp Contributors <contributors@backend2mcp.dev>
|
|
8
|
+
License: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: django,fastapi,flask,mcp,model-context-protocol
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Framework :: AsyncIO
|
|
13
|
+
Classifier: Framework :: Django
|
|
14
|
+
Classifier: Framework :: FastAPI
|
|
15
|
+
Classifier: Framework :: Flask
|
|
16
|
+
Classifier: Intended Audience :: Developers
|
|
17
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Requires-Python: >=3.11
|
|
23
|
+
Requires-Dist: mcp>=1.1.2
|
|
24
|
+
Requires-Dist: pydantic>=2.10.0
|
|
25
|
+
Requires-Dist: typer>=0.14.0
|
|
26
|
+
Provides-Extra: dev
|
|
27
|
+
Requires-Dist: black>=24.10.0; extra == 'dev'
|
|
28
|
+
Requires-Dist: build>=1.0.0; extra == 'dev'
|
|
29
|
+
Requires-Dist: django>=5.2.0; extra == 'dev'
|
|
30
|
+
Requires-Dist: djangorestframework>=3.15.0; extra == 'dev'
|
|
31
|
+
Requires-Dist: fastapi>=0.115.0; extra == 'dev'
|
|
32
|
+
Requires-Dist: flask>=3.1.0; extra == 'dev'
|
|
33
|
+
Requires-Dist: httpx>=0.28.0; extra == 'dev'
|
|
34
|
+
Requires-Dist: isort>=5.13.0; extra == 'dev'
|
|
35
|
+
Requires-Dist: mypy>=1.14.0; extra == 'dev'
|
|
36
|
+
Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
|
|
37
|
+
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
|
|
38
|
+
Requires-Dist: pytest>=8.3.0; extra == 'dev'
|
|
39
|
+
Requires-Dist: twine>=5.0.0; extra == 'dev'
|
|
40
|
+
Provides-Extra: django
|
|
41
|
+
Requires-Dist: django>=5.2.0; extra == 'django'
|
|
42
|
+
Requires-Dist: djangorestframework>=3.15.0; extra == 'django'
|
|
43
|
+
Provides-Extra: fastapi
|
|
44
|
+
Requires-Dist: fastapi>=0.115.0; extra == 'fastapi'
|
|
45
|
+
Requires-Dist: uvicorn>=0.32.0; extra == 'fastapi'
|
|
46
|
+
Provides-Extra: flask
|
|
47
|
+
Requires-Dist: flask>=3.1.0; extra == 'flask'
|
|
48
|
+
Description-Content-Type: text/markdown
|
|
49
|
+
|
|
50
|
+
# backend2mcp
|
|
51
|
+
|
|
52
|
+
> Convert any Python web backend into a fully functional MCP (Model Context Protocol) server automatically, with near-zero developer boilerplate.
|
|
53
|
+
|
|
54
|
+
## What is this?
|
|
55
|
+
|
|
56
|
+
`backend2mcp` automatically exposes your existing Python web API routes as MCP tools. No HTTP servers, no proxies, no code generation—just import and run.
|
|
57
|
+
|
|
58
|
+
## Installation
|
|
59
|
+
|
|
60
|
+
Install the core package:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
pip install backend2mcp
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Install with framework support:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
pip install backend2mcp[fastapi] # FastAPI support
|
|
70
|
+
pip install backend2mcp[flask] # Flask support
|
|
71
|
+
pip install backend2mcp[django] # Django support
|
|
72
|
+
pip install backend2mcp[fastapi,flask] # Multiple frameworks
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Quickstart
|
|
76
|
+
|
|
77
|
+
### FastAPI
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
from fastapi import FastAPI
|
|
81
|
+
from backend2mcp.fastapi import MCPAdapter
|
|
82
|
+
|
|
83
|
+
app = FastAPI()
|
|
84
|
+
|
|
85
|
+
@app.get("/users/{id}")
|
|
86
|
+
async def get_user(id: int):
|
|
87
|
+
return {"id": id, "name": "Satyam"}
|
|
88
|
+
|
|
89
|
+
MCPAdapter(app).run()
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Flask
|
|
93
|
+
|
|
94
|
+
```python
|
|
95
|
+
from flask import Flask
|
|
96
|
+
from backend2mcp.flask import MCPAdapter
|
|
97
|
+
|
|
98
|
+
app = Flask(__name__)
|
|
99
|
+
|
|
100
|
+
@app.route("/users/<int:id>")
|
|
101
|
+
def get_user(id):
|
|
102
|
+
return {"id": id, "name": "Satyam"}
|
|
103
|
+
|
|
104
|
+
MCPAdapter(app).run()
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### Django
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
from django.urls import path
|
|
111
|
+
from backend2mcp.django import MCPAdapter
|
|
112
|
+
|
|
113
|
+
urlpatterns = [
|
|
114
|
+
path("users/<int:id>/", views.get_user),
|
|
115
|
+
]
|
|
116
|
+
|
|
117
|
+
MCPAdapter(urlpatterns=urlpatterns).run()
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## CLI Usage
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
# Auto-detect framework
|
|
124
|
+
backend2mcp run app:app
|
|
125
|
+
|
|
126
|
+
# Explicit framework
|
|
127
|
+
backend2mcp run app:app --framework fastapi
|
|
128
|
+
backend2mcp run app:app --framework flask
|
|
129
|
+
backend2mcp run app:app --framework django
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## Decorator Override
|
|
133
|
+
|
|
134
|
+
Customize tool behavior with `@mcp_tool`:
|
|
135
|
+
|
|
136
|
+
```python
|
|
137
|
+
from backend2mcp.fastapi import MCPAdapter, mcp_tool
|
|
138
|
+
|
|
139
|
+
app = FastAPI()
|
|
140
|
+
|
|
141
|
+
@app.get("/users/{id}")
|
|
142
|
+
@mcp_tool(
|
|
143
|
+
name="get_user",
|
|
144
|
+
description="Get a user by their ID",
|
|
145
|
+
hidden=False
|
|
146
|
+
)
|
|
147
|
+
async def get_user(id: int):
|
|
148
|
+
return {"id": id}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Tool Naming
|
|
152
|
+
|
|
153
|
+
Tools are auto-named using a consistent convention:
|
|
154
|
+
|
|
155
|
+
| Route | Tool Name |
|
|
156
|
+
|-------|-----------|
|
|
157
|
+
| `GET /users/{id}` | `get_by_id` |
|
|
158
|
+
| `POST /search` | `post_search` |
|
|
159
|
+
| `PUT /users/{id}` | `put_by_id` |
|
|
160
|
+
| `DELETE /users/{id}` | `delete_by_id` |
|
|
161
|
+
|
|
162
|
+
## Authentication
|
|
163
|
+
|
|
164
|
+
`backend2mcp` provides flexible authentication support through pluggable `AuthProvider` classes.
|
|
165
|
+
|
|
166
|
+
### No Authentication (Default)
|
|
167
|
+
|
|
168
|
+
Zero config, no auth required:
|
|
169
|
+
|
|
170
|
+
```python
|
|
171
|
+
adapter = MCPAdapter(app) # Works without auth
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
### Bearer Token Auth
|
|
175
|
+
|
|
176
|
+
```python
|
|
177
|
+
from backend2mcp.core import BearerAuthProvider
|
|
178
|
+
|
|
179
|
+
auth = BearerAuthProvider(
|
|
180
|
+
token_header="Authorization", # Header name
|
|
181
|
+
token_prefix="Bearer", # Token prefix
|
|
182
|
+
validate_tokens=["secret1", "secr2"] # Optional whitelist
|
|
183
|
+
)
|
|
184
|
+
adapter = MCPAdapter(app, auth_provider=auth)
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### API Key Auth
|
|
188
|
+
|
|
189
|
+
```python
|
|
190
|
+
from backend2mcp.core import APIKeyAuthProvider
|
|
191
|
+
|
|
192
|
+
auth = APIKeyAuthProvider(
|
|
193
|
+
header_name="X-API-Key", # Header name
|
|
194
|
+
query_param="api_key", # Query param name
|
|
195
|
+
valid_keys=["key1", "key2"] # Optional whitelist
|
|
196
|
+
)
|
|
197
|
+
adapter = MCPAdapter(app, auth_provider=auth)
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
### Custom Headers Injection
|
|
201
|
+
|
|
202
|
+
```python
|
|
203
|
+
from backend2mcp.core import HeaderInjectionAuthProvider
|
|
204
|
+
|
|
205
|
+
auth = HeaderInjectionAuthProvider(
|
|
206
|
+
static_headers={
|
|
207
|
+
"X-Custom-Header": "value",
|
|
208
|
+
"Authorization": "Bearer static-token"
|
|
209
|
+
}
|
|
210
|
+
)
|
|
211
|
+
adapter = MCPAdapter(app, auth_provider=auth)
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
### Combining Providers
|
|
215
|
+
|
|
216
|
+
```python
|
|
217
|
+
from backend2mcp.core import (
|
|
218
|
+
BearerAuthProvider,
|
|
219
|
+
APIKeyAuthProvider,
|
|
220
|
+
combine_providers
|
|
221
|
+
)
|
|
222
|
+
|
|
223
|
+
auth = combine_providers(
|
|
224
|
+
BearerAuthProvider(),
|
|
225
|
+
APIKeyAuthProvider()
|
|
226
|
+
)
|
|
227
|
+
adapter = MCPAdapter(app, auth_provider=auth)
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
### Accessing Auth in Handlers
|
|
231
|
+
|
|
232
|
+
Auth context is injected into handlers:
|
|
233
|
+
|
|
234
|
+
```python
|
|
235
|
+
from backend2mcp.fastapi import MCPAdapter
|
|
236
|
+
from backend2mcp.core import BearerAuthProvider, AuthContext
|
|
237
|
+
|
|
238
|
+
app = FastAPI()
|
|
239
|
+
auth = BearerAuthProvider()
|
|
240
|
+
|
|
241
|
+
@app.get("/users/{id}")
|
|
242
|
+
async def get_user(id: int, auth_context: AuthContext = None):
|
|
243
|
+
headers = auth_context.headers if auth_context else {}
|
|
244
|
+
user = get_user_from_db(id, headers=headers)
|
|
245
|
+
return user
|
|
246
|
+
|
|
247
|
+
adapter = MCPAdapter(app, auth_provider=auth)
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
## Architecture
|
|
251
|
+
|
|
252
|
+
```
|
|
253
|
+
backend2mcp/
|
|
254
|
+
├── core/ # Shared implementation
|
|
255
|
+
│ ├── adapter.py # BaseAdapter abstract interface
|
|
256
|
+
│ ├── auth.py # Auth providers (Bearer, API Key, etc.)
|
|
257
|
+
│ ├── server.py # MCP server implementation
|
|
258
|
+
│ ├── schema.py # Schema conversion utilities
|
|
259
|
+
│ └── exceptions.py # Structured exceptions
|
|
260
|
+
├── fastapi/ # FastAPI adapter
|
|
261
|
+
├── flask/ # Flask adapter
|
|
262
|
+
├── django/ # Django adapter
|
|
263
|
+
└── cli/ # Typer CLI
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
### Core Abstractions
|
|
267
|
+
|
|
268
|
+
- **`BaseAdapter`**: Abstract interface all framework adapters implement
|
|
269
|
+
- **`AuthProvider` / `AuthContext`**: Pluggable authentication system
|
|
270
|
+
- **`MCPServer`**: Handles MCP protocol using official `mcp` SDK
|
|
271
|
+
- **Tool Execution**: Direct handler invocation (no HTTP calls)
|
|
272
|
+
- **Schema Generation**: Pydantic-integrated JSON Schema extraction
|
|
273
|
+
|
|
274
|
+
## Writing a New Adapter
|
|
275
|
+
|
|
276
|
+
To add support for another framework:
|
|
277
|
+
|
|
278
|
+
1. Create `backend2mcp/framework/`
|
|
279
|
+
2. Implement `BaseAdapter` interface:
|
|
280
|
+
- `get_routes()` - Extract all routes from the framework
|
|
281
|
+
- `introspect_route()` - Convert a route to `ToolInfo`
|
|
282
|
+
- `execute_tool()` - Call handler with resolved arguments
|
|
283
|
+
- `build_tool_name()` - Generate MCP-safe tool names
|
|
284
|
+
3. Export `MCPAdapter` from the subpackage
|
|
285
|
+
|
|
286
|
+
```python
|
|
287
|
+
from backend2mcp.core.adapter import BaseAdapter, ToolInfo
|
|
288
|
+
|
|
289
|
+
class MCPAdapter(BaseAdapter):
|
|
290
|
+
def get_routes(self) -> list[tuple]:
|
|
291
|
+
# Your route extraction logic
|
|
292
|
+
pass
|
|
293
|
+
|
|
294
|
+
def introspect_route(self, path, method, handler, config) -> ToolInfo:
|
|
295
|
+
# Your schema extraction logic
|
|
296
|
+
pass
|
|
297
|
+
|
|
298
|
+
def execute_tool(self, handler, arguments, context=None):
|
|
299
|
+
# Your handler invocation logic
|
|
300
|
+
pass
|
|
301
|
+
|
|
302
|
+
def get_app(self):
|
|
303
|
+
# Return underlying framework object
|
|
304
|
+
pass
|
|
305
|
+
|
|
306
|
+
def build_tool_name(self, http_method, path):
|
|
307
|
+
# Your naming convention
|
|
308
|
+
pass
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
## Roadmap
|
|
312
|
+
|
|
313
|
+
| Phase | Frameworks |
|
|
314
|
+
|-------|------------|
|
|
315
|
+
| Phase 1 (this release) | FastAPI, Flask, Django |
|
|
316
|
+
| Phase 2 | Express, NestJS, Fastify |
|
|
317
|
+
| Phase 3 | Spring Boot, Quarkus |
|
|
318
|
+
| Phase 4 | Gin, Fiber, Echo |
|
|
319
|
+
|
|
320
|
+
## License
|
|
321
|
+
|
|
322
|
+
MIT
|
|
@@ -0,0 +1,273 @@
|
|
|
1
|
+
# backend2mcp
|
|
2
|
+
|
|
3
|
+
> Convert any Python web backend into a fully functional MCP (Model Context Protocol) server automatically, with near-zero developer boilerplate.
|
|
4
|
+
|
|
5
|
+
## What is this?
|
|
6
|
+
|
|
7
|
+
`backend2mcp` automatically exposes your existing Python web API routes as MCP tools. No HTTP servers, no proxies, no code generation—just import and run.
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
Install the core package:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
pip install backend2mcp
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Install with framework support:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
pip install backend2mcp[fastapi] # FastAPI support
|
|
21
|
+
pip install backend2mcp[flask] # Flask support
|
|
22
|
+
pip install backend2mcp[django] # Django support
|
|
23
|
+
pip install backend2mcp[fastapi,flask] # Multiple frameworks
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Quickstart
|
|
27
|
+
|
|
28
|
+
### FastAPI
|
|
29
|
+
|
|
30
|
+
```python
|
|
31
|
+
from fastapi import FastAPI
|
|
32
|
+
from backend2mcp.fastapi import MCPAdapter
|
|
33
|
+
|
|
34
|
+
app = FastAPI()
|
|
35
|
+
|
|
36
|
+
@app.get("/users/{id}")
|
|
37
|
+
async def get_user(id: int):
|
|
38
|
+
return {"id": id, "name": "Satyam"}
|
|
39
|
+
|
|
40
|
+
MCPAdapter(app).run()
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### Flask
|
|
44
|
+
|
|
45
|
+
```python
|
|
46
|
+
from flask import Flask
|
|
47
|
+
from backend2mcp.flask import MCPAdapter
|
|
48
|
+
|
|
49
|
+
app = Flask(__name__)
|
|
50
|
+
|
|
51
|
+
@app.route("/users/<int:id>")
|
|
52
|
+
def get_user(id):
|
|
53
|
+
return {"id": id, "name": "Satyam"}
|
|
54
|
+
|
|
55
|
+
MCPAdapter(app).run()
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Django
|
|
59
|
+
|
|
60
|
+
```python
|
|
61
|
+
from django.urls import path
|
|
62
|
+
from backend2mcp.django import MCPAdapter
|
|
63
|
+
|
|
64
|
+
urlpatterns = [
|
|
65
|
+
path("users/<int:id>/", views.get_user),
|
|
66
|
+
]
|
|
67
|
+
|
|
68
|
+
MCPAdapter(urlpatterns=urlpatterns).run()
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## CLI Usage
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
# Auto-detect framework
|
|
75
|
+
backend2mcp run app:app
|
|
76
|
+
|
|
77
|
+
# Explicit framework
|
|
78
|
+
backend2mcp run app:app --framework fastapi
|
|
79
|
+
backend2mcp run app:app --framework flask
|
|
80
|
+
backend2mcp run app:app --framework django
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## Decorator Override
|
|
84
|
+
|
|
85
|
+
Customize tool behavior with `@mcp_tool`:
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
from backend2mcp.fastapi import MCPAdapter, mcp_tool
|
|
89
|
+
|
|
90
|
+
app = FastAPI()
|
|
91
|
+
|
|
92
|
+
@app.get("/users/{id}")
|
|
93
|
+
@mcp_tool(
|
|
94
|
+
name="get_user",
|
|
95
|
+
description="Get a user by their ID",
|
|
96
|
+
hidden=False
|
|
97
|
+
)
|
|
98
|
+
async def get_user(id: int):
|
|
99
|
+
return {"id": id}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Tool Naming
|
|
103
|
+
|
|
104
|
+
Tools are auto-named using a consistent convention:
|
|
105
|
+
|
|
106
|
+
| Route | Tool Name |
|
|
107
|
+
|-------|-----------|
|
|
108
|
+
| `GET /users/{id}` | `get_by_id` |
|
|
109
|
+
| `POST /search` | `post_search` |
|
|
110
|
+
| `PUT /users/{id}` | `put_by_id` |
|
|
111
|
+
| `DELETE /users/{id}` | `delete_by_id` |
|
|
112
|
+
|
|
113
|
+
## Authentication
|
|
114
|
+
|
|
115
|
+
`backend2mcp` provides flexible authentication support through pluggable `AuthProvider` classes.
|
|
116
|
+
|
|
117
|
+
### No Authentication (Default)
|
|
118
|
+
|
|
119
|
+
Zero config, no auth required:
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
adapter = MCPAdapter(app) # Works without auth
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
### Bearer Token Auth
|
|
126
|
+
|
|
127
|
+
```python
|
|
128
|
+
from backend2mcp.core import BearerAuthProvider
|
|
129
|
+
|
|
130
|
+
auth = BearerAuthProvider(
|
|
131
|
+
token_header="Authorization", # Header name
|
|
132
|
+
token_prefix="Bearer", # Token prefix
|
|
133
|
+
validate_tokens=["secret1", "secr2"] # Optional whitelist
|
|
134
|
+
)
|
|
135
|
+
adapter = MCPAdapter(app, auth_provider=auth)
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### API Key Auth
|
|
139
|
+
|
|
140
|
+
```python
|
|
141
|
+
from backend2mcp.core import APIKeyAuthProvider
|
|
142
|
+
|
|
143
|
+
auth = APIKeyAuthProvider(
|
|
144
|
+
header_name="X-API-Key", # Header name
|
|
145
|
+
query_param="api_key", # Query param name
|
|
146
|
+
valid_keys=["key1", "key2"] # Optional whitelist
|
|
147
|
+
)
|
|
148
|
+
adapter = MCPAdapter(app, auth_provider=auth)
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### Custom Headers Injection
|
|
152
|
+
|
|
153
|
+
```python
|
|
154
|
+
from backend2mcp.core import HeaderInjectionAuthProvider
|
|
155
|
+
|
|
156
|
+
auth = HeaderInjectionAuthProvider(
|
|
157
|
+
static_headers={
|
|
158
|
+
"X-Custom-Header": "value",
|
|
159
|
+
"Authorization": "Bearer static-token"
|
|
160
|
+
}
|
|
161
|
+
)
|
|
162
|
+
adapter = MCPAdapter(app, auth_provider=auth)
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### Combining Providers
|
|
166
|
+
|
|
167
|
+
```python
|
|
168
|
+
from backend2mcp.core import (
|
|
169
|
+
BearerAuthProvider,
|
|
170
|
+
APIKeyAuthProvider,
|
|
171
|
+
combine_providers
|
|
172
|
+
)
|
|
173
|
+
|
|
174
|
+
auth = combine_providers(
|
|
175
|
+
BearerAuthProvider(),
|
|
176
|
+
APIKeyAuthProvider()
|
|
177
|
+
)
|
|
178
|
+
adapter = MCPAdapter(app, auth_provider=auth)
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### Accessing Auth in Handlers
|
|
182
|
+
|
|
183
|
+
Auth context is injected into handlers:
|
|
184
|
+
|
|
185
|
+
```python
|
|
186
|
+
from backend2mcp.fastapi import MCPAdapter
|
|
187
|
+
from backend2mcp.core import BearerAuthProvider, AuthContext
|
|
188
|
+
|
|
189
|
+
app = FastAPI()
|
|
190
|
+
auth = BearerAuthProvider()
|
|
191
|
+
|
|
192
|
+
@app.get("/users/{id}")
|
|
193
|
+
async def get_user(id: int, auth_context: AuthContext = None):
|
|
194
|
+
headers = auth_context.headers if auth_context else {}
|
|
195
|
+
user = get_user_from_db(id, headers=headers)
|
|
196
|
+
return user
|
|
197
|
+
|
|
198
|
+
adapter = MCPAdapter(app, auth_provider=auth)
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
## Architecture
|
|
202
|
+
|
|
203
|
+
```
|
|
204
|
+
backend2mcp/
|
|
205
|
+
├── core/ # Shared implementation
|
|
206
|
+
│ ├── adapter.py # BaseAdapter abstract interface
|
|
207
|
+
│ ├── auth.py # Auth providers (Bearer, API Key, etc.)
|
|
208
|
+
│ ├── server.py # MCP server implementation
|
|
209
|
+
│ ├── schema.py # Schema conversion utilities
|
|
210
|
+
│ └── exceptions.py # Structured exceptions
|
|
211
|
+
├── fastapi/ # FastAPI adapter
|
|
212
|
+
├── flask/ # Flask adapter
|
|
213
|
+
├── django/ # Django adapter
|
|
214
|
+
└── cli/ # Typer CLI
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
### Core Abstractions
|
|
218
|
+
|
|
219
|
+
- **`BaseAdapter`**: Abstract interface all framework adapters implement
|
|
220
|
+
- **`AuthProvider` / `AuthContext`**: Pluggable authentication system
|
|
221
|
+
- **`MCPServer`**: Handles MCP protocol using official `mcp` SDK
|
|
222
|
+
- **Tool Execution**: Direct handler invocation (no HTTP calls)
|
|
223
|
+
- **Schema Generation**: Pydantic-integrated JSON Schema extraction
|
|
224
|
+
|
|
225
|
+
## Writing a New Adapter
|
|
226
|
+
|
|
227
|
+
To add support for another framework:
|
|
228
|
+
|
|
229
|
+
1. Create `backend2mcp/framework/`
|
|
230
|
+
2. Implement `BaseAdapter` interface:
|
|
231
|
+
- `get_routes()` - Extract all routes from the framework
|
|
232
|
+
- `introspect_route()` - Convert a route to `ToolInfo`
|
|
233
|
+
- `execute_tool()` - Call handler with resolved arguments
|
|
234
|
+
- `build_tool_name()` - Generate MCP-safe tool names
|
|
235
|
+
3. Export `MCPAdapter` from the subpackage
|
|
236
|
+
|
|
237
|
+
```python
|
|
238
|
+
from backend2mcp.core.adapter import BaseAdapter, ToolInfo
|
|
239
|
+
|
|
240
|
+
class MCPAdapter(BaseAdapter):
|
|
241
|
+
def get_routes(self) -> list[tuple]:
|
|
242
|
+
# Your route extraction logic
|
|
243
|
+
pass
|
|
244
|
+
|
|
245
|
+
def introspect_route(self, path, method, handler, config) -> ToolInfo:
|
|
246
|
+
# Your schema extraction logic
|
|
247
|
+
pass
|
|
248
|
+
|
|
249
|
+
def execute_tool(self, handler, arguments, context=None):
|
|
250
|
+
# Your handler invocation logic
|
|
251
|
+
pass
|
|
252
|
+
|
|
253
|
+
def get_app(self):
|
|
254
|
+
# Return underlying framework object
|
|
255
|
+
pass
|
|
256
|
+
|
|
257
|
+
def build_tool_name(self, http_method, path):
|
|
258
|
+
# Your naming convention
|
|
259
|
+
pass
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
## Roadmap
|
|
263
|
+
|
|
264
|
+
| Phase | Frameworks |
|
|
265
|
+
|-------|------------|
|
|
266
|
+
| Phase 1 (this release) | FastAPI, Flask, Django |
|
|
267
|
+
| Phase 2 | Express, NestJS, Fastify |
|
|
268
|
+
| Phase 3 | Spring Boot, Quarkus |
|
|
269
|
+
| Phase 4 | Gin, Fiber, Echo |
|
|
270
|
+
|
|
271
|
+
## License
|
|
272
|
+
|
|
273
|
+
MIT
|