@agent-tasks/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,108 @@
+# @agent-tasks/mcp-server
+
+MCP server that exposes the [agent-tasks](https://agent-tasks.opentriologue.ai) API
+as tools so MCP-capable clients (Claude Code, Cursor, Cline, triologue, …) can
+drive the full task lifecycle without writing REST boilerplate.
+
+It is a thin wrapper: all governance rules (confidence gates, preconditions,
+review locks, audit trail) are enforced by the agent-tasks backend. The MCP
+server just translates tool calls into authenticated HTTP requests.
+
+## Installation
+
+```bash
+# once published
+npx @agent-tasks/mcp-server
+
+# or build from this workspace
+npm run build --workspace=mcp-server
+node mcp-server/dist/index.js
+```
+
+## Configuration
+
+Two environment variables:
+
+| Variable               | Required | Default                                  |
+| ---------------------- | -------- | ---------------------------------------- |
+| `AGENT_TASKS_TOKEN`    | yes      | —                                        |
+| `AGENT_TASKS_BASE_URL` | no       | `https://agent-tasks.opentriologue.ai`   |
+
+Obtain a token from the agent-tasks UI under **Settings → Agent Tokens**.
+The token scope determines which tools succeed at runtime; tools that require
+missing scopes return an API error describing the missing scope.
+
+## Claude Code setup
+
+Register globally for your user so the server is available in every project:
+
+```bash
+claude mcp add agent-tasks \
+  --scope user \
+  --env AGENT_TASKS_TOKEN=atk_xxx \
+  -- npx -y @agent-tasks/mcp-server
+```
+
+Drop `--scope user` if you want it project-local instead. See
+`claude mcp add --help` for the full list of scopes and options.
+
+## Tools
+
+| Tool                 | Wraps                                        |
+| -------------------- | -------------------------------------------- |
+| `projects_list`      | `GET /api/projects/available`                |
+| `tasks_list`         | `GET /api/tasks/claimable`                   |
+| `tasks_get`          | `GET /api/tasks/:id`                         |
+| `tasks_instructions` | `GET /api/tasks/:id/instructions`            |
+| `tasks_create`       | `POST /api/projects/:projectId/tasks`        |
+| `tasks_claim`        | `POST /api/tasks/:id/claim`                  |
+| `tasks_release`      | `POST /api/tasks/:id/release`                |
+| `tasks_transition`   | `POST /api/tasks/:id/transition`             |
+| `tasks_update`       | `PATCH /api/tasks/:id`                       |
+| `tasks_comment`      | `POST /api/tasks/:id/comments`               |
+| `signals_poll`       | `GET /api/agent/signals`                     |
+| `signals_ack`        | `POST /api/agent/signals/:id/ack`            |
+
+All tools return the raw JSON response from the backend as a text block.
+
+## Transport
+
+This package ships **stdio** only. It is the recommended path for
+local Claude Code / Cursor / Cline integrations — one `npx` command,
+no running server to maintain, no network hop.
+
+### Remote clients: use the backend's `/api/mcp` endpoint instead
+
+Remote MCP clients that speak HTTP + JSON-RPC (e.g. Triologue's
+`mcpBridge.ts`) cannot drive a stdio child process across a network
+boundary. For those, the agent-tasks backend exposes the **same 12
+tools** over HTTP at `POST /api/mcp`:
+
+```bash
+# Example: discover tools on a remote gateway
+curl -X POST https://agent-tasks.opentriologue.ai/api/mcp \
+  -H "Authorization: Bearer <agent_token>" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+
+- Stateless Streamable HTTP (no session ID, one round-trip per
+  request)
+- Same Bearer auth as the rest of the agent-tasks REST API
+- Same tools, same schemas, same governance — the HTTP handler
+  dispatches every tool call back through the same Hono app stack
+  the REST routes live on, so the code paths stay in sync with zero
+  duplication
+- GET / DELETE on `/api/mcp` return 405 with `Allow: POST`
+
+Pick stdio (this package) for local agents; pick `/api/mcp` for
+remote / server-side consumers.
+
+## Development
+
+```bash
+npm install
+npm run dev --workspace=mcp-server        # tsx watch
+npm run build --workspace=mcp-server      # tsc -> dist/
+npm run typecheck --workspace=mcp-server
+```

package/dist/client.d.ts

@@ -0,0 +1,45 @@
+export interface ClientConfig {
+    baseUrl: string;
+    token: string;
+}
+export declare class AgentTasksApiError extends Error {
+    status: number;
+    body: unknown;
+    constructor(status: number, body: unknown, message: string);
+}
+export declare class AgentTasksClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    private request;
+    listProjects(): Promise<unknown>;
+    listClaimableTasks(params?: {
+        limit?: number;
+    }): Promise<unknown>;
+    getTask(taskId: string): Promise<unknown>;
+    getTaskInstructions(taskId: string): Promise<unknown>;
+    createTask(projectId: string, input: {
+        title: string;
+        description?: string;
+        priority?: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+        workflowId?: string;
+        dueAt?: string;
+        externalRef?: string;
+        labels?: string[];
+    }): Promise<unknown>;
+    claimTask(taskId: string): Promise<unknown>;
+    releaseTask(taskId: string): Promise<unknown>;
+    transitionTask(taskId: string, input: {
+        status: string;
+        force?: boolean;
+        forceReason?: string;
+    }): Promise<unknown>;
+    updateTask(taskId: string, input: {
+        branchName?: string | null;
+        prUrl?: string | null;
+        prNumber?: number | null;
+        result?: string | null;
+    }): Promise<unknown>;
+    addTaskComment(taskId: string, content: string): Promise<unknown>;
+    pollSignals(): Promise<unknown>;
+    ackSignal(signalId: string): Promise<unknown>;
+}

package/dist/client.js

@@ -0,0 +1,88 @@
+export class AgentTasksApiError extends Error {
+    status;
+    body;
+    constructor(status, body, message) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "AgentTasksApiError";
+    }
+}
+export class AgentTasksClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async request(method, path, body) {
+        const url = `${this.config.baseUrl.replace(/\/$/, "")}${path}`;
+        const headers = {
+            Authorization: `Bearer ${this.config.token}`,
+            Accept: "application/json",
+        };
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await res.text();
+        let parsed = undefined;
+        if (text.length > 0) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = text;
+            }
+        }
+        if (!res.ok) {
+            const msg = (parsed && typeof parsed === "object" && "message" in parsed
+                ? String(parsed.message)
+                : undefined) ?? `${method} ${path} failed: ${res.status}`;
+            throw new AgentTasksApiError(res.status, parsed, msg);
+        }
+        return parsed;
+    }
+    listProjects() {
+        return this.request("GET", "/api/projects/available");
+    }
+    listClaimableTasks(params) {
+        const qs = params?.limit !== undefined ? `?limit=${params.limit}` : "";
+        return this.request("GET", `/api/tasks/claimable${qs}`);
+    }
+    getTask(taskId) {
+        return this.request("GET", `/api/tasks/${taskId}`);
+    }
+    getTaskInstructions(taskId) {
+        return this.request("GET", `/api/tasks/${taskId}/instructions`);
+    }
+    createTask(projectId, input) {
+        return this.request("POST", `/api/projects/${projectId}/tasks`, input);
+    }
+    claimTask(taskId) {
+        return this.request("POST", `/api/tasks/${taskId}/claim`);
+    }
+    releaseTask(taskId) {
+        return this.request("POST", `/api/tasks/${taskId}/release`);
+    }
+    transitionTask(taskId, input) {
+        return this.request("POST", `/api/tasks/${taskId}/transition`, input);
+    }
+    updateTask(taskId, input) {
+        return this.request("PATCH", `/api/tasks/${taskId}`, input);
+    }
+    addTaskComment(taskId, content) {
+        return this.request("POST", `/api/tasks/${taskId}/comments`, {
+            content,
+        });
+    }
+    pollSignals() {
+        return this.request("GET", "/api/agent/signals");
+    }
+    ackSignal(signalId) {
+        return this.request("POST", `/api/agent/signals/${signalId}/ack`);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { runStdioServer, DEFAULT_BASE_URL } from "./server.js";
+function resolveConfig() {
+    const token = process.env.AGENT_TASKS_TOKEN;
+    if (!token) {
+        throw new Error("AGENT_TASKS_TOKEN env var is required. Obtain a token from the agent-tasks UI under Settings → Agent Tokens.");
+    }
+    const baseUrl = process.env.AGENT_TASKS_BASE_URL ?? DEFAULT_BASE_URL;
+    return { token, baseUrl };
+}
+runStdioServer(resolveConfig()).catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error("[agent-tasks-mcp] fatal:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/D,SAAS,aAAa;IACpB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;IAC5C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,8GAA8G,CAC/G,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,gBAAgB,CAAC;IACrE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC5B,CAAC;AAED,cAAc,CAAC,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IAC5C,sCAAsC;IACtC,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,GAAG,CAAC,CAAC;IAC/C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ClientConfig } from "./client.js";
+export declare const DEFAULT_BASE_URL = "https://agent-tasks.opentriologue.ai";
+export declare const SERVER_NAME = "agent-tasks-mcp";
+export declare const SERVER_VERSION = "0.1.0";
+export declare function createServer(config: ClientConfig): McpServer;
+export declare function runStdioServer(config: ClientConfig): Promise<void>;
+export { AgentTasksClient, type ClientConfig } from "./client.js";
+export { buildTools } from "./tools.js";

package/dist/server.js

@@ -0,0 +1,51 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { AgentTasksClient } from "./client.js";
+import { buildTools } from "./tools.js";
+export const DEFAULT_BASE_URL = "https://agent-tasks.opentriologue.ai";
+export const SERVER_NAME = "agent-tasks-mcp";
+export const SERVER_VERSION = "0.1.0";
+export function createServer(config) {
+    const client = new AgentTasksClient(config);
+    const tools = buildTools(client);
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    });
+    for (const tool of tools) {
+        server.registerTool(tool.name, {
+            description: tool.description,
+            inputSchema: tool.inputShape,
+        }, async (args) => {
+            try {
+                const result = await tool.handler(args);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: typeof result === "string"
+                                ? result
+                                : JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: message }],
+                };
+            }
+        });
+    }
+    return server;
+}
+export async function runStdioServer(config) {
+    const server = createServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+export { AgentTasksClient } from "./client.js";
+export { buildTools } from "./tools.js";
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAqB,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,CAAC,MAAM,gBAAgB,GAAG,sCAAsC,CAAC;AACvE,MAAM,CAAC,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAC7C,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAEtC,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,MAAM,MAAM,GAAG,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IAEjC,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;KACxB,CAAC,CAAC;IAEH,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,YAAY,CACjB,IAAI,CAAC,IAAI,EACT;YACE,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,UAAU;SAC7B,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;YACb,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAa,CAAC,CAAC;gBACjD,OAAO;oBACL,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAM;4BACZ,IAAI,EACF,OAAO,MAAM,KAAK,QAAQ;gCACxB,CAAC,CAAC,MAAM;gCACR,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;yBACtC;qBACF;iBACF,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACjE,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;iBAC3C,CAAC;YACJ,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAoB;IACvD,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,OAAO,EAAE,gBAAgB,EAAqB,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,9 @@
+import { z, ZodRawShape } from "zod";
+import { AgentTasksClient } from "./client.js";
+export interface ToolDefinition<Shape extends ZodRawShape = ZodRawShape> {
+    name: string;
+    description: string;
+    inputShape: Shape;
+    handler: (args: z.objectOutputType<Shape, z.ZodTypeAny>) => Promise<unknown>;
+}
+export declare function buildTools(client: AgentTasksClient): ToolDefinition[];

package/dist/tools.js

@@ -0,0 +1,132 @@
+import { z } from "zod";
+import { AgentTasksApiError } from "./client.js";
+const transitionStatusEnum = z.enum([
+    "open",
+    "in_progress",
+    "review",
+    "done",
+]);
+const priorityEnum = z.enum(["LOW", "MEDIUM", "HIGH", "CRITICAL"]);
+const uuid = () => z.string().uuid();
+async function wrap(fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (err instanceof AgentTasksApiError) {
+            const detail = err.body
+                ? ` — ${typeof err.body === "string" ? err.body : JSON.stringify(err.body)}`
+                : "";
+            throw new Error(`agent-tasks API ${err.status}: ${err.message}${detail}`);
+        }
+        throw err;
+    }
+}
+function def(d) {
+    return d;
+}
+export function buildTools(client) {
+    return [
+        def({
+            name: "projects_list",
+            description: "List all projects visible to the authenticated actor. Returns id, slug, name, and GitHub repo for each.",
+            inputShape: {},
+            handler: async () => wrap(() => client.listProjects()),
+        }),
+        def({
+            name: "tasks_list",
+            description: "List tasks that the authenticated actor may claim (status=open, not blocked, not already claimed). Supports an optional limit.",
+            inputShape: {
+                limit: z.number().int().positive().max(500).optional(),
+            },
+            handler: async ({ limit }) => wrap(() => client.listClaimableTasks({ limit })),
+        }),
+        def({
+            name: "tasks_get",
+            description: "Fetch a single task by id, including comments and dependencies.",
+            inputShape: { taskId: uuid() },
+            handler: async ({ taskId }) => wrap(() => client.getTask(taskId)),
+        }),
+        def({
+            name: "tasks_instructions",
+            description: "Fetch agent-facing instructions for a task: current state, allowed transitions, confidence score, required-field checklist, and updatable fields.",
+            inputShape: { taskId: uuid() },
+            handler: async ({ taskId }) => wrap(() => client.getTaskInstructions(taskId)),
+        }),
+        def({
+            name: "tasks_create",
+            description: "Create a new task in a project. Only title is required. Use externalRef as an idempotency key for bulk imports — the backend dedupes on (projectId, externalRef).",
+            inputShape: {
+                projectId: uuid(),
+                title: z.string().min(1).max(255),
+                description: z.string().optional(),
+                priority: priorityEnum.optional(),
+                workflowId: uuid().optional(),
+                dueAt: z.string().datetime().optional(),
+                externalRef: z.string().trim().min(1).max(255).optional(),
+                labels: z
+                    .array(z.string().trim().min(1).max(100))
+                    .max(20)
+                    .optional(),
+            },
+            handler: async ({ projectId, ...input }) => wrap(() => client.createTask(projectId, input)),
+        }),
+        def({
+            name: "tasks_claim",
+            description: "Claim a task as the authenticated actor. Fails if the task is already claimed, blocked, or not in a claimable state.",
+            inputShape: { taskId: uuid() },
+            handler: async ({ taskId }) => wrap(() => client.claimTask(taskId)),
+        }),
+        def({
+            name: "tasks_release",
+            description: "Release a previously claimed task, returning it to the claimable pool.",
+            inputShape: { taskId: uuid() },
+            handler: async ({ taskId }) => wrap(() => client.releaseTask(taskId)),
+        }),
+        def({
+            name: "tasks_transition",
+            description: "Transition a task to a new status. Preconditions from the task's workflow (branchPresent, prMerged, ciGreen, …) are enforced server-side. Use force=true with a forceReason only when you have explicit authorization to bypass gates.",
+            inputShape: {
+                taskId: uuid(),
+                status: transitionStatusEnum,
+                force: z.boolean().optional(),
+                forceReason: z.string().max(500).optional(),
+            },
+            handler: async ({ taskId, ...input }) => wrap(() => client.transitionTask(taskId, input)),
+        }),
+        def({
+            name: "tasks_update",
+            description: "Update mutable fields on a task: branchName, prUrl, prNumber, result. Pass null to clear a field.",
+            inputShape: {
+                taskId: uuid(),
+                branchName: z.string().max(255).nullable().optional(),
+                prUrl: z.string().url().nullable().optional(),
+                prNumber: z.number().int().positive().nullable().optional(),
+                result: z.string().nullable().optional(),
+            },
+            handler: async ({ taskId, ...input }) => wrap(() => client.updateTask(taskId, input)),
+        }),
+        def({
+            name: "tasks_comment",
+            description: "Add a comment to a task. Useful for logging progress, asking human reviewers for clarification, or recording decisions.",
+            inputShape: {
+                taskId: uuid(),
+                content: z.string().min(1).max(5000),
+            },
+            handler: async ({ taskId, content }) => wrap(() => client.addTaskComment(taskId, content)),
+        }),
+        def({
+            name: "signals_poll",
+            description: "Poll the signal inbox for the authenticated agent. Signals represent state changes the agent should react to (task claimed, review requested, force-transition, …).",
+            inputShape: {},
+            handler: async () => wrap(() => client.pollSignals()),
+        }),
+        def({
+            name: "signals_ack",
+            description: "Acknowledge a signal by id. Acknowledged signals are removed from the inbox.",
+            inputShape: { signalId: uuid() },
+            handler: async ({ signalId }) => wrap(() => client.ackSignal(signalId)),
+        }),
+    ];
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@agent-tasks/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server exposing the agent-tasks API as tools for MCP-capable clients",
+  "homepage": "https://github.com/LanNguyenSi/agent-tasks/tree/master/mcp-server#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LanNguyenSi/agent-tasks.git",
+    "directory": "mcp-server"
+  },
+  "bugs": {
+    "url": "https://github.com/LanNguyenSi/agent-tasks/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "agent-tasks-mcp": "./dist/index.js"
+  },
+  "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}