Skip to content

Commit 599a78e

Browse files
kvzkvz
committed
docs(mcp): move spec to package README
1 parent eae5631 commit 599a78e

5 files changed

Lines changed: 83 additions & 119 deletions

File tree

‎.changeset/mcp-server-endpoint-env.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,4 @@
22
"@transloadit/mcp-server": patch
33
---
44

5-
Add TRANSLOADIT_ENDPOINT support and align MCP auth docs with bearer-token signature bypass.
6-
5+
Add TRANSLOADIT_ENDPOINT support, make the CLI binary executable, and refresh MCP auth docs.

‎README.md‎

Lines changed: 3 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Monorepo for Transloadit SDKs, shared packages, and the MCP server.
1717

1818
- `@transloadit/node` — Node.js SDK + CLI. See `packages/node/README.md`.
1919
- `transloadit` — Stable unscoped package (built from `@transloadit/node`).
20-
- `@transloadit/mcp-server` — MCP server (Streamable HTTP + stdio).
20+
- `@transloadit/mcp-server` — MCP server (Streamable HTTP + stdio). See `packages/mcp-server/README.md`.
2121
- `@transloadit/types` — Shared TypeScript types.
2222
- `@transloadit/utils` — Shared utilities.
2323
- `@transloadit/zod` — Zod schemas for Transloadit APIs.
@@ -45,109 +45,9 @@ const result = await client.createAssembly({
4545
})
4646
```
4747

48-
### MCP server (local)
48+
### MCP server
4949

50-
```bash
51-
npx @transloadit/mcp-server stdio
52-
```
53-
54-
```bash
55-
npx @transloadit/mcp-server http --host 127.0.0.1 --port 5723
56-
```
57-
58-
## MCP server design
59-
60-
The MCP server is thin glue over `@transloadit/node` and shared libraries. It exposes a small,
61-
agent-friendly tool surface while delegating all heavy lifting (uploads, polling, linting, resumes)
62-
to the SDK.
63-
64-
### Transports
65-
66-
- Streamable HTTP at `/mcp`.
67-
- stdio transport for local execution.
68-
- No legacy SSE.
69-
70-
### Auth model
71-
72-
**Hosted (api2.transloadit.com/mcp)**
73-
74-
- Call `POST https://api2.transloadit.com/token` with Auth Key/Secret (HTTP Basic Auth).
75-
- Use `Authorization: Bearer <access_token>` on API2 requests.
76-
- Bearer tokens **satisfy signature auth**; signature checks are enforced only for key/secret
77-
requests.
78-
79-
**Self-hosted**
80-
81-
- stdio and localhost HTTP require no MCP auth by default.
82-
- Non-localhost HTTP requires `TRANSLOADIT_MCP_TOKEN`.
83-
- API calls use `TRANSLOADIT_KEY` + `TRANSLOADIT_SECRET`, or bearer tokens if provided.
84-
85-
### Configuration
86-
87-
Environment:
88-
89-
- `TRANSLOADIT_KEY`
90-
- `TRANSLOADIT_SECRET`
91-
- `TRANSLOADIT_MCP_TOKEN`
92-
- `TRANSLOADIT_ENDPOINT` (optional, default `https://api2.transloadit.com`)
93-
94-
CLI:
95-
96-
- `transloadit-mcp http --host 127.0.0.1 --port 5723 --endpoint https://api2.transloadit.com`
97-
- `transloadit-mcp http --config path/to/config.json`
98-
99-
### Input files
100-
101-
```ts
102-
export type InputFile =
103-
| { kind: 'path'; field: string; path: string }
104-
| {
105-
kind: 'base64'
106-
field: string
107-
base64: string
108-
filename: string
109-
contentType?: string
110-
}
111-
| {
112-
kind: 'url'
113-
field: string
114-
url: string
115-
filename?: string
116-
contentType?: string
117-
}
118-
```
119-
120-
### Limits
121-
122-
- Hosted default request body limit: **1 MB** (JSON).
123-
- Hosted default `maxBase64Bytes`: **512_000** (decoded bytes).
124-
- Self-hosted default request body limit: **10 MB** (configurable).
125-
126-
### URL inputs
127-
128-
- By default URL files are **downloaded and uploaded via tus** (no instruction mutation).
129-
- If instructions already contain an `/http/import` step, the MCP server sets/overrides its `url`.
130-
- If multiple URLs and a single `/http/import` step exists, it supplies a `url` array.
131-
132-
### Resume behavior
133-
134-
If `assembly_url` is provided, the MCP server resumes uploads using Assembly status
135-
(`tus_uploads` + `uploads`). This requires stable, unique `field` names and file metadata
136-
(`filename` + `size`). Only **path-based** inputs resume; non-file inputs start fresh uploads.
137-
138-
### Tool surface
139-
140-
- `transloadit_create_assembly`
141-
- `transloadit_get_assembly_status`
142-
- `transloadit_wait_for_assembly`
143-
- `transloadit_validate_assembly`
144-
- `transloadit_list_robots`
145-
- `transloadit_get_robot_help`
146-
- `transloadit_list_golden_templates`
147-
148-
### Roadmap
149-
150-
- Next.js Claude Web flow to mint and hand off bearer tokens for MCP.
50+
See `packages/mcp-server/README.md` for MCP setup, auth, and tool docs.
15151

15252
## Development
15353

‎packages/mcp-server/README.md‎

