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.
Files changed (92) hide show
  1. mcpforge/__init__.py +8 -0
  2. mcpforge/__main__.py +6 -0
  3. mcpforge/auth/__init__.py +28 -0
  4. mcpforge/auth/models.py +25 -0
  5. mcpforge/auth/providers.py +72 -0
  6. mcpforge/auth/redaction.py +47 -0
  7. mcpforge/auth/resolver.py +42 -0
  8. mcpforge/cli/__init__.py +1 -0
  9. mcpforge/cli/app.py +45 -0
  10. mcpforge/cli/commands/__init__.py +13 -0
  11. mcpforge/cli/commands/import_spec.py +41 -0
  12. mcpforge/cli/commands/init.py +42 -0
  13. mcpforge/cli/commands/inspect.py +56 -0
  14. mcpforge/cli/commands/run.py +44 -0
  15. mcpforge/cli/commands/serve.py +31 -0
  16. mcpforge/cli/commands/test.py +60 -0
  17. mcpforge/cli/commands/validate.py +41 -0
  18. mcpforge/cli/context.py +14 -0
  19. mcpforge/cli/output.py +31 -0
  20. mcpforge/cli/scaffold.py +71 -0
  21. mcpforge/config/__init__.py +37 -0
  22. mcpforge/config/loader.py +44 -0
  23. mcpforge/config/merger.py +25 -0
  24. mcpforge/config/models.py +182 -0
  25. mcpforge/config/secrets.py +94 -0
  26. mcpforge/domain/__init__.py +37 -0
  27. mcpforge/domain/enums.py +42 -0
  28. mcpforge/domain/errors.py +13 -0
  29. mcpforge/domain/models.py +142 -0
  30. mcpforge/domain/parameters.py +33 -0
  31. mcpforge/domain/schemas.py +6 -0
  32. mcpforge/execution/__init__.py +36 -0
  33. mcpforge/execution/client.py +55 -0
  34. mcpforge/execution/engine.py +199 -0
  35. mcpforge/execution/errors.py +83 -0
  36. mcpforge/execution/limits.py +31 -0
  37. mcpforge/execution/request_builder.py +87 -0
  38. mcpforge/execution/response.py +64 -0
  39. mcpforge/execution/retry.py +69 -0
  40. mcpforge/filtering/__init__.py +7 -0
  41. mcpforge/filtering/evaluator.py +26 -0
  42. mcpforge/filtering/policies.py +44 -0
  43. mcpforge/filtering/selectors.py +31 -0
  44. mcpforge/generation/__init__.py +19 -0
  45. mcpforge/generation/collisions.py +24 -0
  46. mcpforge/generation/descriptions.py +15 -0
  47. mcpforge/generation/input_schema.py +53 -0
  48. mcpforge/generation/models.py +32 -0
  49. mcpforge/generation/naming.py +54 -0
  50. mcpforge/generation/service.py +64 -0
  51. mcpforge/ingestion/__init__.py +26 -0
  52. mcpforge/ingestion/errors.py +23 -0
  53. mcpforge/ingestion/loaders/__init__.py +7 -0
  54. mcpforge/ingestion/loaders/file.py +48 -0
  55. mcpforge/ingestion/loaders/remote.py +83 -0
  56. mcpforge/ingestion/normalization/__init__.py +23 -0
  57. mcpforge/ingestion/normalization/operation.py +83 -0
  58. mcpforge/ingestion/normalization/parameters.py +119 -0
  59. mcpforge/ingestion/normalization/references.py +57 -0
  60. mcpforge/ingestion/normalization/schemas.py +76 -0
  61. mcpforge/ingestion/parsers/__init__.py +8 -0
  62. mcpforge/ingestion/parsers/base.py +14 -0
  63. mcpforge/ingestion/parsers/manual.py +82 -0
  64. mcpforge/ingestion/parsers/openapi.py +87 -0
  65. mcpforge/ingestion/parsers/swagger.py +95 -0
  66. mcpforge/ingestion/service.py +84 -0
  67. mcpforge/ingestion/source.py +50 -0
  68. mcpforge/mcp/__init__.py +39 -0
  69. mcpforge/mcp/adapter.py +88 -0
  70. mcpforge/mcp/errors.py +25 -0
  71. mcpforge/mcp/server.py +46 -0
  72. mcpforge/mcp/tools.py +110 -0
  73. mcpforge/mcp/transports.py +51 -0
  74. mcpforge/observability/__init__.py +23 -0
  75. mcpforge/observability/diagnostics.py +45 -0
  76. mcpforge/observability/events.py +58 -0
  77. mcpforge/observability/logging.py +45 -0
  78. mcpforge/runtime/__init__.py +15 -0
  79. mcpforge/runtime/application.py +82 -0
  80. mcpforge/runtime/dependencies.py +77 -0
  81. mcpforge/runtime/lifecycle.py +50 -0
  82. mcpforge/security/__init__.py +40 -0
  83. mcpforge/security/hosts.py +32 -0
  84. mcpforge/security/redaction.py +60 -0
  85. mcpforge/security/safety.py +39 -0
  86. mcpforge/security/ssrf.py +77 -0
  87. mcpforge/security/validation.py +36 -0
  88. openapi_mcpforge-0.1.0.dist-info/METADATA +1566 -0
  89. openapi_mcpforge-0.1.0.dist-info/RECORD +92 -0
  90. openapi_mcpforge-0.1.0.dist-info/WHEEL +4 -0
  91. openapi_mcpforge-0.1.0.dist-info/entry_points.txt +2 -0
  92. 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
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11+-3776AB?logo=python&logoColor=white)](https://www.python.org/)
35
+ [![MCP SDK Compatible](https://img.shields.io/badge/MCP-SDK%20Compatible-6C5CE7)](https://modelcontextprotocol.io/)
36
+ [![Pydantic v2](https://img.shields.io/badge/Pydantic-v2-E92063?logo=pydantic&logoColor=white)](https://docs.pydantic.dev/)
37
+ [![HTTPX Async](https://img.shields.io/badge/HTTPX-Async-0E7490)](https://www.python-httpx.org/)
38
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
39
+ [![Code Style: Ruff](https://img.shields.io/badge/code%20style-Ruff-D7FF64)](https://docs.astral.sh/ruff/)
40
+ [![Type Checked: mypy](https://img.shields.io/badge/type_checked-mypy-2A6DB0)](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