openapi-mcpforge 0.1.0__py3-none-any.whl
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.
- mcpforge/__init__.py +8 -0
- mcpforge/__main__.py +6 -0
- mcpforge/auth/__init__.py +28 -0
- mcpforge/auth/models.py +25 -0
- mcpforge/auth/providers.py +72 -0
- mcpforge/auth/redaction.py +47 -0
- mcpforge/auth/resolver.py +42 -0
- mcpforge/cli/__init__.py +1 -0
- mcpforge/cli/app.py +45 -0
- mcpforge/cli/commands/__init__.py +13 -0
- mcpforge/cli/commands/import_spec.py +41 -0
- mcpforge/cli/commands/init.py +42 -0
- mcpforge/cli/commands/inspect.py +56 -0
- mcpforge/cli/commands/run.py +44 -0
- mcpforge/cli/commands/serve.py +31 -0
- mcpforge/cli/commands/test.py +60 -0
- mcpforge/cli/commands/validate.py +41 -0
- mcpforge/cli/context.py +14 -0
- mcpforge/cli/output.py +31 -0
- mcpforge/cli/scaffold.py +71 -0
- mcpforge/config/__init__.py +37 -0
- mcpforge/config/loader.py +44 -0
- mcpforge/config/merger.py +25 -0
- mcpforge/config/models.py +182 -0
- mcpforge/config/secrets.py +94 -0
- mcpforge/domain/__init__.py +37 -0
- mcpforge/domain/enums.py +42 -0
- mcpforge/domain/errors.py +13 -0
- mcpforge/domain/models.py +142 -0
- mcpforge/domain/parameters.py +33 -0
- mcpforge/domain/schemas.py +6 -0
- mcpforge/execution/__init__.py +36 -0
- mcpforge/execution/client.py +55 -0
- mcpforge/execution/engine.py +199 -0
- mcpforge/execution/errors.py +83 -0
- mcpforge/execution/limits.py +31 -0
- mcpforge/execution/request_builder.py +87 -0
- mcpforge/execution/response.py +64 -0
- mcpforge/execution/retry.py +69 -0
- mcpforge/filtering/__init__.py +7 -0
- mcpforge/filtering/evaluator.py +26 -0
- mcpforge/filtering/policies.py +44 -0
- mcpforge/filtering/selectors.py +31 -0
- mcpforge/generation/__init__.py +19 -0
- mcpforge/generation/collisions.py +24 -0
- mcpforge/generation/descriptions.py +15 -0
- mcpforge/generation/input_schema.py +53 -0
- mcpforge/generation/models.py +32 -0
- mcpforge/generation/naming.py +54 -0
- mcpforge/generation/service.py +64 -0
- mcpforge/ingestion/__init__.py +26 -0
- mcpforge/ingestion/errors.py +23 -0
- mcpforge/ingestion/loaders/__init__.py +7 -0
- mcpforge/ingestion/loaders/file.py +48 -0
- mcpforge/ingestion/loaders/remote.py +83 -0
- mcpforge/ingestion/normalization/__init__.py +23 -0
- mcpforge/ingestion/normalization/operation.py +83 -0
- mcpforge/ingestion/normalization/parameters.py +119 -0
- mcpforge/ingestion/normalization/references.py +57 -0
- mcpforge/ingestion/normalization/schemas.py +76 -0
- mcpforge/ingestion/parsers/__init__.py +8 -0
- mcpforge/ingestion/parsers/base.py +14 -0
- mcpforge/ingestion/parsers/manual.py +82 -0
- mcpforge/ingestion/parsers/openapi.py +87 -0
- mcpforge/ingestion/parsers/swagger.py +95 -0
- mcpforge/ingestion/service.py +84 -0
- mcpforge/ingestion/source.py +50 -0
- mcpforge/mcp/__init__.py +39 -0
- mcpforge/mcp/adapter.py +88 -0
- mcpforge/mcp/errors.py +25 -0
- mcpforge/mcp/server.py +46 -0
- mcpforge/mcp/tools.py +110 -0
- mcpforge/mcp/transports.py +51 -0
- mcpforge/observability/__init__.py +23 -0
- mcpforge/observability/diagnostics.py +45 -0
- mcpforge/observability/events.py +58 -0
- mcpforge/observability/logging.py +45 -0
- mcpforge/runtime/__init__.py +15 -0
- mcpforge/runtime/application.py +82 -0
- mcpforge/runtime/dependencies.py +77 -0
- mcpforge/runtime/lifecycle.py +50 -0
- mcpforge/security/__init__.py +40 -0
- mcpforge/security/hosts.py +32 -0
- mcpforge/security/redaction.py +60 -0
- mcpforge/security/safety.py +39 -0
- mcpforge/security/ssrf.py +77 -0
- mcpforge/security/validation.py +36 -0
- openapi_mcpforge-0.1.0.dist-info/METADATA +1566 -0
- openapi_mcpforge-0.1.0.dist-info/RECORD +92 -0
- openapi_mcpforge-0.1.0.dist-info/WHEEL +4 -0
- openapi_mcpforge-0.1.0.dist-info/entry_points.txt +2 -0
- openapi_mcpforge-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,1566 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: openapi-mcpforge
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Turn any REST API into an AI-ready MCP server.
|
|
5
|
+
Author: MCPForge Contributors
|
|
6
|
+
License: Apache-2.0
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Requires-Python: >=3.11
|
|
9
|
+
Requires-Dist: httpx<1,>=0.27
|
|
10
|
+
Requires-Dist: mcp<2,>=1.0
|
|
11
|
+
Requires-Dist: pydantic<3,>=2.7
|
|
12
|
+
Requires-Dist: pyyaml<7,>=6
|
|
13
|
+
Requires-Dist: rich<14,>=13.7
|
|
14
|
+
Requires-Dist: typer<1,>=0.12
|
|
15
|
+
Provides-Extra: dev
|
|
16
|
+
Requires-Dist: mypy<2,>=1.10; extra == 'dev'
|
|
17
|
+
Requires-Dist: pytest-asyncio<1,>=0.23; extra == 'dev'
|
|
18
|
+
Requires-Dist: pytest-cov<6,>=5; extra == 'dev'
|
|
19
|
+
Requires-Dist: pytest<9,>=8.2; extra == 'dev'
|
|
20
|
+
Requires-Dist: respx<1,>=0.21; extra == 'dev'
|
|
21
|
+
Requires-Dist: ruff<1,>=0.5; extra == 'dev'
|
|
22
|
+
Requires-Dist: types-pyyaml<7,>=6; extra == 'dev'
|
|
23
|
+
Provides-Extra: test
|
|
24
|
+
Requires-Dist: pytest-asyncio<1,>=0.23; extra == 'test'
|
|
25
|
+
Requires-Dist: pytest-cov<6,>=5; extra == 'test'
|
|
26
|
+
Requires-Dist: pytest<9,>=8.2; extra == 'test'
|
|
27
|
+
Requires-Dist: respx<1,>=0.21; extra == 'test'
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
|
|
30
|
+
# ⚒️ MCPForge
|
|
31
|
+
|
|
32
|
+
**Turn Any REST API Into an AI-Ready MCP Server — Automatically, Securely, and Without Boilerplate.**
|
|
33
|
+
|
|
34
|
+
[](https://www.python.org/)
|
|
35
|
+
[](https://modelcontextprotocol.io/)
|
|
36
|
+
[](https://docs.pydantic.dev/)
|
|
37
|
+
[](https://www.python-httpx.org/)
|
|
38
|
+
[](LICENSE)
|
|
39
|
+
[](https://docs.astral.sh/ruff/)
|
|
40
|
+
[](https://mypy-lang.org/)
|
|
41
|
+
|
|
42
|
+
MCPForge transforms existing REST APIs into secure, typed Model Context Protocol
|
|
43
|
+
(MCP) servers. It reads OpenAPI 3.x, Swagger 2.0, or a simple developer-friendly
|
|
44
|
+
YAML configuration, normalizes it into a strongly typed internal model, generates
|
|
45
|
+
predictable MCP tools, and exposes those tools through local `stdio` or remote
|
|
46
|
+
`streamable-http` transports.
|
|
47
|
+
|
|
48
|
+
Instead of maintaining handwritten wrappers, duplicating validation schemas,
|
|
49
|
+
managing authentication separately, and rebuilding transport boilerplate, teams
|
|
50
|
+
can generate an AI-ready API integration in less than 60 seconds. MCPForge keeps
|
|
51
|
+
the normalized domain model independent of MCP and HTTP libraries, making the
|
|
52
|
+
system easier to test, extend, and maintain.
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## Table of Contents
|
|
57
|
+
|
|
58
|
+
- [The Problem vs. the MCPForge Solution](#the-problem-vs-the-mcpforge-solution)
|
|
59
|
+
- [Core Features](#core-features)
|
|
60
|
+
- [System Architecture](#system-architecture)
|
|
61
|
+
- [Installation](#installation)
|
|
62
|
+
- [60-Second Quickstart](#60-second-quickstart)
|
|
63
|
+
- [CLI Command Reference](#cli-command-reference)
|
|
64
|
+
- [Configuration and Manual API Specs](#configuration-and-manual-api-specs)
|
|
65
|
+
- [Connecting to AI Clients](#connecting-to-ai-clients)
|
|
66
|
+
- [Security Model and Guardrails](#security-model-and-guardrails)
|
|
67
|
+
- [Project Directory Structure](#project-directory-structure)
|
|
68
|
+
- [Development and Quality Checks](#development-and-quality-checks)
|
|
69
|
+
- [Roadmap](#roadmap)
|
|
70
|
+
- [License and Attribution](#license-and-attribution)
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## The Problem vs. the MCPForge Solution
|
|
75
|
+
|
|
76
|
+
### Before MCPForge
|
|
77
|
+
|
|
78
|
+
AI assistants cannot directly and safely call most REST APIs without a purpose-built
|
|
79
|
+
MCP integration. Teams traditionally need to:
|
|
80
|
+
|
|
81
|
+
- Read the API specification manually.
|
|
82
|
+
- Write endpoint-specific Python functions.
|
|
83
|
+
- Reimplement path, query, header, cookie, and JSON body mapping.
|
|
84
|
+
- Maintain duplicate Pydantic request models.
|
|
85
|
+
- Generate tool descriptions and names manually.
|
|
86
|
+
- Resolve authentication and secret sources safely.
|
|
87
|
+
- Implement SSRF and private-network protections.
|
|
88
|
+
- Normalize upstream errors for large-language-model recovery.
|
|
89
|
+
- Add retries, timeouts, response limits, redirects, and transport lifecycle logic.
|
|
90
|
+
- Maintain compatibility as the MCP SDK evolves.
|
|
91
|
+
- Rebuild similar boilerplate for every API and endpoint.
|
|
92
|
+
|
|
93
|
+
One API can become dozens of wrapper modules and still fail to scale as the API
|
|
94
|
+
changes.
|
|
95
|
+
|
|
96
|
+
### With MCPForge
|
|
97
|
+
|
|
98
|
+
```text
|
|
99
|
+
API specification or manual YAML
|
|
100
|
+
|
|
|
101
|
+
v
|
|
102
|
+
MCPForge ingest
|
|
103
|
+
|
|
|
104
|
+
v
|
|
105
|
+
Normalized API model
|
|
106
|
+
|
|
|
107
|
+
v
|
|
108
|
+
Typed, filtered MCP tools
|
|
109
|
+
|
|
|
110
|
+
v
|
|
111
|
+
stdio or streamable-http server
|
|
112
|
+
|
|
|
113
|
+
v
|
|
114
|
+
Secure AI-to-REST execution
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
MCPForge separates API parsing from MCP generation and HTTP execution:
|
|
118
|
+
|
|
119
|
+
```text
|
|
120
|
+
OpenAPI / Swagger / Manual YAML
|
|
121
|
+
│
|
|
122
|
+
▼
|
|
123
|
+
Parse + Normalize
|
|
124
|
+
│
|
|
125
|
+
▼
|
|
126
|
+
Filter + Safety Policy
|
|
127
|
+
│
|
|
128
|
+
▼
|
|
129
|
+
Generate MCP Tools
|
|
130
|
+
│
|
|
131
|
+
▼
|
|
132
|
+
Serve through MCP SDK
|
|
133
|
+
│
|
|
134
|
+
▼
|
|
135
|
+
Authenticate + Execute API
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
The result is a repeatable pipeline:
|
|
139
|
+
|
|
140
|
+
```text
|
|
141
|
+
mcpforge run ./openapi.yaml
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
That command can import the specification, validate the configuration and security
|
|
145
|
+
policy, generate deterministic tools, and launch a functioning MCP server with
|
|
146
|
+
no handwritten endpoint wrappers.
|
|
147
|
+
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
## Core Features
|
|
151
|
+
|
|
152
|
+
### Multi-Source API Ingestion
|
|
153
|
+
|
|
154
|
+
MCPForge accepts multiple API definition formats:
|
|
155
|
+
|
|
156
|
+
| Source | Supported Formats | Description |
|
|
157
|
+
|---|---|---|
|
|
158
|
+
| Local file | OpenAPI 3.0 JSON/YAML | Reads a specification from disk |
|
|
159
|
+
| Local file | OpenAPI 3.1 JSON/YAML | Supports modern JSON Schema features |
|
|
160
|
+
| Local file | Swagger 2.0 JSON/YAML | Converts Swagger operations into the normalized model |
|
|
161
|
+
| Remote URL | OpenAPI or Swagger | Downloads and validates a remote specification |
|
|
162
|
+
| Manual YAML | `mcpforge.yaml` | Describes APIs that lack an official specification |
|
|
163
|
+
|
|
164
|
+
The ingestion pipeline extracts:
|
|
165
|
+
|
|
166
|
+
- Base URLs and server definitions
|
|
167
|
+
- Paths and HTTP methods
|
|
168
|
+
- Operation identifiers
|
|
169
|
+
- Summaries and descriptions
|
|
170
|
+
- Tags
|
|
171
|
+
- Path parameters
|
|
172
|
+
- Query parameters
|
|
173
|
+
- Header and cookie parameters
|
|
174
|
+
- JSON request bodies
|
|
175
|
+
- Required and optional fields
|
|
176
|
+
- Response schemas
|
|
177
|
+
- Deprecated operations
|
|
178
|
+
- Operation metadata used by filtering and generation
|
|
179
|
+
|
|
180
|
+
### Decoupled Normalized Domain Model
|
|
181
|
+
|
|
182
|
+
Every parser emits the same Pydantic v2 model:
|
|
183
|
+
|
|
184
|
+
- `ApiDocument`
|
|
185
|
+
- `Endpoint`
|
|
186
|
+
- `Parameter`
|
|
187
|
+
- `RequestBody`
|
|
188
|
+
- `ResponseDefinition`
|
|
189
|
+
- `JsonSchema`
|
|
190
|
+
- `ToolDefinition`
|
|
191
|
+
|
|
192
|
+
Parsers never generate MCP tools directly. The core generator and execution engine
|
|
193
|
+
only receive normalized domain objects. This architectural boundary allows future
|
|
194
|
+
protocol adapters for GraphQL, gRPC, SOAP, or internal API registries without
|
|
195
|
+
rewriting HTTP execution, security, or CLI logic.
|
|
196
|
+
|
|
197
|
+
```text
|
|
198
|
+
OpenAPIParser ─┐
|
|
199
|
+
SwaggerParser ─┼──> ApiDocument ──> ToolGenerator
|
|
200
|
+
ManualParser ──┘
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
### Deterministic Tool Generation
|
|
204
|
+
|
|
205
|
+
MCPForge generates clean MCP-compatible tool names, for example:
|
|
206
|
+
|
|
207
|
+
| REST Operation | Generated Tool |
|
|
208
|
+
|---|---|
|
|
209
|
+
| `GET /users/{id}` | `get_user` |
|
|
210
|
+
| `POST /orders` | `create_order` |
|
|
211
|
+
| `GET /users/{id}/projects` | `get_user_projects` |
|
|
212
|
+
| `DELETE /sessions/{id}` | `delete_session` |
|
|
213
|
+
|
|
214
|
+
Tool generation provides:
|
|
215
|
+
|
|
216
|
+
- Deterministic `snake_case` names
|
|
217
|
+
- Stable collision suffixing
|
|
218
|
+
- Operation-ID-aware naming
|
|
219
|
+
- Path and HTTP-method fallback naming
|
|
220
|
+
- Manual name overrides
|
|
221
|
+
- Manual description overrides
|
|
222
|
+
- Strict JSON input schemas
|
|
223
|
+
- Required/optional field definitions
|
|
224
|
+
- Nested request body support
|
|
225
|
+
- Parameter-location metadata
|
|
226
|
+
- Deprecated endpoint filtering
|
|
227
|
+
- Collision and ambiguous-name reporting
|
|
228
|
+
|
|
229
|
+
### Enterprise Security by Default
|
|
230
|
+
|
|
231
|
+
Safe behavior is the default:
|
|
232
|
+
|
|
233
|
+
- `GET`, `HEAD`, and `OPTIONS` may be exposed for read operations.
|
|
234
|
+
- `POST`, `PUT`, and `PATCH` require explicit write enablement.
|
|
235
|
+
- `DELETE` requires explicit delete enablement.
|
|
236
|
+
- Private, loopback, and link-local addresses are blocked.
|
|
237
|
+
- DNS resolutions are checked before and where possible during connection.
|
|
238
|
+
- Redirect targets are subject to the same network policy.
|
|
239
|
+
- `allowed_hosts` can restrict requests to explicit hostnames.
|
|
240
|
+
- Literal credentials are rejected from project configuration.
|
|
241
|
+
- Secrets are resolved only when a request is executed.
|
|
242
|
+
- Authorization, API keys, cookies, and static headers are redacted recursively.
|
|
243
|
+
|
|
244
|
+
### Zero-Leak Authentication
|
|
245
|
+
|
|
246
|
+
MCPForge supports:
|
|
247
|
+
|
|
248
|
+
- Bearer tokens
|
|
249
|
+
- API keys in custom headers
|
|
250
|
+
- API keys in query parameters
|
|
251
|
+
- HTTP Basic authentication
|
|
252
|
+
- Custom static headers
|
|
253
|
+
- Environment-variable-only runtime resolution
|
|
254
|
+
|
|
255
|
+
Credentials are not included in:
|
|
256
|
+
|
|
257
|
+
- YAML specifications
|
|
258
|
+
- Tool descriptions
|
|
259
|
+
- MCP schemas
|
|
260
|
+
- Terminal logs
|
|
261
|
+
- Debug messages
|
|
262
|
+
- HTTP exception text
|
|
263
|
+
- Structured API errors
|
|
264
|
+
- AI-visible tool responses
|
|
265
|
+
|
|
266
|
+
### Resilient Async Execution
|
|
267
|
+
|
|
268
|
+
The execution engine uses:
|
|
269
|
+
|
|
270
|
+
- A shared, lifecycle-managed `httpx.AsyncClient`
|
|
271
|
+
- Configurable connect and read timeouts
|
|
272
|
+
- Optional transient retry policies
|
|
273
|
+
- Exponential backoff
|
|
274
|
+
- Configurable maximum attempts
|
|
275
|
+
- TLS verification controls
|
|
276
|
+
- Redirect handling
|
|
277
|
+
- JSON body construction
|
|
278
|
+
- Query, path, header, and cookie mapping
|
|
279
|
+
- Maximum response payload limits
|
|
280
|
+
- Structured HTTP and network errors
|
|
281
|
+
|
|
282
|
+
Examples of normalized failure categories include:
|
|
283
|
+
|
|
284
|
+
- `validation_error`
|
|
285
|
+
- `authentication_failed`
|
|
286
|
+
- `authorization_failed`
|
|
287
|
+
- `not_found`
|
|
288
|
+
- `rate_limited`
|
|
289
|
+
- `upstream_unavailable`
|
|
290
|
+
- `timeout`
|
|
291
|
+
- `network_error`
|
|
292
|
+
- `invalid_json`
|
|
293
|
+
- `response_too_large`
|
|
294
|
+
- `host_blocked`
|
|
295
|
+
- `retry_exhausted`
|
|
296
|
+
|
|
297
|
+
### Dual MCP Transports
|
|
298
|
+
|
|
299
|
+
MCPForge is designed for both local and remote usage:
|
|
300
|
+
|
|
301
|
+
- **stdio:** ideal for Claude Desktop, Cursor, Windsurf, and local VS Code MCP clients
|
|
302
|
+
- **streamable-http:** suitable for remote deployments and centrally managed MCP gateways
|
|
303
|
+
|
|
304
|
+
The MCP SDK remains isolated behind an adapter layer. The domain model, tool
|
|
305
|
+
generator, authentication providers, and HTTP execution engine never depend on
|
|
306
|
+
SDK-specific classes.
|
|
307
|
+
|
|
308
|
+
---
|
|
309
|
+
|
|
310
|
+
## System Architecture
|
|
311
|
+
|
|
312
|
+
```text
|
|
313
|
+
┌──────────────────────────────────────────────────────────────────────┐
|
|
314
|
+
│ MCPForge Pipeline │
|
|
315
|
+
└──────────────────────────────────────────────────────────────────────┘
|
|
316
|
+
|
|
317
|
+
OpenAPI 3.x ──┐
|
|
318
|
+
Swagger 2.0 ──┼──> Source Loaders
|
|
319
|
+
Manual YAML ──┘ │
|
|
320
|
+
v
|
|
321
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
322
|
+
│ Local / Remote Ingestion + Format Detection + Schema Normalization │
|
|
323
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
324
|
+
│
|
|
325
|
+
v
|
|
326
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
327
|
+
│ Unified Pydantic Domain Model │
|
|
328
|
+
│ ApiDocument -> Endpoint -> Parameter -> RequestBody -> Responses │
|
|
329
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
330
|
+
│
|
|
331
|
+
v
|
|
332
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
333
|
+
│ Filter + Deprecated + Tag + Path + Method + Safety Policies │
|
|
334
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
335
|
+
│
|
|
336
|
+
v
|
|
337
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
338
|
+
│ Tool Generation: Naming, Overrides, Collisions, Input JSON Schemas │
|
|
339
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
340
|
+
│
|
|
341
|
+
v
|
|
342
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
343
|
+
│ MCP SDK Adapter + Stdio or Streamable HTTP Transport │
|
|
344
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
345
|
+
│
|
|
346
|
+
v
|
|
347
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
348
|
+
│ Argument Mapping -> Authentication -> SSRF -> HTTP Retry / Limits │
|
|
349
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
350
|
+
│
|
|
351
|
+
v
|
|
352
|
+
Upstream REST API
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
### Module Responsibilities
|
|
356
|
+
|
|
357
|
+
| Module | Responsibility |
|
|
358
|
+
|---|---|
|
|
359
|
+
| `domain` | Pure Pydantic contracts shared by all internal modules |
|
|
360
|
+
| `config` | YAML/JSON loading, merging, validation, and environment references |
|
|
361
|
+
| `ingestion` | Source loading, format detection, parsing, and normalization |
|
|
362
|
+
| `filtering` | Endpoint allowlists, blocklists, tags, methods, and deprecated handling |
|
|
363
|
+
| `generation` | Tool names, descriptions, JSON schemas, and collision resolution |
|
|
364
|
+
| `auth` | Environment-backed authentication providers and credential resolution |
|
|
365
|
+
| `execution` | HTTP request construction, retries, response parsing, and normalized errors |
|
|
366
|
+
| `security` | Operation safety, SSRF protection, host policy, validation, and redaction |
|
|
367
|
+
| `mcp` | MCP SDK adapter and both transport implementations |
|
|
368
|
+
| `runtime` | Dependency composition and shared application lifecycle |
|
|
369
|
+
| `observability` | Redacted structured logging and diagnostics |
|
|
370
|
+
| `cli` | Terminal commands, argument handling, and Rich output |
|
|
371
|
+
|
|
372
|
+
The dependency direction remains one-way:
|
|
373
|
+
|
|
374
|
+
```text
|
|
375
|
+
cli -> runtime -> generation/filtering/execution
|
|
376
|
+
|
|
|
377
|
+
v
|
|
378
|
+
config -> ingestion -> domain
|
|
379
|
+
security -----------------^
|
|
380
|
+
mcp ----------------------^
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
The `domain` package must not import Typer, Rich, HTTPX, PyYAML, or the MCP SDK.
|
|
384
|
+
|
|
385
|
+
---
|
|
386
|
+
|
|
387
|
+
## Installation
|
|
388
|
+
|
|
389
|
+
### Requirements
|
|
390
|
+
|
|
391
|
+
- Python 3.11 or newer
|
|
392
|
+
- An MCP-compatible client for local usage
|
|
393
|
+
- Network access to the upstream API, if remote API testing is required
|
|
394
|
+
|
|
395
|
+
### Install with pip
|
|
396
|
+
|
|
397
|
+
```bash
|
|
398
|
+
python -m pip install mcpforge
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
For an isolated environment:
|
|
402
|
+
|
|
403
|
+
```bash
|
|
404
|
+
python -m venv .venv
|
|
405
|
+
source .venv/bin/activate
|
|
406
|
+
python -m pip install mcpforge
|
|
407
|
+
mcpforge --help
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
On Windows:
|
|
411
|
+
|
|
412
|
+
```powershell
|
|
413
|
+
python -m venv .venv
|
|
414
|
+
.venv\Scripts\Activate.ps1
|
|
415
|
+
python -m pip install mcpforge
|
|
416
|
+
mcpforge --help
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
### Install with uv
|
|
420
|
+
|
|
421
|
+
```bash
|
|
422
|
+
uv tool install mcpforge
|
|
423
|
+
mcpforge --help
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
For a project environment:
|
|
427
|
+
|
|
428
|
+
```bash
|
|
429
|
+
uv venv
|
|
430
|
+
source .venv/bin/activate
|
|
431
|
+
uv pip install mcpforge
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
### Install from source
|
|
435
|
+
|
|
436
|
+
```bash
|
|
437
|
+
git clone https://github.com/AshishVail/mcpforge.git
|
|
438
|
+
cd mcpforge
|
|
439
|
+
python -m venv .venv
|
|
440
|
+
source .venv/bin/activate
|
|
441
|
+
python -m pip install -e ".[dev]"
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
Verify the installation:
|
|
445
|
+
|
|
446
|
+
```bash
|
|
447
|
+
mcpforge --version
|
|
448
|
+
mcpforge --help
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
---
|
|
452
|
+
|
|
453
|
+
## 60-Second Quickstart
|
|
454
|
+
|
|
455
|
+
### 1. Create a project
|
|
456
|
+
|
|
457
|
+
```bash
|
|
458
|
+
mkdir inventory-api && cd inventory-api
|
|
459
|
+
mcpforge init
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
This creates a starter `mcpforge.yaml` and supporting environment template.
|
|
463
|
+
|
|
464
|
+
### 2. Add environment-backed secrets
|
|
465
|
+
|
|
466
|
+
```bash
|
|
467
|
+
cp .env.example .env
|
|
468
|
+
export MCPFORGE_API_TOKEN="replace-with-your-token"
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
Never paste a token directly into `mcpforge.yaml`.
|
|
472
|
+
|
|
473
|
+
### 3. Import an API specification
|
|
474
|
+
|
|
475
|
+
Remote URL:
|
|
476
|
+
|
|
477
|
+
```bash
|
|
478
|
+
mcpforge import https://api.example.com/openapi.json
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
Local file:
|
|
482
|
+
|
|
483
|
+
```bash
|
|
484
|
+
mcpforge import ./openapi.yaml
|
|
485
|
+
```
|
|
486
|
+
|
|
487
|
+
Swagger 2.0:
|
|
488
|
+
|
|
489
|
+
```bash
|
|
490
|
+
mcpforge import ./swagger.yaml --format swagger
|
|
491
|
+
```
|
|
492
|
+
|
|
493
|
+
Manual configuration:
|
|
494
|
+
|
|
495
|
+
```bash
|
|
496
|
+
mcpforge import ./mcpforge.yaml --format manual
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
### 4. Inspect the generated tools
|
|
500
|
+
|
|
501
|
+
```bash
|
|
502
|
+
mcpforge inspect
|
|
503
|
+
```
|
|
504
|
+
|
|
505
|
+
Example output:
|
|
506
|
+
|
|
507
|
+
```text
|
|
508
|
+
┌───────┬────────────────────────┬───────────────┬──────────────┐
|
|
509
|
+
│ Method│ Path │ Tool Name │ Safety │
|
|
510
|
+
├───────┼────────────────────────┼───────────────┼──────────────┤
|
|
511
|
+
│ GET │ /users/{id} │ get_user │ read │
|
|
512
|
+
│ GET │ /users │ list_users │ read │
|
|
513
|
+
│ POST │ /orders │ create_order │ write │
|
|
514
|
+
└───────┴────────────────────────┴───────────────┴──────────────┘
|
|
515
|
+
```
|
|
516
|
+
|
|
517
|
+
### 5. Validate configuration and security
|
|
518
|
+
|
|
519
|
+
```bash
|
|
520
|
+
mcpforge validate
|
|
521
|
+
```
|
|
522
|
+
|
|
523
|
+
The validation pass checks:
|
|
524
|
+
|
|
525
|
+
- YAML/JSON syntax
|
|
526
|
+
- Pydantic configuration models
|
|
527
|
+
- Source availability
|
|
528
|
+
- Schema validity
|
|
529
|
+
- Authentication references
|
|
530
|
+
- Write/delete policy
|
|
531
|
+
- Deprecated operations
|
|
532
|
+
- Host and SSRF policy
|
|
533
|
+
- Tool-name collisions
|
|
534
|
+
- Required environment variables
|
|
535
|
+
|
|
536
|
+
### 6. Test upstream connectivity
|
|
537
|
+
|
|
538
|
+
```bash
|
|
539
|
+
mcpforge test
|
|
540
|
+
```
|
|
541
|
+
|
|
542
|
+
Expected output:
|
|
543
|
+
|
|
544
|
+
```text
|
|
545
|
+
✓ Configuration loaded
|
|
546
|
+
✓ Authentication resolved
|
|
547
|
+
✓ API host allowed
|
|
548
|
+
✓ Connectivity successful
|
|
549
|
+
✓ Upstream returned a valid response
|
|
550
|
+
```
|
|
551
|
+
|
|
552
|
+
### 7. Start a local MCP server
|
|
553
|
+
|
|
554
|
+
```bash
|
|
555
|
+
mcpforge serve --transport stdio
|
|
556
|
+
```
|
|
557
|
+
|
|
558
|
+
To start the remote HTTP transport:
|
|
559
|
+
|
|
560
|
+
```bash
|
|
561
|
+
mcpforge serve --transport streamable-http --host 127.0.0.1 --port 8080
|
|
562
|
+
```
|
|
563
|
+
|
|
564
|
+
Streamable HTTP endpoint:
|
|
565
|
+
|
|
566
|
+
```text
|
|
567
|
+
http://127.0.0.1:8080/mcp
|
|
568
|
+
```
|
|
569
|
+
|
|
570
|
+
### 8. Use the one-command workflow
|
|
571
|
+
|
|
572
|
+
```bash
|
|
573
|
+
mcpforge run ./openapi.yaml
|
|
574
|
+
```
|
|
575
|
+
|
|
576
|
+
With remote OpenAPI:
|
|
577
|
+
|
|
578
|
+
```bash
|
|
579
|
+
mcpforge run https://api.example.com/openapi.json --transport stdio
|
|
580
|
+
```
|
|
581
|
+
|
|
582
|
+
With HTTP transport:
|
|
583
|
+
|
|
584
|
+
```bash
|
|
585
|
+
mcpforge run ./openapi.yaml \
|
|
586
|
+
--transport streamable-http \
|
|
587
|
+
--host 0.0.0.0 \
|
|
588
|
+
--port 8080
|
|
589
|
+
```
|
|
590
|
+
|
|
591
|
+
---
|
|
592
|
+
|
|
593
|
+
## CLI Command Reference
|
|
594
|
+
|
|
595
|
+
### `mcpforge init`
|
|
596
|
+
|
|
597
|
+
Scaffold a new MCPForge project.
|
|
598
|
+
|
|
599
|
+
```bash
|
|
600
|
+
mcpforge init
|
|
601
|
+
mcpforge init ./my-api
|
|
602
|
+
mcpforge init --force
|
|
603
|
+
mcpforge init --with-example
|
|
604
|
+
```
|
|
605
|
+
|
|
606
|
+
| Option | Description |
|
|
607
|
+
|---|---|
|
|
608
|
+
| `PATH` | Target project directory |
|
|
609
|
+
| `--force` | Replace existing project files after confirmation |
|
|
610
|
+
| `--with-example` | Include an example OpenAPI and environment file |
|
|
611
|
+
| `--config-name TEXT` | Custom configuration filename |
|
|
612
|
+
|
|
613
|
+
Creates:
|
|
614
|
+
|
|
615
|
+
```text
|
|
616
|
+
my-api/
|
|
617
|
+
├── mcpforge.yaml
|
|
618
|
+
├── .env.example
|
|
619
|
+
└── examples/
|
|
620
|
+
└── petstore.openapi.yaml
|
|
621
|
+
```
|
|
622
|
+
|
|
623
|
+
### `mcpforge import`
|
|
624
|
+
|
|
625
|
+
Load and normalize an API specification.
|
|
626
|
+
|
|
627
|
+
```bash
|
|
628
|
+
mcpforge import ./openapi.yaml
|
|
629
|
+
mcpforge import ./swagger.json --format swagger
|
|
630
|
+
mcpforge import https://api.example.com/openapi.json
|
|
631
|
+
mcpforge import ./manual.yaml --format manual --save
|
|
632
|
+
```
|
|
633
|
+
|
|
634
|
+
| Option | Description |
|
|
635
|
+
|---|---|
|
|
636
|
+
| `<source>` | Local path or remote URL |
|
|
637
|
+
| `--format [openapi|swagger|manual]` | Explicit source format |
|
|
638
|
+
| `--save / --no-save` | Persist normalized project metadata |
|
|
639
|
+
| `--base-url TEXT` | Override a specification's server URL |
|
|
640
|
+
| `--config PATH` | Use a specific project configuration |
|
|
641
|
+
|
|
642
|
+
### `mcpforge inspect`
|
|
643
|
+
|
|
644
|
+
Display discovered endpoints and generated tool names.
|
|
645
|
+
|
|
646
|
+
```bash
|
|
647
|
+
mcpforge inspect
|
|
648
|
+
mcpforge inspect --methods GET
|
|
649
|
+
mcpforge inspect --tag users
|
|
650
|
+
mcpforge inspect --include-deprecated
|
|
651
|
+
mcpforge inspect --format json
|
|
652
|
+
```
|
|
653
|
+
|
|
654
|
+
| Option | Description |
|
|
655
|
+
|---|---|
|
|
656
|
+
| `--methods TEXT` | Filter by comma-separated HTTP methods |
|
|
657
|
+
| `--tag TEXT` | Filter by operation tag |
|
|
658
|
+
| `--path TEXT` | Filter by path substring or pattern |
|
|
659
|
+
| `--include-deprecated` | Include deprecated operations |
|
|
660
|
+
| `--format [table|json]` | Select Rich table or JSON output |
|
|
661
|
+
|
|
662
|
+
### `mcpforge validate`
|
|
663
|
+
|
|
664
|
+
Validate configuration, specifications, schemas, auth references, and security policy.
|
|
665
|
+
|
|
666
|
+
```bash
|
|
667
|
+
mcpforge validate
|
|
668
|
+
mcpforge validate --strict
|
|
669
|
+
mcpforge validate --config ./config/mcpforge.yaml
|
|
670
|
+
mcpforge validate --source ./openapi.yaml
|
|
671
|
+
```
|
|
672
|
+
|
|
673
|
+
| Option | Description |
|
|
674
|
+
|---|---|
|
|
675
|
+
| `--strict` | Treat warnings as validation failures |
|
|
676
|
+
| `--config PATH` | Validate a specific configuration |
|
|
677
|
+
| `--source PATH_OR_URL` | Validate a specific API source |
|
|
678
|
+
| `--show-secrets` | Never available; secret values are intentionally not rendered |
|
|
679
|
+
|
|
680
|
+
### `mcpforge test`
|
|
681
|
+
|
|
682
|
+
Verify API connectivity and authentication.
|
|
683
|
+
|
|
684
|
+
```bash
|
|
685
|
+
mcpforge test
|
|
686
|
+
mcpforge test --operation get_users
|
|
687
|
+
mcpforge test --operation get_user --param id=123
|
|
688
|
+
mcpforge test --timeout 15
|
|
689
|
+
mcpforge test --dry-run
|
|
690
|
+
```
|
|
691
|
+
|
|
692
|
+
| Option | Description |
|
|
693
|
+
|---|---|
|
|
694
|
+
| `--operation TEXT` | Invoke a specific endpoint |
|
|
695
|
+
| `--param KEY=VALUE` | Supply endpoint test parameters |
|
|
696
|
+
| `--timeout FLOAT` | Override HTTP timeout |
|
|
697
|
+
| `--dry-run` | Resolve configuration and auth without sending the request |
|
|
698
|
+
| `--verbose` | Show redacted request diagnostics |
|
|
699
|
+
|
|
700
|
+
### `mcpforge serve`
|
|
701
|
+
|
|
702
|
+
Launch the MCP server.
|
|
703
|
+
|
|
704
|
+
```bash
|
|
705
|
+
mcpforge serve --transport stdio
|
|
706
|
+
mcpforge serve --transport streamable-http --host 127.0.0.1 --port 8080
|
|
707
|
+
mcpforge serve --config ./mcpforge.yaml --log-level debug
|
|
708
|
+
```
|
|
709
|
+
|
|
710
|
+
| Option | Description |
|
|
711
|
+
|---|---|
|
|
712
|
+
| `--transport [stdio|streamable-http]` | MCP transport |
|
|
713
|
+
| `--host TEXT` | HTTP bind host |
|
|
714
|
+
| `--port INTEGER` | HTTP listen port |
|
|
715
|
+
| `--config PATH` | Project configuration file |
|
|
716
|
+
| `--log-level [debug|info|warning|error]` | Redacted runtime log level |
|
|
717
|
+
|
|
718
|
+
### `mcpforge run`
|
|
719
|
+
|
|
720
|
+
Import, validate, generate, and serve in one command.
|
|
721
|
+
|
|
722
|
+
```bash
|
|
723
|
+
mcpforge run ./openapi.yaml
|
|
724
|
+
mcpforge run https://api.example.com/openapi.yaml --transport stdio
|
|
725
|
+
mcpforge run ./openapi.yaml --allow-write
|
|
726
|
+
mcpforge run ./openapi.yaml --allow-delete
|
|
727
|
+
mcpforge run ./openapi.yaml --transport streamable-http --port 8080
|
|
728
|
+
```
|
|
729
|
+
|
|
730
|
+
| Option | Description |
|
|
731
|
+
|---|---|
|
|
732
|
+
| `<source>` | API specification or manual configuration |
|
|
733
|
+
| `--transport [stdio|streamable-http]` | MCP transport |
|
|
734
|
+
| `--host TEXT` | HTTP bind host |
|
|
735
|
+
| `--port INTEGER` | HTTP listen port |
|
|
736
|
+
| `--allow-write` | Explicitly enable write operations |
|
|
737
|
+
| `--allow-delete` | Explicitly enable delete operations |
|
|
738
|
+
| `--include-deprecated` | Include deprecated endpoints |
|
|
739
|
+
| `--config PATH` | Project configuration file |
|
|
740
|
+
|
|
741
|
+
### Global behavior
|
|
742
|
+
|
|
743
|
+
Every command should fail closed if:
|
|
744
|
+
|
|
745
|
+
- Authentication secrets are missing.
|
|
746
|
+
- Configuration contains literal credentials.
|
|
747
|
+
- A source cannot be safely loaded.
|
|
748
|
+
- Host policy rules conflict with the source host.
|
|
749
|
+
- Write or delete operations are enabled without explicit intent.
|
|
750
|
+
- A private or loopback host is discovered.
|
|
751
|
+
- The resolved DNS answer is prohibited.
|
|
752
|
+
- A tool schema is ambiguous or invalid.
|
|
753
|
+
|
|
754
|
+
---
|
|
755
|
+
|
|
756
|
+
## Configuration and Manual API Specs
|
|
757
|
+
|
|
758
|
+
### Complete `mcpforge.yaml` example
|
|
759
|
+
|
|
760
|
+
```yaml
|
|
761
|
+
name: inventory-api
|
|
762
|
+
|
|
763
|
+
source:
|
|
764
|
+
location: https://api.example.com/openapi.json
|
|
765
|
+
format: openapi
|
|
766
|
+
base_url: https://api.example.com
|
|
767
|
+
timeout_seconds: 30.0
|
|
768
|
+
|
|
769
|
+
auth:
|
|
770
|
+
type: bearer
|
|
771
|
+
token:
|
|
772
|
+
env: MCPFORGE_API_TOKEN
|
|
773
|
+
required: true
|
|
774
|
+
|
|
775
|
+
filters:
|
|
776
|
+
include_paths:
|
|
777
|
+
- /users
|
|
778
|
+
- /users/{id}
|
|
779
|
+
- /orders
|
|
780
|
+
- /orders/{id}
|
|
781
|
+
exclude_paths:
|
|
782
|
+
- /internal/*
|
|
783
|
+
- /admin/*
|
|
784
|
+
include_tags:
|
|
785
|
+
- Inventory
|
|
786
|
+
- Orders
|
|
787
|
+
exclude_tags:
|
|
788
|
+
- Internal
|
|
789
|
+
methods:
|
|
790
|
+
- GET
|
|
791
|
+
- POST
|
|
792
|
+
include_deprecated: false
|
|
793
|
+
|
|
794
|
+
security:
|
|
795
|
+
allow_write_operations: true
|
|
796
|
+
allow_delete_operations: false
|
|
797
|
+
allowed_hosts:
|
|
798
|
+
- api.example.com
|
|
799
|
+
block_private_networks: true
|
|
800
|
+
max_response_bytes: 5000000
|
|
801
|
+
|
|
802
|
+
http:
|
|
803
|
+
timeout_seconds: 30.0
|
|
804
|
+
verify_tls: true
|
|
805
|
+
retry:
|
|
806
|
+
max_attempts: 3
|
|
807
|
+
backoff_seconds: 0.5
|
|
808
|
+
```
|
|
809
|
+
|
|
810
|
+
### Bearer authentication
|
|
811
|
+
|
|
812
|
+
```yaml
|
|
813
|
+
auth:
|
|
814
|
+
type: bearer
|
|
815
|
+
token:
|
|
816
|
+
env: MCPFORGE_API_TOKEN
|
|
817
|
+
required: true
|
|
818
|
+
```
|
|
819
|
+
|
|
820
|
+
Do not use:
|
|
821
|
+
|
|
822
|
+
```yaml
|
|
823
|
+
auth:
|
|
824
|
+
type: bearer
|
|
825
|
+
token: sk-live-hardcoded-secret
|
|
826
|
+
```
|
|
827
|
+
|
|
828
|
+
### API key in a header
|
|
829
|
+
|
|
830
|
+
```yaml
|
|
831
|
+
auth:
|
|
832
|
+
type: api_key
|
|
833
|
+
name: X-API-Key
|
|
834
|
+
location: header
|
|
835
|
+
value:
|
|
836
|
+
env: MCPFORGE_API_KEY
|
|
837
|
+
required: true
|
|
838
|
+
```
|
|
839
|
+
|
|
840
|
+
### API key in a query parameter
|
|
841
|
+
|
|
842
|
+
```yaml
|
|
843
|
+
auth:
|
|
844
|
+
type: api_key
|
|
845
|
+
name: api_key
|
|
846
|
+
location: query
|
|
847
|
+
value:
|
|
848
|
+
env: MCPFORGE_API_KEY
|
|
849
|
+
required: true
|
|
850
|
+
```
|
|
851
|
+
|
|
852
|
+
### Basic authentication
|
|
853
|
+
|
|
854
|
+
```yaml
|
|
855
|
+
auth:
|
|
856
|
+
type: basic
|
|
857
|
+
username:
|
|
858
|
+
env: MCPFORGE_API_USERNAME
|
|
859
|
+
required: true
|
|
860
|
+
password:
|
|
861
|
+
env: MCPFORGE_API_PASSWORD
|
|
862
|
+
required: true
|
|
863
|
+
```
|
|
864
|
+
|
|
865
|
+
### Custom static headers
|
|
866
|
+
|
|
867
|
+
```yaml
|
|
868
|
+
auth:
|
|
869
|
+
type: static_headers
|
|
870
|
+
headers:
|
|
871
|
+
X-Tenant-ID:
|
|
872
|
+
env: MCPFORGE_TENANT_ID
|
|
873
|
+
required: true
|
|
874
|
+
X-Client-Version:
|
|
875
|
+
env: MCPFORGE_CLIENT_VERSION
|
|
876
|
+
required: false
|
|
877
|
+
default: "1.0"
|
|
878
|
+
```
|
|
879
|
+
|
|
880
|
+
### Manual API specification
|
|
881
|
+
|
|
882
|
+
MCPForge supports manual YAML when no OpenAPI specification is available:
|
|
883
|
+
|
|
884
|
+
```yaml
|
|
885
|
+
name: Inventory API
|
|
886
|
+
version: "1.0.0"
|
|
887
|
+
base_url: https://api.example.com
|
|
888
|
+
|
|
889
|
+
endpoints:
|
|
890
|
+
- operation_id: list_products
|
|
891
|
+
method: GET
|
|
892
|
+
path: /products
|
|
893
|
+
summary: List products
|
|
894
|
+
description: Returns a paginated product catalog.
|
|
895
|
+
tags:
|
|
896
|
+
- Inventory
|
|
897
|
+
parameters:
|
|
898
|
+
- name: limit
|
|
899
|
+
location: query
|
|
900
|
+
required: false
|
|
901
|
+
description: Maximum number of products to return.
|
|
902
|
+
schema:
|
|
903
|
+
type: integer
|
|
904
|
+
minimum: 1
|
|
905
|
+
maximum: 100
|
|
906
|
+
default: 20
|
|
907
|
+
- name: cursor
|
|
908
|
+
location: query
|
|
909
|
+
required: false
|
|
910
|
+
schema:
|
|
911
|
+
type: string
|
|
912
|
+
responses:
|
|
913
|
+
- status_code: 200
|
|
914
|
+
content_type: application/json
|
|
915
|
+
description: Product page
|
|
916
|
+
schema:
|
|
917
|
+
type: object
|
|
918
|
+
properties:
|
|
919
|
+
items:
|
|
920
|
+
type: array
|
|
921
|
+
items:
|
|
922
|
+
type: object
|
|
923
|
+
next_cursor:
|
|
924
|
+
type: string
|
|
925
|
+
nullable: true
|
|
926
|
+
|
|
927
|
+
- operation_id: get_product
|
|
928
|
+
method: GET
|
|
929
|
+
path: /products/{product_id}
|
|
930
|
+
tags:
|
|
931
|
+
- Inventory
|
|
932
|
+
parameters:
|
|
933
|
+
- name: product_id
|
|
934
|
+
location: path
|
|
935
|
+
required: true
|
|
936
|
+
description: Product identifier.
|
|
937
|
+
schema:
|
|
938
|
+
type: string
|
|
939
|
+
responses:
|
|
940
|
+
- status_code: 200
|
|
941
|
+
content_type: application/json
|
|
942
|
+
description: Product found
|
|
943
|
+
- status_code: 404
|
|
944
|
+
description: Product not found
|
|
945
|
+
```
|
|
946
|
+
|
|
947
|
+
Manual request bodies use a JSON Schema-like structure:
|
|
948
|
+
|
|
949
|
+
```yaml
|
|
950
|
+
- operation_id: create_product
|
|
951
|
+
method: POST
|
|
952
|
+
path: /products
|
|
953
|
+
tags:
|
|
954
|
+
- Inventory
|
|
955
|
+
request_body:
|
|
956
|
+
required: true
|
|
957
|
+
content_type: application/json
|
|
958
|
+
schema:
|
|
959
|
+
type: object
|
|
960
|
+
required:
|
|
961
|
+
- name
|
|
962
|
+
- price
|
|
963
|
+
properties:
|
|
964
|
+
name:
|
|
965
|
+
type: string
|
|
966
|
+
min_length: 1
|
|
967
|
+
price:
|
|
968
|
+
type: number
|
|
969
|
+
minimum: 0
|
|
970
|
+
category:
|
|
971
|
+
type: string
|
|
972
|
+
enum:
|
|
973
|
+
- physical
|
|
974
|
+
- digital
|
|
975
|
+
```
|
|
976
|
+
|
|
977
|
+
### Tool override example
|
|
978
|
+
|
|
979
|
+
```yaml
|
|
980
|
+
tool_overrides:
|
|
981
|
+
get_product:
|
|
982
|
+
name: fetch_inventory_product
|
|
983
|
+
description: Fetch a product by its unique inventory identifier.
|
|
984
|
+
delete_product:
|
|
985
|
+
enabled: false
|
|
986
|
+
```
|
|
987
|
+
|
|
988
|
+
Tool overrides must not contain credentials or expose secret values.
|
|
989
|
+
|
|
990
|
+
---
|
|
991
|
+
|
|
992
|
+
## Connecting to AI Clients
|
|
993
|
+
|
|
994
|
+
Set secrets in the environment that launches your MCP client process.
|
|
995
|
+
|
|
996
|
+
```bash
|
|
997
|
+
export MCPFORGE_API_TOKEN="your-token"
|
|
998
|
+
```
|
|
999
|
+
|
|
1000
|
+
### Claude Desktop
|
|
1001
|
+
|
|
1002
|
+
Edit `claude_desktop_config.json`:
|
|
1003
|
+
|
|
1004
|
+
```json
|
|
1005
|
+
{
|
|
1006
|
+
"mcpServers": {
|
|
1007
|
+
"mcpforge": {
|
|
1008
|
+
"command": "mcpforge",
|
|
1009
|
+
"args": [
|
|
1010
|
+
"serve",
|
|
1011
|
+
"--transport",
|
|
1012
|
+
"stdio",
|
|
1013
|
+
"--config",
|
|
1014
|
+
"/absolute/path/to/mcpforge.yaml"
|
|
1015
|
+
],
|
|
1016
|
+
"env": {
|
|
1017
|
+
"MCPFORGE_API_TOKEN": "not-recommended-to-place-a-token-here"
|
|
1018
|
+
}
|
|
1019
|
+
}
|
|
1020
|
+
}
|
|
1021
|
+
}
|
|
1022
|
+
```
|
|
1023
|
+
|
|
1024
|
+
Prefer resolving secrets through Claude Desktop's environment or a system-level
|
|
1025
|
+
secret manager. MCPForge can read `MCPFORGE_API_TOKEN` directly from the process
|
|
1026
|
+
environment.
|
|
1027
|
+
|
|
1028
|
+
Claude Desktop locations:
|
|
1029
|
+
|
|
1030
|
+
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
1031
|
+
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
1032
|
+
- Linux: varies by MCP host configuration
|
|
1033
|
+
|
|
1034
|
+
### Cursor IDE
|
|
1035
|
+
|
|
1036
|
+
Create or update `.cursor/mcp.json`:
|
|
1037
|
+
|
|
1038
|
+
```json
|
|
1039
|
+
{
|
|
1040
|
+
"mcpServers": {
|
|
1041
|
+
"mcpforge": {
|
|
1042
|
+
"command": "mcpforge",
|
|
1043
|
+
"args": [
|
|
1044
|
+
"serve",
|
|
1045
|
+
"--transport",
|
|
1046
|
+
"stdio",
|
|
1047
|
+
"--config",
|
|
1048
|
+
"${workspaceFolder}/mcpforge.yaml"
|
|
1049
|
+
],
|
|
1050
|
+
"env": {
|
|
1051
|
+
"MCPFORGE_API_TOKEN": "${env:MCPFORGE_API_TOKEN}"
|
|
1052
|
+
}
|
|
1053
|
+
}
|
|
1054
|
+
}
|
|
1055
|
+
}
|
|
1056
|
+
```
|
|
1057
|
+
|
|
1058
|
+
### VS Code
|
|
1059
|
+
|
|
1060
|
+
VS Code MCP configurations commonly use a `.vscode/mcp.json` file:
|
|
1061
|
+
|
|
1062
|
+
```json
|
|
1063
|
+
{
|
|
1064
|
+
"servers": {
|
|
1065
|
+
"mcpforge": {
|
|
1066
|
+
"type": "stdio",
|
|
1067
|
+
"command": "mcpforge",
|
|
1068
|
+
"args": [
|
|
1069
|
+
"serve",
|
|
1070
|
+
"--transport",
|
|
1071
|
+
"stdio",
|
|
1072
|
+
"--config",
|
|
1073
|
+
"${workspaceFolder}/mcpforge.yaml"
|
|
1074
|
+
],
|
|
1075
|
+
"env": {
|
|
1076
|
+
"MCPFORGE_API_TOKEN": "${env:MCPFORGE_API_TOKEN}"
|
|
1077
|
+
}
|
|
1078
|
+
}
|
|
1079
|
+
}
|
|
1080
|
+
}
|
|
1081
|
+
```
|
|
1082
|
+
|
|
1083
|
+
Use the MCP configuration interface in VS Code if your installed version supports
|
|
1084
|
+
workspace variable substitution or environment expansion.
|
|
1085
|
+
|
|
1086
|
+
### Windsurf
|
|
1087
|
+
|
|
1088
|
+
Add a project or user MCP configuration in the Windsurf MCP settings:
|
|
1089
|
+
|
|
1090
|
+
```json
|
|
1091
|
+
{
|
|
1092
|
+
"mcpServers": {
|
|
1093
|
+
"mcpforge": {
|
|
1094
|
+
"command": "mcpforge",
|
|
1095
|
+
"args": [
|
|
1096
|
+
"serve",
|
|
1097
|
+
"--transport",
|
|
1098
|
+
"stdio",
|
|
1099
|
+
"--config",
|
|
1100
|
+
"/absolute/path/to/mcpforge.yaml"
|
|
1101
|
+
],
|
|
1102
|
+
"env": {
|
|
1103
|
+
"MCPFORGE_API_TOKEN": "${env:MCPFORGE_API_TOKEN}"
|
|
1104
|
+
}
|
|
1105
|
+
}
|
|
1106
|
+
}
|
|
1107
|
+
}
|
|
1108
|
+
```
|
|
1109
|
+
|
|
1110
|
+
Use an absolute configuration path if the MCP host process does not inherit the
|
|
1111
|
+
project working directory.
|
|
1112
|
+
|
|
1113
|
+
### Streamable HTTP Remote Server
|
|
1114
|
+
|
|
1115
|
+
Start the server:
|
|
1116
|
+
|
|
1117
|
+
```bash
|
|
1118
|
+
MCPFORGE_API_TOKEN="your-token" \
|
|
1119
|
+
mcpforge serve \
|
|
1120
|
+
--transport streamable-http \
|
|
1121
|
+
--host 0.0.0.0 \
|
|
1122
|
+
--port 8080 \
|
|
1123
|
+
--config /srv/mcpforge/mcpforge.yaml
|
|
1124
|
+
```
|
|
1125
|
+
|
|
1126
|
+
Configure a compatible MCP client:
|
|
1127
|
+
|
|
1128
|
+
```json
|
|
1129
|
+
{
|
|
1130
|
+
"mcpServers": {
|
|
1131
|
+
"inventory-api": {
|
|
1132
|
+
"transport": "streamable-http",
|
|
1133
|
+
"url": "https://mcp.example.com/mcp",
|
|
1134
|
+
"headers": {
|
|
1135
|
+
"Authorization": "Bearer ${MCP_GATEWAY_TOKEN}"
|
|
1136
|
+
}
|
|
1137
|
+
}
|
|
1138
|
+
}
|
|
1139
|
+
}
|
|
1140
|
+
```
|
|
1141
|
+
|
|
1142
|
+
Production deployments should place MCPForge behind:
|
|
1143
|
+
|
|
1144
|
+
- TLS termination
|
|
1145
|
+
- Authentication
|
|
1146
|
+
- Authorization
|
|
1147
|
+
- Rate limiting
|
|
1148
|
+
- Restricted network routing
|
|
1149
|
+
- Health monitoring
|
|
1150
|
+
- Centralized secret management
|
|
1151
|
+
|
|
1152
|
+
---
|
|
1153
|
+
|
|
1154
|
+
## Security Model and Guardrails
|
|
1155
|
+
|
|
1156
|
+
| Threat or Failure | MCPForge Protection |
|
|
1157
|
+
|---|---|
|
|
1158
|
+
| Accidental deletion | `DELETE` operations remain disabled unless explicitly enabled |
|
|
1159
|
+
| Accidental writes | `POST`, `PUT`, and `PATCH` remain disabled unless configured |
|
|
1160
|
+
| SSRF to loopback | Loopback addresses such as `127.0.0.0/8` and `::1` are blocked |
|
|
1161
|
+
| SSRF to private networks | RFC1918 and equivalent private ranges are blocked by default |
|
|
1162
|
+
| Link-local access | Link-local IPv4/IPv6 ranges are blocked |
|
|
1163
|
+
| DNS rebinding | Resolved addresses are checked before execution and redirects |
|
|
1164
|
+
| Host allowlist bypass | Requests outside `allowed_hosts` are rejected |
|
|
1165
|
+
| Literal credentials | Configuration rejects credentials that are not environment references |
|
|
1166
|
+
| Logs exposing secrets | Recursive redaction removes tokens and authorization values |
|
|
1167
|
+
| MCP schema leakage | Credentials never become tool arguments or descriptions |
|
|
1168
|
+
| Context overflow | Maximum response bytes are enforced before AI delivery |
|
|
1169
|
+
| Invalid upstream JSON | Invalid JSON becomes a structured, recoverable error |
|
|
1170
|
+
| Token rotation | Secrets resolve at runtime instead of during import or generation |
|
|
1171
|
+
| Unbounded retries | Retry attempts are capped and backoff is configurable |
|
|
1172
|
+
| Slow upstream API | Connect and read timeouts prevent indefinite execution |
|
|
1173
|
+
| Redirect escape | Redirect hosts remain subject to allowed-host and SSRF policy |
|
|
1174
|
+
| TLS interception | TLS verification is enabled by default |
|
|
1175
|
+
| Ambiguous tool names | Collision resolution produces deterministic names and warnings |
|
|
1176
|
+
|
|
1177
|
+
### Operation Safety
|
|
1178
|
+
|
|
1179
|
+
Endpoint methods map to coarse safety categories:
|
|
1180
|
+
|
|
1181
|
+
| Method | Default Safety |
|
|
1182
|
+
|---|---|
|
|
1183
|
+
| `GET` | Read; enabled by default |
|
|
1184
|
+
| `HEAD` | Read; enabled by default |
|
|
1185
|
+
| `OPTIONS` | Read; enabled by default |
|
|
1186
|
+
| `POST` | Write; explicit opt-in |
|
|
1187
|
+
| `PUT` | Write; explicit opt-in |
|
|
1188
|
+
| `PATCH` | Write; explicit opt-in |
|
|
1189
|
+
| `DELETE` | Delete; explicit opt-in |
|
|
1190
|
+
|
|
1191
|
+
A write-enabled project does not imply delete-enabled behavior. Both flags are
|
|
1192
|
+
evaluated independently.
|
|
1193
|
+
|
|
1194
|
+
### SSRF Defense
|
|
1195
|
+
|
|
1196
|
+
Before creating an upstream request, MCPForge should validate:
|
|
1197
|
+
|
|
1198
|
+
1. The scheme is HTTP or HTTPS.
|
|
1199
|
+
2. The URL host matches `allowed_hosts`, where configured.
|
|
1200
|
+
3. The hostname can be resolved.
|
|
1201
|
+
4. Every resolved address is outside blocked ranges.
|
|
1202
|
+
5. Redirect targets pass the same checks.
|
|
1203
|
+
6. The selected connection cannot escape the validated address policy.
|
|
1204
|
+
|
|
1205
|
+
Private address detection is broad enough to include loopback, private, reserved,
|
|
1206
|
+
link-local, multicast, unspecified, carrier-grade NAT, and other special-purpose
|
|
1207
|
+
address families where applicable.
|
|
1208
|
+
|
|
1209
|
+
### Secret Redaction
|
|
1210
|
+
|
|
1211
|
+
Redaction applies recursively to:
|
|
1212
|
+
|
|
1213
|
+
- Dictionaries
|
|
1214
|
+
- Lists
|
|
1215
|
+
- Nested error details
|
|
1216
|
+
- Exception messages
|
|
1217
|
+
- Header collections
|
|
1218
|
+
- Query logging
|
|
1219
|
+
- Diagnostic JSON
|
|
1220
|
+
- Terminal output
|
|
1221
|
+
|
|
1222
|
+
Sensitive names include values associated with:
|
|
1223
|
+
|
|
1224
|
+
- `authorization`
|
|
1225
|
+
- `cookie`
|
|
1226
|
+
- `set-cookie`
|
|
1227
|
+
- `token`
|
|
1228
|
+
- `api_key`
|
|
1229
|
+
- `api-key`
|
|
1230
|
+
- `password`
|
|
1231
|
+
- `secret`
|
|
1232
|
+
- `client_secret`
|
|
1233
|
+
- `access_key`
|
|
1234
|
+
- `session`
|
|
1235
|
+
|
|
1236
|
+
Redacted values are replaced consistently rather than being returned to AI clients.
|
|
1237
|
+
|
|
1238
|
+
### Response Size Protection
|
|
1239
|
+
|
|
1240
|
+
Every successful and error response is checked against `max_response_bytes`.
|
|
1241
|
+
|
|
1242
|
+
A payload exceeding the limit should result in:
|
|
1243
|
+
|
|
1244
|
+
```json
|
|
1245
|
+
{
|
|
1246
|
+
"ok": false,
|
|
1247
|
+
"error": {
|
|
1248
|
+
"category": "response_too_large",
|
|
1249
|
+
"message": "The upstream response exceeded the configured payload limit.",
|
|
1250
|
+
"status_code": 200,
|
|
1251
|
+
"retryable": false
|
|
1252
|
+
}
|
|
1253
|
+
}
|
|
1254
|
+
```
|
|
1255
|
+
|
|
1256
|
+
The raw oversized body must not be included in the response delivered to the AI.
|
|
1257
|
+
|
|
1258
|
+
---
|
|
1259
|
+
|
|
1260
|
+
## Project Directory Structure
|
|
1261
|
+
|
|
1262
|
+
```text
|
|
1263
|
+
mcpforge/
|
|
1264
|
+
├── pyproject.toml # Build, dependencies, scripts, and tool settings
|
|
1265
|
+
├── README.md # Project documentation
|
|
1266
|
+
├── LICENSE # MIT license
|
|
1267
|
+
├── CHANGELOG.md # Release history
|
|
1268
|
+
├── Makefile # Common development commands
|
|
1269
|
+
├── .gitignore # Repository ignore rules
|
|
1270
|
+
├── .pre-commit-config.yaml # Pre-commit quality hooks
|
|
1271
|
+
│
|
|
1272
|
+
├── docs/
|
|
1273
|
+
│ ├── architecture.md # Architecture and extension points
|
|
1274
|
+
│ ├── configuration.md # Complete configuration reference
|
|
1275
|
+
│ ├── security.md # Security guarantees and deployment guidance
|
|
1276
|
+
│ └── supported-specifications.md
|
|
1277
|
+
│
|
|
1278
|
+
├── examples/
|
|
1279
|
+
│ ├── basic/
|
|
1280
|
+
│ │ ├── mcpforge.yaml # Basic project configuration
|
|
1281
|
+
│ │ └── .env.example # Environment variable template
|
|
1282
|
+
│ └── openapi/
|
|
1283
|
+
│ └── petstore.yaml # Example OpenAPI specification
|
|
1284
|
+
│
|
|
1285
|
+
├── src/
|
|
1286
|
+
│ └── mcpforge/
|
|
1287
|
+
│ ├── __init__.py # Package metadata and public exports
|
|
1288
|
+
│ ├── __main__.py # `python -m mcpforge` entry point
|
|
1289
|
+
│
|
|
1290
|
+
│ ├── cli/
|
|
1291
|
+
│ │ ├── app.py # Typer application
|
|
1292
|
+
│ │ ├── context.py # Shared CLI context
|
|
1293
|
+
│ │ ├── output.py # Rich terminal rendering
|
|
1294
|
+
│ │ └── commands/
|
|
1295
|
+
│ │ ├── init.py # Project scaffolding
|
|
1296
|
+
│ │ ├── import_spec.py # API import
|
|
1297
|
+
│ │ ├── inspect.py # Endpoint and tool inspection
|
|
1298
|
+
│ │ ├── validate.py # Static validation
|
|
1299
|
+
│ │ ├── test.py # Connectivity and auth testing
|
|
1300
|
+
│ │ ├── serve.py # MCP server startup
|
|
1301
|
+
│ │ └── run.py # One-command pipeline
|
|
1302
|
+
│
|
|
1303
|
+
│ ├── config/
|
|
1304
|
+
│ │ ├── models.py # Pydantic configuration models
|
|
1305
|
+
│ │ ├── loader.py # YAML/JSON loading
|
|
1306
|
+
│ │ ├── merger.py # Configuration precedence
|
|
1307
|
+
│ │ └── secrets.py # Environment-backed secret resolution
|
|
1308
|
+
│
|
|
1309
|
+
│ ├── domain/
|
|
1310
|
+
│ │ ├── enums.py # HTTP, parameter, auth, and safety enums
|
|
1311
|
+
│ │ ├── models.py # ApiDocument and endpoint contracts
|
|
1312
|
+
│ │ ├── parameters.py # Parameter helpers
|
|
1313
|
+
│ │ ├── schemas.py # JSON schema aliases
|
|
1314
|
+
│ │ └── errors.py # Domain exceptions
|
|
1315
|
+
│
|
|
1316
|
+
│ ├── ingestion/
|
|
1317
|
+
│ │ ├── service.py # Format selection and ingestion workflow
|
|
1318
|
+
│ │ ├── source.py # Source descriptors
|
|
1319
|
+
│ │ ├── loaders/ # Local and remote loading
|
|
1320
|
+
│ │ ├── parsers/ # OpenAPI, Swagger, and manual parsers
|
|
1321
|
+
│ │ └── normalization/ # Parser-specific conversion helpers
|
|
1322
|
+
│
|
|
1323
|
+
│ ├── filtering/
|
|
1324
|
+
│ │ ├── policies.py # Read/write/delete and deprecation policies
|
|
1325
|
+
│ │ ├── selectors.py # Path, tag, and method selectors
|
|
1326
|
+
│ │ └── evaluator.py # Final endpoint inclusion decision
|
|
1327
|
+
│
|
|
1328
|
+
│ ├── generation/
|
|
1329
|
+
│ │ ├── models.py # Generated ToolDefinition contracts
|
|
1330
|
+
│ │ ├── naming.py # Deterministic snake_case naming
|
|
1331
|
+
│ │ ├── descriptions.py # Tool descriptions
|
|
1332
|
+
│ │ ├── collisions.py # Stable collision resolution
|
|
1333
|
+
│ │ ├── input_schema.py # AI-facing JSON input schemas
|
|
1334
|
+
│ │ └── service.py # Endpoint-to-tool generation
|
|
1335
|
+
│
|
|
1336
|
+
│ ├── auth/
|
|
1337
|
+
│ │ ├── models.py # Authentication contracts
|
|
1338
|
+
│ │ ├── providers.py # Bearer, API key, Basic, and static auth
|
|
1339
|
+
│ │ ├── resolver.py # Runtime auth resolution
|
|
1340
|
+
│ │ └── redaction.py # Auth-related secret scrubbing
|
|
1341
|
+
│
|
|
1342
|
+
│ ├── execution/
|
|
1343
|
+
│ │ ├── engine.py # Request orchestration
|
|
1344
|
+
│ │ ├── client.py # Shared AsyncClient lifecycle
|
|
1345
|
+
│ │ ├── request_builder.py # Path/query/header/body construction
|
|
1346
|
+
│ │ ├── retry.py # Retry and backoff policy
|
|
1347
|
+
│ │ ├── response.py # Response parsing
|
|
1348
|
+
│ │ ├── errors.py # Structured HTTP failures
|
|
1349
|
+
│ │ └── limits.py # Payload-size enforcement
|
|
1350
|
+
│
|
|
1351
|
+
│ ├── security/
|
|
1352
|
+
│ │ ├── safety.py # Operation safety policy
|
|
1353
|
+
│ │ ├── ssrf.py # DNS and private-network validation
|
|
1354
|
+
│ │ ├── hosts.py # Allowed-host enforcement
|
|
1355
|
+
│ │ ├── validation.py # Cross-cutting security validation
|
|
1356
|
+
│ │ └── redaction.py # Recursive output/log redaction
|
|
1357
|
+
│
|
|
1358
|
+
│ ├── mcp/
|
|
1359
|
+
│ │ ├── adapter.py # Internal-tool to MCP-SDK adapter
|
|
1360
|
+
│ │ ├── server.py # MCP server creation
|
|
1361
|
+
│ │ ├── tools.py # Tool callbacks
|
|
1362
|
+
│ │ ├── errors.py # MCP-compatible errors
|
|
1363
|
+
│ │ └── transports.py # stdio and streamable-http
|
|
1364
|
+
│
|
|
1365
|
+
│ ├── runtime/
|
|
1366
|
+
│ │ ├── application.py # Dependency composition
|
|
1367
|
+
│ │ ├── lifecycle.py # Startup and graceful shutdown
|
|
1368
|
+
│ │ └── dependencies.py # Runtime dependency providers
|
|
1369
|
+
│
|
|
1370
|
+
│ └── observability/
|
|
1371
|
+
│ ├── logging.py # Redacted logging
|
|
1372
|
+
│ ├── events.py # Structured events
|
|
1373
|
+
│ └── diagnostics.py # Safe diagnostics
|
|
1374
|
+
│
|
|
1375
|
+
└── tests/
|
|
1376
|
+
├── conftest.py
|
|
1377
|
+
├── unit/
|
|
1378
|
+
│ ├── domain/
|
|
1379
|
+
│ ├── config/
|
|
1380
|
+
│ ├── ingestion/
|
|
1381
|
+
│ ├── filtering/
|
|
1382
|
+
│ ├── generation/
|
|
1383
|
+
│ ├── auth/
|
|
1384
|
+
│ ├── execution/
|
|
1385
|
+
│ ├── security/
|
|
1386
|
+
│ ├── mcp/
|
|
1387
|
+
│ └── runtime/
|
|
1388
|
+
├── integration/
|
|
1389
|
+
│ ├── ingestion/
|
|
1390
|
+
│ ├── execution/
|
|
1391
|
+
│ └── server/
|
|
1392
|
+
├── fixtures/
|
|
1393
|
+
│ ├── openapi/
|
|
1394
|
+
│ ├── swagger/
|
|
1395
|
+
│ ├── manual/
|
|
1396
|
+
│ └── responses/
|
|
1397
|
+
└── e2e/
|
|
1398
|
+
```
|
|
1399
|
+
|
|
1400
|
+
---
|
|
1401
|
+
|
|
1402
|
+
## Development and Quality Checks
|
|
1403
|
+
|
|
1404
|
+
### Clone and install
|
|
1405
|
+
|
|
1406
|
+
```bash
|
|
1407
|
+
git clone https://github.com/AshishVail/mcpforge.git
|
|
1408
|
+
cd mcpforge
|
|
1409
|
+
python -m venv .venv
|
|
1410
|
+
source .venv/bin/activate
|
|
1411
|
+
python -m pip install -e ".[dev]"
|
|
1412
|
+
```
|
|
1413
|
+
|
|
1414
|
+
### Run unit and integration tests
|
|
1415
|
+
|
|
1416
|
+
```bash
|
|
1417
|
+
pytest
|
|
1418
|
+
```
|
|
1419
|
+
|
|
1420
|
+
With coverage:
|
|
1421
|
+
|
|
1422
|
+
```bash
|
|
1423
|
+
pytest --cov=mcpforge --cov-report=term-missing --cov-report=html
|
|
1424
|
+
```
|
|
1425
|
+
|
|
1426
|
+
Run a focused test directory:
|
|
1427
|
+
|
|
1428
|
+
```bash
|
|
1429
|
+
pytest tests/unit/generation
|
|
1430
|
+
pytest tests/integration/execution
|
|
1431
|
+
```
|
|
1432
|
+
|
|
1433
|
+
### Run Ruff
|
|
1434
|
+
|
|
1435
|
+
```bash
|
|
1436
|
+
ruff check .
|
|
1437
|
+
ruff format --check .
|
|
1438
|
+
ruff format .
|
|
1439
|
+
ruff check --fix .
|
|
1440
|
+
```
|
|
1441
|
+
|
|
1442
|
+
### Run mypy
|
|
1443
|
+
|
|
1444
|
+
```bash
|
|
1445
|
+
mypy src
|
|
1446
|
+
```
|
|
1447
|
+
|
|
1448
|
+
Strict typing is recommended for all pull requests.
|
|
1449
|
+
|
|
1450
|
+
### Makefile targets
|
|
1451
|
+
|
|
1452
|
+
```bash
|
|
1453
|
+
make install
|
|
1454
|
+
make test
|
|
1455
|
+
make lint
|
|
1456
|
+
make typecheck
|
|
1457
|
+
make format
|
|
1458
|
+
make check
|
|
1459
|
+
```
|
|
1460
|
+
|
|
1461
|
+
Expected `make check` sequence:
|
|
1462
|
+
|
|
1463
|
+
```text
|
|
1464
|
+
ruff check .
|
|
1465
|
+
mypy src
|
|
1466
|
+
pytest
|
|
1467
|
+
```
|
|
1468
|
+
|
|
1469
|
+
### Pre-commit hooks
|
|
1470
|
+
|
|
1471
|
+
```bash
|
|
1472
|
+
python -m pip install pre-commit
|
|
1473
|
+
pre-commit install
|
|
1474
|
+
pre-commit run --all-files
|
|
1475
|
+
```
|
|
1476
|
+
|
|
1477
|
+
### Pull request checklist
|
|
1478
|
+
|
|
1479
|
+
Before submitting a pull request:
|
|
1480
|
+
|
|
1481
|
+
- [ ] Changes are covered by focused tests
|
|
1482
|
+
- [ ] Public models remain Pydantic v2-compatible
|
|
1483
|
+
- [ ] Domain code remains framework-independent
|
|
1484
|
+
- [ ] MCP SDK imports stay behind the adapter layer
|
|
1485
|
+
- [ ] Secrets are environment-backed
|
|
1486
|
+
- [ ] Logs and errors pass through redaction
|
|
1487
|
+
- [ ] SSRF and host-policy behavior is preserved
|
|
1488
|
+
- [ ] Write and delete operations remain opt-in
|
|
1489
|
+
- [ ] Ruff and mypy pass
|
|
1490
|
+
- [ ] Documentation reflects CLI behavior or configuration changes
|
|
1491
|
+
|
|
1492
|
+
---
|
|
1493
|
+
|
|
1494
|
+
## Roadmap
|
|
1495
|
+
|
|
1496
|
+
### Current Foundation
|
|
1497
|
+
|
|
1498
|
+
- [x] Project identity and package structure
|
|
1499
|
+
- [x] Pydantic normalized domain model
|
|
1500
|
+
- [x] Strict project configuration
|
|
1501
|
+
- [x] Environment-variable secret references
|
|
1502
|
+
- [x] Typer/Rich CLI foundation
|
|
1503
|
+
- [ ] OpenAPI 3.0 and 3.1 ingestion
|
|
1504
|
+
- [ ] Swagger 2.0 conversion
|
|
1505
|
+
- [ ] Manual YAML ingestion
|
|
1506
|
+
- [ ] Deterministic MCP tool generation
|
|
1507
|
+
- [ ] Authentication providers
|
|
1508
|
+
- [ ] SSRF and host protection
|
|
1509
|
+
- [ ] Async HTTP execution
|
|
1510
|
+
- [ ] stdio and streamable-http transports
|
|
1511
|
+
- [ ] Complete CLI workflow
|
|
1512
|
+
- [ ] Enterprise documentation and examples
|
|
1513
|
+
|
|
1514
|
+
### Near-Term
|
|
1515
|
+
|
|
1516
|
+
- OpenAPI specification caching
|
|
1517
|
+
- Endpoint-level tool overrides
|
|
1518
|
+
- JSON Schema composition support
|
|
1519
|
+
- GraphQL or gRPC protocol adapters
|
|
1520
|
+
- OAuth 2.0 device authorization
|
|
1521
|
+
- OAuth 2.0 client credentials
|
|
1522
|
+
- Interactive secret resolution
|
|
1523
|
+
- Docker and Kubernetes examples
|
|
1524
|
+
- OpenTelemetry-compatible tracing
|
|
1525
|
+
- Structured audit events
|
|
1526
|
+
- Secret-manager provider plugins
|
|
1527
|
+
- MCP prompt and resource generation
|
|
1528
|
+
- Response transformation templates
|
|
1529
|
+
- Interactive local configuration UI
|
|
1530
|
+
|
|
1531
|
+
### Long-Term
|
|
1532
|
+
|
|
1533
|
+
- API registry integration
|
|
1534
|
+
- Remote specification discovery
|
|
1535
|
+
- Signed configuration packages
|
|
1536
|
+
- Policy-as-code plugins
|
|
1537
|
+
- Organization-wide host allowlists
|
|
1538
|
+
- Central credential brokers
|
|
1539
|
+
- Automated schema drift detection
|
|
1540
|
+
- Built-in API mock server
|
|
1541
|
+
- Multi-API MCP gateway
|
|
1542
|
+
- Per-user authorization mapping
|
|
1543
|
+
- Enterprise audit and observability exports
|
|
1544
|
+
- Compliance reporting
|
|
1545
|
+
- Plugin marketplace for parsers and transports
|
|
1546
|
+
|
|
1547
|
+
---
|
|
1548
|
+
|
|
1549
|
+
## License and Attribution
|
|
1550
|
+
|
|
1551
|
+
MCPForge is licensed under the [MIT License](LICENSE).
|
|
1552
|
+
|
|
1553
|
+
Copyright 2026 [AshishVail](https://github.com/AshishVail).
|
|
1554
|
+
|
|
1555
|
+
MCPForge is independently maintained and is not affiliated with Anthropic,
|
|
1556
|
+
Claude, Cursor, Microsoft, Windsurf, or the maintainers of the official MCP SDK.
|
|
1557
|
+
All trademarks belong to their respective owners.
|
|
1558
|
+
|
|
1559
|
+
If MCPForge helps automate API integration for your team or project, consider:
|
|
1560
|
+
|
|
1561
|
+
- Starring the repository
|
|
1562
|
+
- Reporting bugs and security issues
|
|
1563
|
+
- Adding supported specifications
|
|
1564
|
+
- Improving documentation
|
|
1565
|
+
- Contributing parsers, auth providers, or MCP integrations
|
|
1566
|
+
- Sharing your deployment architecture
|