mcp-api-translator 0.1.0 → 0.1.1
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.
- package/LICENSE +661 -661
- package/LICENSING.md +58 -58
- package/NOTICE +19 -19
- package/README.md +257 -257
- package/dist/{chunk-KSWSDM52.js → chunk-WNBBH3HV.js} +1 -1
- package/dist/chunk-WNBBH3HV.js.map +1 -0
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/lib.js +1 -1
- package/package.json +73 -73
- package/dist/chunk-KSWSDM52.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,257 +1,257 @@
|
|
|
1
|
-
# mcp-api-translator
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/mcp-api-translator)
|
|
4
|
-
[](https://github.com/krishgok/mcp-api-translator/actions/workflows/ci.yml)
|
|
5
|
-
[](LICENSE)
|
|
6
|
-
[](LICENSING.md)
|
|
7
|
-
[](https://modelcontextprotocol.io)
|
|
8
|
-
|
|
9
|
-
An **MCP server that generates MCP servers**. Give it an API definition (OpenAPI 3.0/3.1 or a
|
|
10
|
-
Postman collection) and it scaffolds a complete, runnable, _ownable_ TypeScript MCP server for that
|
|
11
|
-
API — so a service with no "MCP strategy" becomes usable and discoverable by AI models (Claude,
|
|
12
|
-
Cursor, Codex, …).
|
|
13
|
-
|
|
14
|
-
It is itself an MCP server: an agent connects to it and calls its tools to analyze a spec, generate
|
|
15
|
-
a server, or extend an existing one.
|
|
16
|
-
|
|
17
|
-
## Add to your AI stack
|
|
18
|
-
|
|
19
|
-
No install step. `npx` fetches and runs the latest published version — cross-platform, Node 20+.
|
|
20
|
-
|
|
21
|
-
### Claude Desktop / Claude Code
|
|
22
|
-
|
|
23
|
-
Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows:
|
|
24
|
-
`%APPDATA%\Claude\`) or your `mcp.json`:
|
|
25
|
-
|
|
26
|
-
```json
|
|
27
|
-
{
|
|
28
|
-
"mcpServers": {
|
|
29
|
-
"api-translator": {
|
|
30
|
-
"command": "npx",
|
|
31
|
-
"args": ["-y", "mcp-api-translator"]
|
|
32
|
-
}
|
|
33
|
-
}
|
|
34
|
-
}
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
<details>
|
|
38
|
-
<summary><strong>Cursor</strong></summary>
|
|
39
|
-
|
|
40
|
-
Add to `~/.cursor/mcp.json` (or the project-scoped `.cursor/mcp.json`):
|
|
41
|
-
|
|
42
|
-
```json
|
|
43
|
-
{
|
|
44
|
-
"mcpServers": {
|
|
45
|
-
"api-translator": {
|
|
46
|
-
"command": "npx",
|
|
47
|
-
"args": ["-y", "mcp-api-translator"]
|
|
48
|
-
}
|
|
49
|
-
}
|
|
50
|
-
}
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
</details>
|
|
54
|
-
|
|
55
|
-
<details>
|
|
56
|
-
<summary><strong>Cline (VS Code)</strong></summary>
|
|
57
|
-
|
|
58
|
-
Open the Cline sidebar → MCP Servers → Configure → add:
|
|
59
|
-
|
|
60
|
-
```json
|
|
61
|
-
{
|
|
62
|
-
"mcpServers": {
|
|
63
|
-
"api-translator": {
|
|
64
|
-
"command": "npx",
|
|
65
|
-
"args": ["-y", "mcp-api-translator"],
|
|
66
|
-
"disabled": false
|
|
67
|
-
}
|
|
68
|
-
}
|
|
69
|
-
}
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
</details>
|
|
73
|
-
|
|
74
|
-
<details>
|
|
75
|
-
<summary><strong>Continue.dev</strong></summary>
|
|
76
|
-
|
|
77
|
-
Add to `~/.continue/config.json` under `experimental.modelContextProtocolServers`:
|
|
78
|
-
|
|
79
|
-
```json
|
|
80
|
-
{
|
|
81
|
-
"experimental": {
|
|
82
|
-
"modelContextProtocolServers": [
|
|
83
|
-
{
|
|
84
|
-
"transport": {
|
|
85
|
-
"type": "stdio",
|
|
86
|
-
"command": "npx",
|
|
87
|
-
"args": ["-y", "mcp-api-translator"]
|
|
88
|
-
}
|
|
89
|
-
}
|
|
90
|
-
]
|
|
91
|
-
}
|
|
92
|
-
}
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
</details>
|
|
96
|
-
|
|
97
|
-
<details>
|
|
98
|
-
<summary><strong>Docker (no Node required)</strong></summary>
|
|
99
|
-
|
|
100
|
-
```json
|
|
101
|
-
{
|
|
102
|
-
"mcpServers": {
|
|
103
|
-
"api-translator": {
|
|
104
|
-
"command": "docker",
|
|
105
|
-
"args": ["run", "--rm", "-i", "ghcr.io/krishgok/mcp-api-translator:latest"]
|
|
106
|
-
}
|
|
107
|
-
}
|
|
108
|
-
}
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
To let the generator read specs from disk or write generated projects to a host path, mount the
|
|
112
|
-
directory: `-v ${PWD}:/workspace` and pass `/workspace/...` as `specPath` / `outputDir`.
|
|
113
|
-
|
|
114
|
-
</details>
|
|
115
|
-
|
|
116
|
-
Restart your client. Then try: _"analyze ./petstore.yaml, then generate an MCP server for just the
|
|
117
|
-
`pets` tag into ./petstore-mcp"_.
|
|
118
|
-
|
|
119
|
-
## Why this exists (and an honest take on the space)
|
|
120
|
-
|
|
121
|
-
Turning an OpenAPI spec into MCP "tool stubs" is **not novel** — [FastMCP's `from_openapi`](https://gofastmcp.com/integrations/openapi),
|
|
122
|
-
[Speakeasy/Gram](https://www.speakeasy.com/blog/generate-mcp-from-openapi), and several
|
|
123
|
-
`openapi-mcp-generator` projects already do the mechanical part. A naive 1:1 endpoint→tool generator
|
|
124
|
-
has no real advantage.
|
|
125
|
-
|
|
126
|
-
So this project focuses on the parts those tools get wrong or skip, which is where the actual value
|
|
127
|
-
of "make my API usable by AI models" lives:
|
|
128
|
-
|
|
129
|
-
1. **Curation, not just generation.** A 200-endpoint API naively becomes 200 tools, which wrecks a
|
|
130
|
-
model's tool-selection accuracy and blows out context. `analyze_spec` previews the tool list
|
|
131
|
-
first, and every command supports `includeTags` / `methods` / `pathGlob` / `excludeOperations`
|
|
132
|
-
filtering, with a warning when a server gets too large.
|
|
133
|
-
2. **Aggregation via append.** `extend_mcp_server` adds another API's tools to an existing generated
|
|
134
|
-
project, so you can build **one** MCP server spanning GitHub + Stripe + your internal API.
|
|
135
|
-
3. **An artifact you own.** Output is a normal TypeScript project (not a hosted black box): readable
|
|
136
|
-
per-tool files, env-based auth, a Dockerfile, and a `server.json` + client snippets for
|
|
137
|
-
publishing to the [official MCP Registry](https://registry.modelcontextprotocol.io).
|
|
138
|
-
|
|
139
|
-
If you only need throwaway, in-memory exposure of one API and don't care about owning the code,
|
|
140
|
-
FastMCP's runtime mode may suit you better — that's a deliberate non-goal here (see Limitations).
|
|
141
|
-
|
|
142
|
-
## Tech stack & rationale
|
|
143
|
-
|
|
144
|
-
- **TypeScript on the official `@modelcontextprotocol/sdk`** — MCP's Tier-1 SDK; the most portable
|
|
145
|
-
output target (runs on any Node host, `npx`-friendly for Claude/Cursor/Codex).
|
|
146
|
-
- **`@readme/openapi-parser`** for `$ref`-resolved OpenAPI 3.0/3.1 (+ best-effort Swagger 2.0);
|
|
147
|
-
Postman v2.1 is parsed directly.
|
|
148
|
-
- **Raw JSON Schema for generated tool inputs.** OpenAPI 3.1 schemas _are_ JSON Schema 2020-12,
|
|
149
|
-
which is exactly what an MCP tool's `inputSchema` expects — so there's no lossy zod round-trip.
|
|
150
|
-
- **String-builder templates, no template engine** — minimal deps, every emitter is snapshot-testable.
|
|
151
|
-
|
|
152
|
-
## The tools
|
|
153
|
-
|
|
154
|
-
| Tool | What it does |
|
|
155
|
-
| ------------------------- | ---------------------------------------------------------------------------------- |
|
|
156
|
-
| `analyze_spec` | Parse a spec and **preview** the tools that would be generated — no files written. |
|
|
157
|
-
| `generate_mcp_server` | Generate a complete TS MCP-server project into `outputDir`. |
|
|
158
|
-
| `extend_mcp_server` | Append another spec's tools to an existing generated project (idempotent). |
|
|
159
|
-
| `list_supported_features` | Report supported formats, auth schemes, transports, and limits. |
|
|
160
|
-
|
|
161
|
-
All spec inputs accept inline text (`spec`) or a local path (`specPath`), JSON or YAML.
|
|
162
|
-
|
|
163
|
-
## Two ways to use a spec: generate, or serve
|
|
164
|
-
|
|
165
|
-
- **Generate** ownable code (`generate_mcp_server`) when you want a project you can hand-edit,
|
|
166
|
-
self-host, and own — in **TypeScript** (default) or **Python** (`language: "python"`).
|
|
167
|
-
- **Serve** a live runtime proxy when you just want an API exposed to an agent **now**, with no
|
|
168
|
-
generated files to build or maintain:
|
|
169
|
-
|
|
170
|
-
```bash
|
|
171
|
-
mcp-api-translator serve --spec ./api.yaml # mount one API as live MCP tools
|
|
172
|
-
mcp-api-translator serve --spec ./a.yaml --spec ./b.yaml --methods GET,POST # aggregate several
|
|
173
|
-
```
|
|
174
|
-
|
|
175
|
-
`serve` runs the same request plan and env-based auth the generator would emit, so behavior matches
|
|
176
|
-
generated output exactly — it just skips the codegen step. See
|
|
177
|
-
[docs/serve-api-proposal.md](docs/serve-api-proposal.md) for the design and
|
|
178
|
-
[docs/market-analysis.md](docs/market-analysis.md) for why both models exist.
|
|
179
|
-
|
|
180
|
-
For the full end-to-end journey (analyze → curate → generate → run → aggregate → publish), see
|
|
181
|
-
[docs/usage-workflow.md](docs/usage-workflow.md).
|
|
182
|
-
|
|
183
|
-
## Generated project layout
|
|
184
|
-
|
|
185
|
-
```
|
|
186
|
-
src/index.ts # stdio entry (index.http.ts too if transport http/both)
|
|
187
|
-
src/server.ts # registers tools (low-level Server + JSON-Schema inputs)
|
|
188
|
-
src/tools/<name>.ts # one file per operation: schema + request plan
|
|
189
|
-
src/http/client.ts # builds the request, fetch, error handling
|
|
190
|
-
src/auth.ts # env-based credential injection
|
|
191
|
-
.env.example # API_BASE_URL + any detected credentials
|
|
192
|
-
server.json # MCP Registry manifest
|
|
193
|
-
client-config.md # paste-ready Claude / Cursor / Codex config
|
|
194
|
-
.mcp-translator.json # manifest that powers `extend_mcp_server`
|
|
195
|
-
```
|
|
196
|
-
|
|
197
|
-
## Assumptions & limitations
|
|
198
|
-
|
|
199
|
-
- **Inputs:** OpenAPI 3.0/3.1 and Postman v2.1 (Swagger 2.0 best-effort). No GraphQL/gRPC yet.
|
|
200
|
-
- **Output languages:** TypeScript (default) and Python. Both support `generate` and
|
|
201
|
-
`extend_mcp_server` (aggregating multiple APIs into one server).
|
|
202
|
-
- **Output quality tracks spec quality** — missing `operationId`s/descriptions yield weaker tool
|
|
203
|
-
names and docs. Curation helps; it can't invent semantics.
|
|
204
|
-
- **Auth:** API key / bearer / basic / pre-obtained OAuth token, plus the **OAuth2
|
|
205
|
-
client-credentials grant** (fetches + caches a token), all read from env. **No interactive
|
|
206
|
-
(authorization-code) OAuth flows** in v1.
|
|
207
|
-
- **Responses** are returned as JSON/text; no upstream streaming or automatic pagination.
|
|
208
|
-
- **Postman** parameter types are inferred from examples (Postman carries no formal schema).
|
|
209
|
-
- **Not a hosted service.** It runs locally/self-hosted: `generate` ownable code, or `serve` a live
|
|
210
|
-
in-process proxy. (No managed cloud offering — see [docs/serve-api-proposal.md](docs/serve-api-proposal.md) roadmap.)
|
|
211
|
-
|
|
212
|
-
## Security & trust model
|
|
213
|
-
|
|
214
|
-
A spec is treated as **untrusted input**: spec-derived strings are escaped before they're embedded
|
|
215
|
-
in generated source, generated tool names are restricted to `[A-Za-z0-9_]`, and all file writes stay
|
|
216
|
-
under `outputDir`. Two things are still inherent to what a generated server _does_, so review the
|
|
217
|
-
output before pointing it at credentials:
|
|
218
|
-
|
|
219
|
-
- **The generated server calls whatever base URL the spec declares** (or `API_BASE_URL`) and injects
|
|
220
|
-
your env-supplied credentials into those requests. Generating from a spec you don't trust, then
|
|
221
|
-
running it with real secrets, can send those secrets to a host the spec chose. Set `API_BASE_URL`
|
|
222
|
-
explicitly when in doubt.
|
|
223
|
-
- **Secrets are never embedded** in the generated project — `auth.ts` reads them from the environment
|
|
224
|
-
at runtime and `.env.example` ships with empty values.
|
|
225
|
-
|
|
226
|
-
To report a vulnerability, see [SECURITY.md](SECURITY.md).
|
|
227
|
-
|
|
228
|
-
## Development
|
|
229
|
-
|
|
230
|
-
```bash
|
|
231
|
-
npm install
|
|
232
|
-
npm test # unit + integration (parsers, curation, emit, append)
|
|
233
|
-
npm run typecheck
|
|
234
|
-
npm run build
|
|
235
|
-
npm run e2e # generate a sample project from the fixtures into build/e2e-out
|
|
236
|
-
```
|
|
237
|
-
|
|
238
|
-
Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). All commits must be signed off
|
|
239
|
-
under the [Developer Certificate of Origin](https://developercertificate.org/) (`git commit -s`).
|
|
240
|
-
|
|
241
|
-
## License & Attribution
|
|
242
|
-
|
|
243
|
-
`mcp-api-translator` is **dual-licensed** — © 2026 krishgok. See [LICENSING.md](LICENSING.md) for
|
|
244
|
-
the full details.
|
|
245
|
-
|
|
246
|
-
- **Open source:** [GNU AGPL-3.0-or-later](LICENSE). If you run a modified version to provide a
|
|
247
|
-
network service, the AGPL requires you to offer that version's complete source to its users.
|
|
248
|
-
- **Commercial:** a separate commercial license is available for embedding `mcp-api-translator` in
|
|
249
|
-
proprietary or closed-source products/services without AGPL obligations —
|
|
250
|
-
see [LICENSING.md](LICENSING.md).
|
|
251
|
-
- **Your generated output is yours.** Projects produced by running this tool are covered by a
|
|
252
|
-
[generated-output exception](LICENSING.md#3-generated-output-exception) and are **not** subject to
|
|
253
|
-
the AGPL — license them however you like.
|
|
254
|
-
|
|
255
|
-
Redistributions must retain [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE). The licenses do **not**
|
|
256
|
-
grant the right to use the "mcp-api-translator" name to endorse or promote forked or derivative
|
|
257
|
-
works without prior written permission.
|
|
1
|
+
# mcp-api-translator
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/mcp-api-translator)
|
|
4
|
+
[](https://github.com/krishgok/mcp-api-translator/actions/workflows/ci.yml)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
[](LICENSING.md)
|
|
7
|
+
[](https://modelcontextprotocol.io)
|
|
8
|
+
|
|
9
|
+
An **MCP server that generates MCP servers**. Give it an API definition (OpenAPI 3.0/3.1 or a
|
|
10
|
+
Postman collection) and it scaffolds a complete, runnable, _ownable_ TypeScript MCP server for that
|
|
11
|
+
API — so a service with no "MCP strategy" becomes usable and discoverable by AI models (Claude,
|
|
12
|
+
Cursor, Codex, …).
|
|
13
|
+
|
|
14
|
+
It is itself an MCP server: an agent connects to it and calls its tools to analyze a spec, generate
|
|
15
|
+
a server, or extend an existing one.
|
|
16
|
+
|
|
17
|
+
## Add to your AI stack
|
|
18
|
+
|
|
19
|
+
No install step. `npx` fetches and runs the latest published version — cross-platform, Node 20+.
|
|
20
|
+
|
|
21
|
+
### Claude Desktop / Claude Code
|
|
22
|
+
|
|
23
|
+
Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows:
|
|
24
|
+
`%APPDATA%\Claude\`) or your `mcp.json`:
|
|
25
|
+
|
|
26
|
+
```json
|
|
27
|
+
{
|
|
28
|
+
"mcpServers": {
|
|
29
|
+
"api-translator": {
|
|
30
|
+
"command": "npx",
|
|
31
|
+
"args": ["-y", "mcp-api-translator"]
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
<details>
|
|
38
|
+
<summary><strong>Cursor</strong></summary>
|
|
39
|
+
|
|
40
|
+
Add to `~/.cursor/mcp.json` (or the project-scoped `.cursor/mcp.json`):
|
|
41
|
+
|
|
42
|
+
```json
|
|
43
|
+
{
|
|
44
|
+
"mcpServers": {
|
|
45
|
+
"api-translator": {
|
|
46
|
+
"command": "npx",
|
|
47
|
+
"args": ["-y", "mcp-api-translator"]
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
</details>
|
|
54
|
+
|
|
55
|
+
<details>
|
|
56
|
+
<summary><strong>Cline (VS Code)</strong></summary>
|
|
57
|
+
|
|
58
|
+
Open the Cline sidebar → MCP Servers → Configure → add:
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
{
|
|
62
|
+
"mcpServers": {
|
|
63
|
+
"api-translator": {
|
|
64
|
+
"command": "npx",
|
|
65
|
+
"args": ["-y", "mcp-api-translator"],
|
|
66
|
+
"disabled": false
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
</details>
|
|
73
|
+
|
|
74
|
+
<details>
|
|
75
|
+
<summary><strong>Continue.dev</strong></summary>
|
|
76
|
+
|
|
77
|
+
Add to `~/.continue/config.json` under `experimental.modelContextProtocolServers`:
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
{
|
|
81
|
+
"experimental": {
|
|
82
|
+
"modelContextProtocolServers": [
|
|
83
|
+
{
|
|
84
|
+
"transport": {
|
|
85
|
+
"type": "stdio",
|
|
86
|
+
"command": "npx",
|
|
87
|
+
"args": ["-y", "mcp-api-translator"]
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
]
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
</details>
|
|
96
|
+
|
|
97
|
+
<details>
|
|
98
|
+
<summary><strong>Docker (no Node required)</strong></summary>
|
|
99
|
+
|
|
100
|
+
```json
|
|
101
|
+
{
|
|
102
|
+
"mcpServers": {
|
|
103
|
+
"api-translator": {
|
|
104
|
+
"command": "docker",
|
|
105
|
+
"args": ["run", "--rm", "-i", "ghcr.io/krishgok/mcp-api-translator:latest"]
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
To let the generator read specs from disk or write generated projects to a host path, mount the
|
|
112
|
+
directory: `-v ${PWD}:/workspace` and pass `/workspace/...` as `specPath` / `outputDir`.
|
|
113
|
+
|
|
114
|
+
</details>
|
|
115
|
+
|
|
116
|
+
Restart your client. Then try: _"analyze ./petstore.yaml, then generate an MCP server for just the
|
|
117
|
+
`pets` tag into ./petstore-mcp"_.
|
|
118
|
+
|
|
119
|
+
## Why this exists (and an honest take on the space)
|
|
120
|
+
|
|
121
|
+
Turning an OpenAPI spec into MCP "tool stubs" is **not novel** — [FastMCP's `from_openapi`](https://gofastmcp.com/integrations/openapi),
|
|
122
|
+
[Speakeasy/Gram](https://www.speakeasy.com/blog/generate-mcp-from-openapi), and several
|
|
123
|
+
`openapi-mcp-generator` projects already do the mechanical part. A naive 1:1 endpoint→tool generator
|
|
124
|
+
has no real advantage.
|
|
125
|
+
|
|
126
|
+
So this project focuses on the parts those tools get wrong or skip, which is where the actual value
|
|
127
|
+
of "make my API usable by AI models" lives:
|
|
128
|
+
|
|
129
|
+
1. **Curation, not just generation.** A 200-endpoint API naively becomes 200 tools, which wrecks a
|
|
130
|
+
model's tool-selection accuracy and blows out context. `analyze_spec` previews the tool list
|
|
131
|
+
first, and every command supports `includeTags` / `methods` / `pathGlob` / `excludeOperations`
|
|
132
|
+
filtering, with a warning when a server gets too large.
|
|
133
|
+
2. **Aggregation via append.** `extend_mcp_server` adds another API's tools to an existing generated
|
|
134
|
+
project, so you can build **one** MCP server spanning GitHub + Stripe + your internal API.
|
|
135
|
+
3. **An artifact you own.** Output is a normal TypeScript project (not a hosted black box): readable
|
|
136
|
+
per-tool files, env-based auth, a Dockerfile, and a `server.json` + client snippets for
|
|
137
|
+
publishing to the [official MCP Registry](https://registry.modelcontextprotocol.io).
|
|
138
|
+
|
|
139
|
+
If you only need throwaway, in-memory exposure of one API and don't care about owning the code,
|
|
140
|
+
FastMCP's runtime mode may suit you better — that's a deliberate non-goal here (see Limitations).
|
|
141
|
+
|
|
142
|
+
## Tech stack & rationale
|
|
143
|
+
|
|
144
|
+
- **TypeScript on the official `@modelcontextprotocol/sdk`** — MCP's Tier-1 SDK; the most portable
|
|
145
|
+
output target (runs on any Node host, `npx`-friendly for Claude/Cursor/Codex).
|
|
146
|
+
- **`@readme/openapi-parser`** for `$ref`-resolved OpenAPI 3.0/3.1 (+ best-effort Swagger 2.0);
|
|
147
|
+
Postman v2.1 is parsed directly.
|
|
148
|
+
- **Raw JSON Schema for generated tool inputs.** OpenAPI 3.1 schemas _are_ JSON Schema 2020-12,
|
|
149
|
+
which is exactly what an MCP tool's `inputSchema` expects — so there's no lossy zod round-trip.
|
|
150
|
+
- **String-builder templates, no template engine** — minimal deps, every emitter is snapshot-testable.
|
|
151
|
+
|
|
152
|
+
## The tools
|
|
153
|
+
|
|
154
|
+
| Tool | What it does |
|
|
155
|
+
| ------------------------- | ---------------------------------------------------------------------------------- |
|
|
156
|
+
| `analyze_spec` | Parse a spec and **preview** the tools that would be generated — no files written. |
|
|
157
|
+
| `generate_mcp_server` | Generate a complete TS MCP-server project into `outputDir`. |
|
|
158
|
+
| `extend_mcp_server` | Append another spec's tools to an existing generated project (idempotent). |
|
|
159
|
+
| `list_supported_features` | Report supported formats, auth schemes, transports, and limits. |
|
|
160
|
+
|
|
161
|
+
All spec inputs accept inline text (`spec`) or a local path (`specPath`), JSON or YAML.
|
|
162
|
+
|
|
163
|
+
## Two ways to use a spec: generate, or serve
|
|
164
|
+
|
|
165
|
+
- **Generate** ownable code (`generate_mcp_server`) when you want a project you can hand-edit,
|
|
166
|
+
self-host, and own — in **TypeScript** (default) or **Python** (`language: "python"`).
|
|
167
|
+
- **Serve** a live runtime proxy when you just want an API exposed to an agent **now**, with no
|
|
168
|
+
generated files to build or maintain:
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
mcp-api-translator serve --spec ./api.yaml # mount one API as live MCP tools
|
|
172
|
+
mcp-api-translator serve --spec ./a.yaml --spec ./b.yaml --methods GET,POST # aggregate several
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
`serve` runs the same request plan and env-based auth the generator would emit, so behavior matches
|
|
176
|
+
generated output exactly — it just skips the codegen step. See
|
|
177
|
+
[docs/serve-api-proposal.md](docs/serve-api-proposal.md) for the design and
|
|
178
|
+
[docs/market-analysis.md](docs/market-analysis.md) for why both models exist.
|
|
179
|
+
|
|
180
|
+
For the full end-to-end journey (analyze → curate → generate → run → aggregate → publish), see
|
|
181
|
+
[docs/usage-workflow.md](docs/usage-workflow.md).
|
|
182
|
+
|
|
183
|
+
## Generated project layout
|
|
184
|
+
|
|
185
|
+
```
|
|
186
|
+
src/index.ts # stdio entry (index.http.ts too if transport http/both)
|
|
187
|
+
src/server.ts # registers tools (low-level Server + JSON-Schema inputs)
|
|
188
|
+
src/tools/<name>.ts # one file per operation: schema + request plan
|
|
189
|
+
src/http/client.ts # builds the request, fetch, error handling
|
|
190
|
+
src/auth.ts # env-based credential injection
|
|
191
|
+
.env.example # API_BASE_URL + any detected credentials
|
|
192
|
+
server.json # MCP Registry manifest
|
|
193
|
+
client-config.md # paste-ready Claude / Cursor / Codex config
|
|
194
|
+
.mcp-translator.json # manifest that powers `extend_mcp_server`
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
## Assumptions & limitations
|
|
198
|
+
|
|
199
|
+
- **Inputs:** OpenAPI 3.0/3.1 and Postman v2.1 (Swagger 2.0 best-effort). No GraphQL/gRPC yet.
|
|
200
|
+
- **Output languages:** TypeScript (default) and Python. Both support `generate` and
|
|
201
|
+
`extend_mcp_server` (aggregating multiple APIs into one server).
|
|
202
|
+
- **Output quality tracks spec quality** — missing `operationId`s/descriptions yield weaker tool
|
|
203
|
+
names and docs. Curation helps; it can't invent semantics.
|
|
204
|
+
- **Auth:** API key / bearer / basic / pre-obtained OAuth token, plus the **OAuth2
|
|
205
|
+
client-credentials grant** (fetches + caches a token), all read from env. **No interactive
|
|
206
|
+
(authorization-code) OAuth flows** in v1.
|
|
207
|
+
- **Responses** are returned as JSON/text; no upstream streaming or automatic pagination.
|
|
208
|
+
- **Postman** parameter types are inferred from examples (Postman carries no formal schema).
|
|
209
|
+
- **Not a hosted service.** It runs locally/self-hosted: `generate` ownable code, or `serve` a live
|
|
210
|
+
in-process proxy. (No managed cloud offering — see [docs/serve-api-proposal.md](docs/serve-api-proposal.md) roadmap.)
|
|
211
|
+
|
|
212
|
+
## Security & trust model
|
|
213
|
+
|
|
214
|
+
A spec is treated as **untrusted input**: spec-derived strings are escaped before they're embedded
|
|
215
|
+
in generated source, generated tool names are restricted to `[A-Za-z0-9_]`, and all file writes stay
|
|
216
|
+
under `outputDir`. Two things are still inherent to what a generated server _does_, so review the
|
|
217
|
+
output before pointing it at credentials:
|
|
218
|
+
|
|
219
|
+
- **The generated server calls whatever base URL the spec declares** (or `API_BASE_URL`) and injects
|
|
220
|
+
your env-supplied credentials into those requests. Generating from a spec you don't trust, then
|
|
221
|
+
running it with real secrets, can send those secrets to a host the spec chose. Set `API_BASE_URL`
|
|
222
|
+
explicitly when in doubt.
|
|
223
|
+
- **Secrets are never embedded** in the generated project — `auth.ts` reads them from the environment
|
|
224
|
+
at runtime and `.env.example` ships with empty values.
|
|
225
|
+
|
|
226
|
+
To report a vulnerability, see [SECURITY.md](SECURITY.md).
|
|
227
|
+
|
|
228
|
+
## Development
|
|
229
|
+
|
|
230
|
+
```bash
|
|
231
|
+
npm install
|
|
232
|
+
npm test # unit + integration (parsers, curation, emit, append)
|
|
233
|
+
npm run typecheck
|
|
234
|
+
npm run build
|
|
235
|
+
npm run e2e # generate a sample project from the fixtures into build/e2e-out
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). All commits must be signed off
|
|
239
|
+
under the [Developer Certificate of Origin](https://developercertificate.org/) (`git commit -s`).
|
|
240
|
+
|
|
241
|
+
## License & Attribution
|
|
242
|
+
|
|
243
|
+
`mcp-api-translator` is **dual-licensed** — © 2026 krishgok. See [LICENSING.md](LICENSING.md) for
|
|
244
|
+
the full details.
|
|
245
|
+
|
|
246
|
+
- **Open source:** [GNU AGPL-3.0-or-later](LICENSE). If you run a modified version to provide a
|
|
247
|
+
network service, the AGPL requires you to offer that version's complete source to its users.
|
|
248
|
+
- **Commercial:** a separate commercial license is available for embedding `mcp-api-translator` in
|
|
249
|
+
proprietary or closed-source products/services without AGPL obligations —
|
|
250
|
+
see [LICENSING.md](LICENSING.md).
|
|
251
|
+
- **Your generated output is yours.** Projects produced by running this tool are covered by a
|
|
252
|
+
[generated-output exception](LICENSING.md#3-generated-output-exception) and are **not** subject to
|
|
253
|
+
the AGPL — license them however you like.
|
|
254
|
+
|
|
255
|
+
Redistributions must retain [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE). The licenses do **not**
|
|
256
|
+
grant the right to use the "mcp-api-translator" name to endorse or promote forked or derivative
|
|
257
|
+
works without prior written permission.
|