Lines changed: 76 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,7 @@
11
# @transloadit/mcp-server
22

3-
Transloadit MCP server (Streamable HTTP + stdio).
4-
5-
This package provides a thin MCP wrapper around `@transloadit/node` for creating, validating, and
6-
monitoring Transloadit Assemblies with a delightful, agent-friendly DX.
3+
Transloadit MCP server (Streamable HTTP + stdio). This package is thin glue over
4+
`@transloadit/node` and shared libraries.
75

86
## Install
97

@@ -23,18 +21,83 @@ transloadit-mcp http --host 127.0.0.1 --port 5723
2321
transloadit-mcp stdio
2422
```
2523

26-
## Environment
24+
## Auth model
25+
26+
**Hosted (api2.transloadit.com/mcp)**
27+
28+
- Mint a token via `POST https://api2.transloadit.com/token` (HTTP Basic Auth with key+secret).
29+
- Use `Authorization: Bearer <access_token>` on API2 requests.
30+
- Bearer tokens **satisfy signature auth**; signature checks apply only to key/secret requests.
31+
32+
**Self-hosted**
33+
34+
- stdio and localhost HTTP require no MCP auth by default.
35+
- Non-localhost HTTP requires `TRANSLOADIT_MCP_TOKEN`.
36+
- API calls use `TRANSLOADIT_KEY` + `TRANSLOADIT_SECRET`, or bearer tokens if provided.
37+
38+
## Configuration
39+
40+
Environment:
41+
42+
- `TRANSLOADIT_KEY`
43+
- `TRANSLOADIT_SECRET`
44+
- `TRANSLOADIT_MCP_TOKEN`
45+
- `TRANSLOADIT_ENDPOINT` (optional, default `https://api2.transloadit.com`)
46+
47+
CLI:
48+
49+
- `transloadit-mcp http --host 127.0.0.1 --port 5723 --endpoint https://api2.transloadit.com`
50+
- `transloadit-mcp http --config path/to/config.json`
51+
52+
## Input files
53+
54+
```ts
55+
export type InputFile =
56+
| { kind: 'path'; field: string; path: string }
57+
| {
58+
kind: 'base64'
59+
field: string
60+
base64: string
61+
filename: string
62+
contentType?: string
63+
}
64+
| {
65+
kind: 'url'
66+
field: string
67+
url: string
68+
filename?: string
69+
contentType?: string
70+
}
71+
```
72+
73+
## Limits
74+
75+
- Hosted default request body limit: **1 MB** (JSON).
76+
- Hosted default `maxBase64Bytes`: **512_000** (decoded bytes).
77+
- Self-hosted default request body limit: **10 MB** (configurable).
78+
79+
## URL inputs
80+
81+
- By default URL files are **downloaded and uploaded via tus** (no instruction mutation).
82+
- If instructions already contain an `/http/import` step, the MCP server sets/overrides its `url`.
83+
- If multiple URLs and a single `/http/import` step exists, it supplies a `url` array.
84+
85+
## Resume behavior
2786
28-
- `TRANSLOADIT_KEY` / `TRANSLOADIT_SECRET` (required for API requests)
29-
- `TRANSLOADIT_MCP_TOKEN` (optional for static bearer auth on non-localhost HTTP)
30-
- `TRANSLOADIT_ENDPOINT` (optional, defaults to `https://api2.transloadit.com`)
87+
If `assembly_url` is provided, the MCP server resumes uploads using Assembly status
88+
(`tus_uploads` + `uploads`). This requires stable, unique `field` names and file metadata
89+
(`filename` + `size`). Only **path-based** inputs resume; non-file inputs start fresh uploads.
3190
3291
## Tool surface
3392
34-
See the MCP section in the repo README for the full tool list, auth model, and input formats.
93+
- `transloadit_create_assembly`
94+
- `transloadit_get_assembly_status`
95+
- `transloadit_wait_for_assembly`
96+
- `transloadit_validate_assembly`
97+
- `transloadit_list_robots`
98+
- `transloadit_get_robot_help`
99+
- `transloadit_list_golden_templates`
35100
36-
## Notes
101+
## Roadmap
37102
38-
- Hosted MCP calls use bearer tokens minted via `/token`.
39-
- Bearer tokens satisfy signature auth; signature checks apply only to key/secret requests.
40-
- URL inputs default to safe handling; base64 inputs have explicit limits to keep requests small.
103+
- Next.js Claude Web flow to mint and hand off bearer tokens for MCP.

‎packages/mcp-server/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@
3131
},
3232
"scripts": {
3333
"lint:ts": "yarn --cwd ../.. tsc:utils && yarn --cwd ../.. tsc:node && ../../node_modules/.bin/tsc --build tsconfig.build.json",
34-
"build": "yarn lint:ts",
34+
"build": "yarn lint:ts && chmod +x dist/cli.js",
3535
"test:unit": "yarn --cwd ../.. tsc:utils && yarn --cwd ../.. tsc:node && ../../node_modules/.bin/vitest run ./test/unit",
3636
"test:e2e": "yarn --cwd ../.. tsc:utils && yarn --cwd ../.. tsc:node && ../../node_modules/.bin/vitest run ./test/e2e",
3737
"check": "yarn lint:ts && yarn test:unit",

‎packages/mcp-server/src/cli.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
#!/usr/bin/env node
2+
13
import { readFile } from 'node:fs/promises'
24
import { createServer } from 'node:http'
35
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

0 commit comments

Comments
 (0)