qodflow-mcp 0.1.0

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 (3) hide show
  1. package/README.md +103 -0
  2. package/dist/index.js +549 -0
  3. package/package.json +33 -0
package/README.md ADDED
@@ -0,0 +1,103 @@
1
+ # @qodflow/mcp-server
2
+
3
+ Model Context Protocol (MCP) server for QodFlow. Lets AI agents like Claude Desktop, Cursor, and ChatGPT Desktop drive a QodFlow workspace through a Personal Access Token.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ cd mcp-server
9
+ npm install
10
+ npm run build
11
+ ```
12
+
13
+ The binary is exposed as `qodflow-mcp`.
14
+
15
+ ## Configure your agent
16
+
17
+ ### Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`)
18
+
19
+ ```json
20
+ {
21
+ "mcpServers": {
22
+ "qodflow": {
23
+ "command": "node",
24
+ "args": ["/absolute/path/to/qodflow/mcp-server/dist/index.js"],
25
+ "env": {
26
+ "QODFLOW_API_TOKEN": "qf_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx"
27
+ }
28
+ }
29
+ }
30
+ }
31
+ ```
32
+
33
+ ### Cursor / ChatGPT Desktop
34
+
35
+ Use the same `command + env` shape; consult your client's docs for the exact config path.
36
+
37
+ ## Get a token
38
+
39
+ 1. Sign in to QodFlow.
40
+ 2. Go to **Settings → API Keys**.
41
+ 3. Click **New token**, give it a name, pick the minimum scopes you need (`jobs:read` + `stages:read` is enough for the current toolset), and copy the plaintext **once** — it isn't shown again.
42
+ 4. Paste it as `QODFLOW_API_TOKEN` in your agent config.
43
+
44
+ For integration testing, toggle **Test mode** at token creation; the prefix becomes `qf_test_` and the token binds to test-mode Stripe products.
45
+
46
+ ## Tools (v0.1)
47
+
48
+ | Tool | Scope required | Plan | Description |
49
+ | ------------------------ | -------------- | -------- | ----------- |
50
+ | `list_jobs` | `jobs:read` | any | Most recent jobs, paginated. |
51
+ | `list_stages` | `stages:read` | any | Pipeline stages with order, color, SLA. |
52
+ | `list_tags` | `tags:read` | any | Tags defined on the workspace. |
53
+ | `list_members` | `members:read` | any | Team members (id, name, masked email hint, role). |
54
+ | `create_job` | `jobs:write` | any\* | Create a job in the first (or given) stage. |
55
+ | `update_job` | `jobs:write` | any\* | Update title, description, priority, PO number. |
56
+ | `move_job` | `jobs:write` | any | Move a job to another stage. |
57
+ | `assign_job` | `mcp:assign` | DIAMOND | Assign a job to a member (or `null` to unassign). |
58
+ | `create_tag` | `tags:write` | PREMIUM+ | Create a tag. |
59
+ | `update_stage` | `stages:write` | any\* | Rename a stage, change SLA/color. |
60
+ | `claim_job` / `release_job` | `mcp:claim` | any | Atomically claim/release a job (lease-based). |
61
+ | `report_progress` | `mcp:claim` | any | Append a progress note to a job's timeline. |
62
+ | `request_human_decision` | `mcp:decide` | any | Ask a human to pick between options. |
63
+ | `resolve_decision` | `mcp:resolve` | any | Resolve an open decision. |
64
+ | `attach_evidence` | `mcp:evidence` | any | Attach a note (+ optional URL) as evidence. |
65
+ | `get_timeline` / `list_decisions` / `list_evidence` | `jobs:read` | any | Read a job's timeline / decisions / evidence. |
66
+
67
+ \* Subject to plan limits (active-job cap, priority/tags gating). When a call
68
+ exceeds a plan gate or quota the tool returns an error whose text includes an
69
+ `Upgrade: <url>` hint you can relay to the user.
70
+
71
+ Destructive verbs (delete_team, mass move, etc.) are **never** exposed via MCP. They live behind the UI confirm-literal guard only.
72
+
73
+ ## Security model
74
+
75
+ - Token scopes are enforced server-side on every call — this binary cannot grant itself privileges it wasn't issued.
76
+ - Audit log is written for every token-authed request and is visible to team owners.
77
+ - Killswitch: revoke the token from **Settings → API Keys** to stop the agent immediately.
78
+ - Rate limit: 120 requests/minute per token (server-enforced).
79
+ - This binary does not persist anything to disk and does not phone home — it only talks to `QODFLOW_API_BASE` (default `https://www.qodflow.com`).
80
+
81
+ ### Token handling on shared workstations
82
+
83
+ The MCP host (Claude Desktop, Cursor) launches this binary as a child process and passes the token via the `QODFLOW_API_TOKEN` environment variable. On Linux that environment is readable by any other process running as the same user via `/proc/PID/environ`, and similar exposure exists on macOS via `ps -ewww` in some configurations. If you operate on a shared workstation or a machine where other untrusted code runs (CI runners, contractor laptops, etc.):
84
+
85
+ 1. **Prefer a per-user token over a shared one** — issue narrow scopes and rotate every 90 days.
86
+ 2. **Use the OS keychain** for storage: `security add-generic-password` (macOS), `secret-tool` (GNOME), `wincred` (Windows). Have your host config read from it at launch rather than embedding the literal token.
87
+ 3. **Future:** v1.1 will accept the token via stdin write at startup instead of `env`, eliminating `/proc/PID/environ` exposure. Track issue [token-via-stdin] for adoption.
88
+ 4. **Never** commit `claude_desktop_config.json` or equivalent to a repository. It contains your token.
89
+
90
+ ## Environment variables
91
+
92
+ | Var | Required | Default | Description |
93
+ | ------------------- | -------- | -------------------- | ----------- |
94
+ | `QODFLOW_API_TOKEN` | yes | — | `qf_live_…` or `qf_test_…` PAT. |
95
+ | `QODFLOW_API_BASE` | no | `https://www.qodflow.com` | Override for self-hosted or local dev. Must be the **www** host — the apex redirects and Node strips the auth header on the cross-origin hop. |
96
+
97
+ ## Development
98
+
99
+ ```bash
100
+ npm run dev # tsx watch on src/index.ts
101
+ ```
102
+
103
+ Roadmap: write tools (create job, move job), then audit-log read, then v1.1 hosted-HTTP transport with OAuth.
package/dist/index.js ADDED
@@ -0,0 +1,549 @@
1
+ #!/usr/bin/env node
2
+ // QodFlow MCP server — stdio transport, v1.
3
+ //
4
+ // Wires AI agents (Claude Desktop, Cursor, ChatGPT Desktop) to the QodFlow
5
+ // public REST API via a Personal Access Token. The token determines which
6
+ // team the agent operates against and which scopes it has — there is no
7
+ // separate auth between the agent and this server.
8
+ //
9
+ // Tools intentionally start with the SHIP-tier subset from
10
+ // docs/handoff/shippable-scope-and-toolchain.md §2 — read-only and low-blast
11
+ // mutations. Destructive verbs (delete_team etc.) are NEVER exposed here.
12
+ // They live behind the UI confirm-literal guard only.
13
+ //
14
+ // Run:
15
+ // QODFLOW_API_TOKEN=qf_live_xxxx qodflow-mcp
16
+ //
17
+ // Claude Desktop config example:
18
+ // {
19
+ // "mcpServers": {
20
+ // "qodflow": {
21
+ // "command": "qodflow-mcp",
22
+ // "env": { "QODFLOW_API_TOKEN": "qf_live_..." }
23
+ // }
24
+ // }
25
+ // }
26
+ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
27
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
28
+ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
29
+ import { z } from "zod";
30
+ const TOKEN = process.env.QODFLOW_API_TOKEN;
31
+ // MUST be the www host: the apex (qodflow.com) 307-redirects to www, and Node's
32
+ // fetch strips the Authorization header on a cross-origin redirect, so every
33
+ // call would 401. Point straight at www to keep the Bearer token attached.
34
+ const API_BASE = process.env.QODFLOW_API_BASE ?? "https://www.qodflow.com";
35
+ if (!TOKEN) {
36
+ console.error("QODFLOW_API_TOKEN env var is required");
37
+ process.exit(1);
38
+ }
39
+ if (!/^qf_(live|test)_[a-z0-9]{8}_[a-z0-9]{24}$/.test(TOKEN)) {
40
+ console.error("QODFLOW_API_TOKEN format invalid (expected qf_live_xxxx_xxxxxxxx…)");
41
+ process.exit(1);
42
+ }
43
+ async function api(path, init) {
44
+ const res = await fetch(`${API_BASE}${path}`, {
45
+ ...init,
46
+ headers: {
47
+ Authorization: `Bearer ${TOKEN}`,
48
+ "Content-Type": "application/json",
49
+ "User-Agent": "qodflow-mcp/0.1.0",
50
+ ...(init?.headers ?? {}),
51
+ },
52
+ });
53
+ const text = await res.text();
54
+ let json;
55
+ try {
56
+ json = text ? JSON.parse(text) : null;
57
+ }
58
+ catch {
59
+ throw new Error(`Non-JSON response from ${path}: ${text.slice(0, 200)}`);
60
+ }
61
+ if (!res.ok) {
62
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
63
+ const e = json?.error;
64
+ const msg = e?.message ?? `HTTP ${res.status}`;
65
+ // Surface the upgrade URL so the agent can relay an actionable upsell to the
66
+ // human (the alert-that-explains), not just a bare error.
67
+ const url = e?.details?.upgradeUrl;
68
+ throw new Error(url ? `${msg} Upgrade: ${url}` : msg);
69
+ }
70
+ return json;
71
+ }
72
+ // ---- Tool schemas ----
73
+ const ListJobsArgs = z.object({
74
+ limit: z.number().int().min(1).max(100).default(25).optional(),
75
+ cursor: z.string().optional(),
76
+ });
77
+ const GetStagesArgs = z.object({});
78
+ const CreateJobArgs = z.object({
79
+ title: z.string().min(1).max(200),
80
+ description: z.string().max(5000).optional(),
81
+ stageId: z.string().optional(),
82
+ priority: z.enum(["NORMAL", "FLAGGED", "URGENT"]).optional(),
83
+ });
84
+ const UpdateJobArgs = z.object({
85
+ id: z.string(),
86
+ title: z.string().min(1).max(200).optional(),
87
+ description: z.string().max(5000).optional(),
88
+ priority: z.enum(["NORMAL", "FLAGGED", "URGENT"]).optional(),
89
+ poNumber: z.string().optional(),
90
+ });
91
+ const ListTagsArgs = z.object({});
92
+ const ListMembersArgs = z.object({});
93
+ const CreateTagArgs = z.object({ name: z.string().min(1).max(40), color: z.string().optional() });
94
+ const UpdateStageArgs = z.object({
95
+ id: z.string(),
96
+ name: z.string().min(1).max(60).optional(),
97
+ slaDays: z.number().int().min(1).max(365).optional(),
98
+ color: z.string().optional(),
99
+ });
100
+ const AssignJobArgs = z.object({
101
+ jobId: z.string(),
102
+ assignedToId: z.string().min(1).nullable(),
103
+ });
104
+ const MoveJobArgs = z.object({
105
+ jobId: z.string(),
106
+ stageId: z.string(),
107
+ reason: z.string().max(280).optional(),
108
+ });
109
+ // MCP agent-collaboration primitives (Phase 1-3 of docs/planning/MCP-PLAN.md).
110
+ const ClaimJobArgs = z.object({
111
+ jobId: z.string(),
112
+ leaseMinutes: z.number().int().min(1).max(240).optional(),
113
+ note: z.string().max(280).optional(),
114
+ });
115
+ const ReleaseJobArgs = z.object({
116
+ jobId: z.string(),
117
+ note: z.string().max(280).optional(),
118
+ });
119
+ const ReportProgressArgs = z.object({
120
+ jobId: z.string(),
121
+ note: z.string().min(1).max(280),
122
+ });
123
+ const RequestHumanDecisionArgs = z.object({
124
+ jobId: z.string(),
125
+ question: z.string().min(1).max(280),
126
+ options: z.array(z.object({ id: z.string().min(1).max(40), label: z.string().min(1).max(80) })).min(2).max(6),
127
+ ttlDays: z.number().int().min(1).max(30).optional(),
128
+ });
129
+ const AttachEvidenceArgs = z.object({
130
+ jobId: z.string(),
131
+ note: z.string().min(1).max(280),
132
+ url: z.string().url().max(2048).optional(),
133
+ });
134
+ const GetTimelineArgs = z.object({
135
+ jobId: z.string(),
136
+ limit: z.number().int().min(1).max(100).optional(),
137
+ cursor: z.string().optional(),
138
+ });
139
+ const ListDecisionsArgs = z.object({ jobId: z.string() });
140
+ const ListEvidenceArgs = z.object({ jobId: z.string() });
141
+ const ResolveDecisionArgs = z.object({
142
+ decisionId: z.string(),
143
+ chosenOption: z.string().min(1).max(40),
144
+ humanResponseExcerpt: z.string().min(1).max(280),
145
+ });
146
+ // Server setup
147
+ const server = new Server({ name: "qodflow", version: "0.1.0" }, { capabilities: { tools: {} } });
148
+ // Tool annotations per MCP spec (2025-06-18) — clients use these to decide
149
+ // whether to prompt the user before calling. We pin them static here so a
150
+ // hijacked server cannot rug-pull descriptions (Invariant Labs Apr 2025).
151
+ //
152
+ // Annotation legend:
153
+ // readOnlyHint — tool only reads data, no state change
154
+ // destructiveHint — tool may make irreversible changes (none in our surface)
155
+ // idempotentHint — repeated calls with same args = same effect (use with Idempotency-Key)
156
+ // openWorldHint — tool reaches external systems (everything here hits qodflow.com only)
157
+ const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
158
+ const WRITE_NONDESTR = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
159
+ const WRITE_IDEMPOTENT = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
160
+ const TOOLS = [
161
+ {
162
+ name: "list_jobs",
163
+ description: "List jobs in the QodFlow workspace bound to this token. Returns the most recent first. Cursor-paginated.",
164
+ annotations: READ_ONLY,
165
+ inputSchema: {
166
+ type: "object",
167
+ properties: {
168
+ limit: { type: "integer", minimum: 1, maximum: 100, default: 25 },
169
+ cursor: { type: "string", description: "Pagination cursor from a previous response." },
170
+ },
171
+ },
172
+ },
173
+ {
174
+ name: "list_stages",
175
+ description: "List pipeline stages for the workspace. Each stage has an order, name, color, and SLA in days. Use stage IDs when referencing positions.",
176
+ annotations: READ_ONLY,
177
+ inputSchema: { type: "object", properties: {} },
178
+ },
179
+ {
180
+ name: "create_job",
181
+ description: "Create a new job in the workspace. Placed in the first stage unless stageId is provided. Requires the jobs:write scope on the token.",
182
+ annotations: WRITE_NONDESTR, inputSchema: {
183
+ type: "object",
184
+ required: ["title"],
185
+ properties: {
186
+ title: { type: "string", minLength: 1, maxLength: 200 },
187
+ description: { type: "string", maxLength: 5000 },
188
+ stageId: { type: "string" },
189
+ priority: { type: "string", enum: ["NORMAL", "FLAGGED", "URGENT"] },
190
+ },
191
+ },
192
+ },
193
+ {
194
+ name: "update_job",
195
+ description: "Update a job's title, description, priority, or PO number. To move a job between stages use move_job; to assign it use assign_job. Requires jobs:write.",
196
+ annotations: WRITE_IDEMPOTENT, inputSchema: {
197
+ type: "object",
198
+ required: ["id"],
199
+ properties: {
200
+ id: { type: "string" },
201
+ title: { type: "string", minLength: 1, maxLength: 200 },
202
+ description: { type: "string", maxLength: 5000 },
203
+ priority: { type: "string", enum: ["NORMAL", "FLAGGED", "URGENT"] },
204
+ poNumber: { type: "string" },
205
+ },
206
+ },
207
+ },
208
+ {
209
+ name: "move_job",
210
+ description: "Move a job to a different stage. Use list_stages to get stage IDs. Requires jobs:write.",
211
+ annotations: WRITE_IDEMPOTENT,
212
+ inputSchema: {
213
+ type: "object",
214
+ required: ["jobId", "stageId"],
215
+ properties: {
216
+ jobId: { type: "string" },
217
+ stageId: { type: "string" },
218
+ reason: { type: "string", maxLength: 280 },
219
+ },
220
+ },
221
+ },
222
+ {
223
+ name: "assign_job",
224
+ description: "Assign a job to a team member, or pass assignedToId:null to unassign. Use list_members to get member IDs. Requires the mcp:assign scope and the DIAMOND plan.",
225
+ annotations: WRITE_IDEMPOTENT,
226
+ inputSchema: {
227
+ type: "object",
228
+ required: ["jobId", "assignedToId"],
229
+ properties: {
230
+ jobId: { type: "string" },
231
+ assignedToId: { type: ["string", "null"], description: "Member user id, or null to unassign." },
232
+ },
233
+ },
234
+ },
235
+ {
236
+ name: "list_tags",
237
+ description: "List all tags defined on the workspace. Requires tags:read.",
238
+ annotations: READ_ONLY, inputSchema: { type: "object", properties: {} },
239
+ },
240
+ {
241
+ name: "list_members",
242
+ description: "List team members with their roles. Requires members:read.",
243
+ annotations: READ_ONLY, inputSchema: { type: "object", properties: {} },
244
+ },
245
+ {
246
+ name: "create_tag",
247
+ description: "Create a new tag for the workspace. Requires tags:write.",
248
+ annotations: WRITE_NONDESTR, inputSchema: {
249
+ type: "object",
250
+ required: ["name"],
251
+ properties: {
252
+ name: { type: "string", minLength: 1, maxLength: 40 },
253
+ color: { type: "string" },
254
+ },
255
+ },
256
+ },
257
+ {
258
+ name: "update_stage",
259
+ description: "Rename a stage, change its SLA, or change its color. Requires stages:write.",
260
+ annotations: WRITE_IDEMPOTENT, inputSchema: {
261
+ type: "object",
262
+ required: ["id"],
263
+ properties: {
264
+ id: { type: "string" },
265
+ name: { type: "string", minLength: 1, maxLength: 60 },
266
+ slaDays: { type: "integer", minimum: 1, maximum: 365 },
267
+ color: { type: "string" },
268
+ },
269
+ },
270
+ },
271
+ // --- Agent-collaboration primitives ---
272
+ {
273
+ name: "claim_job",
274
+ description: "Atomically claim a job for this agent so other agents won't pick it up. Includes a lease (default 30 min, max 240) so a crashed agent does not lock the job forever. Requires mcp:claim scope. Returns CONFLICT if already claimed by someone else with a fresh lease.",
275
+ annotations: WRITE_IDEMPOTENT, inputSchema: {
276
+ type: "object",
277
+ required: ["jobId"],
278
+ properties: {
279
+ jobId: { type: "string" },
280
+ leaseMinutes: { type: "integer", minimum: 1, maximum: 240, default: 30 },
281
+ note: { type: "string", maxLength: 280 },
282
+ },
283
+ },
284
+ },
285
+ {
286
+ name: "release_job",
287
+ description: "Release a job this agent currently holds. Lets another actor pick it up. Requires mcp:claim.",
288
+ annotations: WRITE_IDEMPOTENT, inputSchema: {
289
+ type: "object",
290
+ required: ["jobId"],
291
+ properties: { jobId: { type: "string" }, note: { type: "string", maxLength: 280 } },
292
+ },
293
+ },
294
+ {
295
+ name: "report_progress",
296
+ description: "Append a 280-character narration entry to the job's timeline so the human can see what this agent has been doing. Call this at every meaningful step — humans skim, agents forget. Requires mcp:claim.",
297
+ annotations: WRITE_NONDESTR, inputSchema: {
298
+ type: "object",
299
+ required: ["jobId", "note"],
300
+ properties: { jobId: { type: "string" }, note: { type: "string", minLength: 1, maxLength: 280 } },
301
+ },
302
+ },
303
+ {
304
+ name: "request_human_decision",
305
+ description: "Ask the human team to pick one of 2-6 structured options. Creates a DecisionRequest that appears in their /my-tasks inbox. PREMIUM-plan only — FREE will receive PLAN_UPGRADE_REQUIRED with a structured upgrade prompt. Requires mcp:decide.",
306
+ annotations: WRITE_NONDESTR, inputSchema: {
307
+ type: "object",
308
+ required: ["jobId", "question", "options"],
309
+ properties: {
310
+ jobId: { type: "string" },
311
+ question: { type: "string", minLength: 1, maxLength: 280 },
312
+ options: {
313
+ type: "array",
314
+ minItems: 2,
315
+ maxItems: 6,
316
+ items: {
317
+ type: "object",
318
+ required: ["id", "label"],
319
+ properties: {
320
+ id: { type: "string", minLength: 1, maxLength: 40 },
321
+ label: { type: "string", minLength: 1, maxLength: 80 },
322
+ },
323
+ },
324
+ },
325
+ ttlDays: { type: "integer", minimum: 1, maximum: 30, default: 7 },
326
+ },
327
+ },
328
+ },
329
+ {
330
+ name: "attach_evidence",
331
+ description: "Attach a 280-character note and optional external URL as evidence that work was completed. URLs must be http(s) and never target internal/private hosts — they are display-only, never fetched server-side. PREMIUM-plan only. Requires mcp:evidence.",
332
+ annotations: WRITE_NONDESTR, inputSchema: {
333
+ type: "object",
334
+ required: ["jobId", "note"],
335
+ properties: {
336
+ jobId: { type: "string" },
337
+ note: { type: "string", minLength: 1, maxLength: 280 },
338
+ url: { type: "string", maxLength: 2048 },
339
+ },
340
+ },
341
+ },
342
+ {
343
+ name: "get_timeline",
344
+ description: "Read the most recent timeline entries for a job (claim/release/progress/decision/evidence). Helpful when the agent restarts a conversation and needs to know what happened. Requires jobs:read.",
345
+ annotations: READ_ONLY, inputSchema: {
346
+ type: "object",
347
+ required: ["jobId"],
348
+ properties: {
349
+ jobId: { type: "string" },
350
+ limit: { type: "integer", minimum: 1, maximum: 100, default: 50 },
351
+ cursor: { type: "string" },
352
+ },
353
+ },
354
+ },
355
+ {
356
+ name: "list_decisions",
357
+ description: "List open + recently resolved decision requests for a job. Use to poll for human response. Requires jobs:read.",
358
+ annotations: READ_ONLY, inputSchema: { type: "object", required: ["jobId"], properties: { jobId: { type: "string" } } },
359
+ },
360
+ {
361
+ name: "list_evidence",
362
+ description: "List evidence attached to a job. Requires jobs:read.",
363
+ annotations: READ_ONLY, inputSchema: { type: "object", required: ["jobId"], properties: { jobId: { type: "string" } } },
364
+ },
365
+ {
366
+ name: "resolve_decision",
367
+ description: "Resolve a DecisionRequest you previously opened with request_human_decision. Use this when the human gave you the answer in your chat (not in the QodFlow board) — propagating it here keeps the board in sync. You MUST include `humanResponseExcerpt` with the human's actual reply (first 280 chars). Audit log captures the chat excerpt so the trail is verifiable. Requires mcp:resolve_decision scope.",
368
+ annotations: WRITE_IDEMPOTENT,
369
+ inputSchema: {
370
+ type: "object",
371
+ required: ["decisionId", "chosenOption", "humanResponseExcerpt"],
372
+ properties: {
373
+ decisionId: { type: "string" },
374
+ chosenOption: { type: "string", minLength: 1, maxLength: 40 },
375
+ humanResponseExcerpt: { type: "string", minLength: 1, maxLength: 280 },
376
+ },
377
+ },
378
+ },
379
+ ];
380
+ server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
381
+ server.setRequestHandler(CallToolRequestSchema, async (req) => {
382
+ const { name, arguments: args } = req.params;
383
+ if (name === "list_jobs") {
384
+ const parsed = ListJobsArgs.parse(args ?? {});
385
+ const qs = new URLSearchParams();
386
+ if (parsed.limit)
387
+ qs.set("limit", String(parsed.limit));
388
+ if (parsed.cursor)
389
+ qs.set("cursor", parsed.cursor);
390
+ const json = await api(`/api/v1/jobs?${qs.toString()}`);
391
+ return {
392
+ content: [{ type: "text", text: JSON.stringify(json, null, 2) }],
393
+ };
394
+ }
395
+ if (name === "list_stages") {
396
+ GetStagesArgs.parse(args ?? {});
397
+ const json = await api(`/api/v1/stages`);
398
+ return {
399
+ content: [{ type: "text", text: JSON.stringify(json, null, 2) }],
400
+ };
401
+ }
402
+ if (name === "create_job") {
403
+ const parsed = CreateJobArgs.parse(args ?? {});
404
+ const json = await api(`/api/v1/jobs`, {
405
+ method: "POST",
406
+ body: JSON.stringify(parsed),
407
+ });
408
+ return { content: [{ type: "text", text: JSON.stringify(json, null, 2) }] };
409
+ }
410
+ if (name === "update_job") {
411
+ const parsed = UpdateJobArgs.parse(args ?? {});
412
+ const { id, ...rest } = parsed;
413
+ const json = await api(`/api/v1/jobs/${encodeURIComponent(id)}`, {
414
+ method: "PATCH",
415
+ body: JSON.stringify(rest),
416
+ });
417
+ return { content: [{ type: "text", text: JSON.stringify(json, null, 2) }] };
418
+ }
419
+ if (name === "move_job") {
420
+ const { jobId, ...rest } = MoveJobArgs.parse(args ?? {});
421
+ const json = await api(`/api/v1/jobs/${encodeURIComponent(jobId)}/move`, {
422
+ method: "POST",
423
+ body: JSON.stringify(rest),
424
+ });
425
+ return { content: [{ type: "text", text: JSON.stringify(json, null, 2) }] };
426
+ }
427
+ if (name === "assign_job") {
428
+ const { jobId, assignedToId } = AssignJobArgs.parse(args ?? {});
429
+ const json = await api(`/api/v1/jobs/${encodeURIComponent(jobId)}/assign`, {
430
+ method: "POST",
431
+ body: JSON.stringify({ assignedToId }),
432
+ });
433
+ return { content: [{ type: "text", text: JSON.stringify(json, null, 2) }] };
434
+ }
435
+ if (name === "list_tags") {
436
+ ListTagsArgs.parse(args ?? {});
437
+ const json = await api(`/api/v1/tags`);
438
+ return { content: [{ type: "text", text: JSON.stringify(json, null, 2) }] };
439
+ }
440
+ if (name === "list_members") {
441
+ ListMembersArgs.parse(args ?? {});
442
+ const json = await api(`/api/v1/members`);
443
+ return { content: [{ type: "text", text: JSON.stringify(json, null, 2) }] };
444
+ }
445
+ if (name === "create_tag") {
446
+ const parsed = CreateTagArgs.parse(args ?? {});
447
+ const json = await api(`/api/v1/tags`, {
448
+ method: "POST",
449
+ body: JSON.stringify(parsed),
450
+ });
451
+ return { content: [{ type: "text", text: JSON.stringify(json, null, 2) }] };
452
+ }
453
+ if (name === "update_stage") {
454
+ const parsed = UpdateStageArgs.parse(args ?? {});
455
+ const { id, ...rest } = parsed;
456
+ const json = await api(`/api/v1/stages/${encodeURIComponent(id)}`, {
457
+ method: "PATCH",
458
+ body: JSON.stringify(rest),
459
+ });
460
+ return { content: [{ type: "text", text: JSON.stringify(json, null, 2) }] };
461
+ }
462
+ if (name === "claim_job") {
463
+ const { jobId, ...rest } = ClaimJobArgs.parse(args ?? {});
464
+ const json = await api(`/api/v1/jobs/${encodeURIComponent(jobId)}/claim`, {
465
+ method: "POST",
466
+ body: JSON.stringify(rest),
467
+ });
468
+ return { content: [{ type: "text", text: JSON.stringify(json, null, 2) }] };
469
+ }
470
+ if (name === "release_job") {
471
+ const { jobId, ...rest } = ReleaseJobArgs.parse(args ?? {});
472
+ const json = await api(`/api/v1/jobs/${encodeURIComponent(jobId)}/release`, {
473
+ method: "POST",
474
+ body: JSON.stringify(rest),
475
+ });
476
+ return { content: [{ type: "text", text: JSON.stringify(json, null, 2) }] };
477
+ }
478
+ if (name === "report_progress") {
479
+ const { jobId, ...rest } = ReportProgressArgs.parse(args ?? {});
480
+ const json = await api(`/api/v1/jobs/${encodeURIComponent(jobId)}/progress`, {
481
+ method: "POST",
482
+ body: JSON.stringify(rest),
483
+ });
484
+ return { content: [{ type: "text", text: JSON.stringify(json, null, 2) }] };
485
+ }
486
+ if (name === "request_human_decision") {
487
+ const { jobId, ...rest } = RequestHumanDecisionArgs.parse(args ?? {});
488
+ const json = await api(`/api/v1/jobs/${encodeURIComponent(jobId)}/decision`, {
489
+ method: "POST",
490
+ body: JSON.stringify(rest),
491
+ });
492
+ return { content: [{ type: "text", text: JSON.stringify(json, null, 2) }] };
493
+ }
494
+ if (name === "attach_evidence") {
495
+ const { jobId, ...rest } = AttachEvidenceArgs.parse(args ?? {});
496
+ const json = await api(`/api/v1/jobs/${encodeURIComponent(jobId)}/evidence`, {
497
+ method: "POST",
498
+ body: JSON.stringify(rest),
499
+ });
500
+ return { content: [{ type: "text", text: JSON.stringify(json, null, 2) }] };
501
+ }
502
+ // Read-tools that surface text authored by another actor (humans, other
503
+ // agents, untrusted external sources) MUST tag their response with
504
+ // `_meta.untrusted: true` per MCP spec 2025-06-18 §Security so the host
505
+ // (Claude Desktop / Cursor) can apply Passive Cognitive Restriction:
506
+ // disable destructive/openWorld tools for this turn. The string-level
507
+ // [UNTRUSTED-BEGIN]…[END] wrap already applied by the server is layer 2;
508
+ // this is the spec-level signal.
509
+ if (name === "get_timeline") {
510
+ const { jobId, limit, cursor } = GetTimelineArgs.parse(args ?? {});
511
+ const qs = new URLSearchParams();
512
+ if (limit)
513
+ qs.set("limit", String(limit));
514
+ if (cursor)
515
+ qs.set("cursor", cursor);
516
+ const json = await api(`/api/v1/jobs/${encodeURIComponent(jobId)}/timeline?${qs.toString()}`);
517
+ return {
518
+ content: [{ type: "text", text: JSON.stringify(json, null, 2) }],
519
+ _meta: { untrusted: true, source: "agent-authored-timeline" },
520
+ };
521
+ }
522
+ if (name === "list_decisions") {
523
+ const { jobId } = ListDecisionsArgs.parse(args ?? {});
524
+ const json = await api(`/api/v1/jobs/${encodeURIComponent(jobId)}/decision`);
525
+ return {
526
+ content: [{ type: "text", text: JSON.stringify(json, null, 2) }],
527
+ _meta: { untrusted: true, source: "agent-authored-question" },
528
+ };
529
+ }
530
+ if (name === "list_evidence") {
531
+ const { jobId } = ListEvidenceArgs.parse(args ?? {});
532
+ const json = await api(`/api/v1/jobs/${encodeURIComponent(jobId)}/evidence`);
533
+ return {
534
+ content: [{ type: "text", text: JSON.stringify(json, null, 2) }],
535
+ _meta: { untrusted: true, source: "agent-authored-evidence-note" },
536
+ };
537
+ }
538
+ if (name === "resolve_decision") {
539
+ const { decisionId, ...rest } = ResolveDecisionArgs.parse(args ?? {});
540
+ const json = await api(`/api/v1/decisions/${encodeURIComponent(decisionId)}/resolve`, {
541
+ method: "POST",
542
+ body: JSON.stringify(rest),
543
+ });
544
+ return { content: [{ type: "text", text: JSON.stringify(json, null, 2) }] };
545
+ }
546
+ throw new Error(`Unknown tool: ${name}`);
547
+ });
548
+ const transport = new StdioServerTransport();
549
+ await server.connect(transport);
package/package.json ADDED
@@ -0,0 +1,33 @@
1
+ {
2
+ "name": "qodflow-mcp",
3
+ "version": "0.1.0",
4
+ "description": "Model Context Protocol server for QodFlow. Lets AI agents (Claude Desktop, Cursor, ChatGPT Desktop) drive a QodFlow workspace through Personal Access Tokens.",
5
+ "type": "module",
6
+ "bin": {
7
+ "qodflow-mcp": "./dist/index.js"
8
+ },
9
+ "files": [
10
+ "dist",
11
+ "README.md"
12
+ ],
13
+ "scripts": {
14
+ "build": "tsc -p tsconfig.json",
15
+ "dev": "tsx watch src/index.ts",
16
+ "start": "node dist/index.js",
17
+ "prepublishOnly": "npm run build"
18
+ },
19
+ "engines": {
20
+ "node": ">=20"
21
+ },
22
+ "//security": "E48 supply-chain hardening: deps pinned to exact versions (no caret). No postinstall script. CI must run `npm ci --ignore-scripts`. Update by editing manually + reviewing the diff in PR — never `npm update` or `dependabot auto-merge`.",
23
+ "dependencies": {
24
+ "@modelcontextprotocol/sdk": "1.0.4",
25
+ "zod": "3.23.8"
26
+ },
27
+ "devDependencies": {
28
+ "tsx": "4.19.2",
29
+ "typescript": "5.7.2",
30
+ "@types/node": "20.17.10"
31
+ },
32
+ "license": "MIT"
33
+ }