@getagenthook/mcp 1.0.0

package/dist/client.js

@@ -0,0 +1,115 @@
+// Bearer HTTP client — ported 1:1 from packages/cli/src/http.ts + run.ts.
+// Standalone: the published package cannot runtime-import @getagenthook/core,
+// so the minimal wire types are mirrored here (packages/core/contract.ts).
+import { randomUUID } from "node:crypto";
+const BASE_PATH = "/api/v1";
+const DEFAULT_API_URL = "https://getagenthook.com";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+// One transient re-submit with the SAME idempotency key (never double-charge —
+// the server dedupes on the key). Mirrors cli/src/commands/run.ts.
+const SUBMIT_RETRIES = 1;
+export class ApiError extends Error {
+    status;
+    code;
+    details;
+    retryAfter;
+    constructor(message, status, // 0 = network/timeout, no HTTP response
+    code, details, retryAfter) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.retryAfter = retryAfter;
+        this.name = "ApiError";
+    }
+}
+/** Resolution order mirrors the CLI: AGENTHOOK_API_URL env, then default.
+ * Enforces https:// so a hostile/misconfigured env can't redirect the Bearer
+ * key to a cleartext or attacker-controlled host (and poison the fetched tool
+ * descriptions). http:// is allowed ONLY for localhost, for local dev. */
+export function resolveApiUrl() {
+    const raw = (process.env.AGENTHOOK_API_URL || DEFAULT_API_URL).replace(/\/+$/, "");
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new Error(`AGENTHOOK_API_URL is not a valid URL: ${raw}`);
+    }
+    const isLocalhost = u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "::1";
+    if (u.protocol !== "https:" && !(u.protocol === "http:" && isLocalhost)) {
+        throw new Error(`AGENTHOOK_API_URL must use https:// (got ${u.protocol}//${u.hostname}). http:// is allowed only for localhost.`);
+    }
+    return raw;
+}
+/** AGENTHOOK_API_KEY env only (no on-disk credentials in the MCP server). */
+export function resolveApiKey() {
+    return process.env.AGENTHOOK_API_KEY || undefined;
+}
+/** Bounded JSON request against <apiUrl>/api/v1<pathname>. Checks res.ok before
+ * res.json() (donor rule) and normalizes every failure to ApiError. */
+async function api(apiUrl, pathname, opts = {}) {
+    const url = new URL(apiUrl + BASE_PATH + pathname);
+    const headers = { ...opts.headers };
+    if (opts.key)
+        headers.authorization = `Bearer ${opts.key}`;
+    if (opts.body !== undefined)
+        headers["content-type"] = "application/json";
+    let res;
+    try {
+        res = await fetch(url, {
+            method: opts.method ?? "GET",
+            headers,
+            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+            signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+        });
+    }
+    catch (e) {
+        throw new ApiError(`request to ${url.host} failed: ${e.message}`, 0);
+    }
+    if (!res.ok) {
+        let body;
+        try {
+            body = (await res.json());
+        }
+        catch {
+            // non-JSON error body — fall through to the status line
+        }
+        throw new ApiError(body?.error ?? `HTTP ${res.status} ${res.statusText}`, res.status, body?.code, body?.details, body?.retry_after);
+    }
+    return (await res.json());
+}
+/** GET /api/v1/tools — the single live schema source. */
+export async function fetchTools() {
+    const res = await api(resolveApiUrl(), "/tools", { key: resolveApiKey() });
+    return res.tools;
+}
+/** POST /api/v1/tools/:tool/run — submit, retrying only transient network
+ * failures (status 0) with the SAME idempotency key so a hiccup mid-submit
+ * never double-charges. */
+export async function submitRun(tool, input) {
+    const apiUrl = resolveApiUrl();
+    const key = resolveApiKey();
+    const idempotencyKey = randomUUID();
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await api(apiUrl, `/tools/${encodeURIComponent(tool)}/run`, {
+                method: "POST",
+                key,
+                body: input,
+                headers: { [IDEMPOTENCY_KEY_HEADER]: idempotencyKey },
+            });
+        }
+        catch (e) {
+            if (e instanceof ApiError && e.status === 0 && attempt < SUBMIT_RETRIES)
+                continue;
+            throw e;
+        }
+    }
+}
+/** GET /api/v1/runs/:id — a SINGLE status read (the MCP client polls per call,
+ * there is no loop here — cf. cli/src/commands/run.ts which loops). */
+export async function getRun(id) {
+    return api(resolveApiUrl(), `/runs/${encodeURIComponent(id)}`, { key: resolveApiKey() });
+}

package/dist/main.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Bin entry for `npx -y @getagenthook/mcp`. All diagnostics go to stderr —
+// stdout carries ONLY JSON-RPC frames on stdio.
+import { startServer } from "./server.js";
+startServer().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/schema.js

@@ -0,0 +1,36 @@
+export function toJsonSchema(params) {
+    const properties = {};
+    const required = [];
+    for (const [name, spec] of Object.entries(params)) {
+        const prop = { type: spec.type };
+        if (spec.description !== undefined)
+            prop.description = spec.description;
+        if (spec.enum !== undefined)
+            prop.enum = [...spec.enum];
+        if (spec.type === "array" && spec.items)
+            prop.items = { type: spec.items.type };
+        if (spec.default !== undefined)
+            prop.default = spec.default;
+        if (spec.type === "number") {
+            if (spec.min !== undefined)
+                prop.minimum = spec.min;
+            if (spec.max !== undefined)
+                prop.maximum = spec.max;
+        }
+        else if (spec.type === "array") {
+            if (spec.min !== undefined)
+                prop.minItems = spec.min;
+            if (spec.max !== undefined)
+                prop.maxItems = spec.max;
+        }
+        if (spec.maxLength !== undefined)
+            prop.maxLength = spec.maxLength;
+        properties[name] = prop;
+        if (spec.required)
+            required.push(name);
+    }
+    const schema = { type: "object", properties, additionalProperties: false };
+    if (required.length)
+        schema.required = required;
+    return schema;
+}

package/dist/server.js

@@ -0,0 +1,112 @@
+// Stdio MCP server: a thin 1:1 proxy over the AgentHook REST API.
+//
+// DEVIATION FROM SPEC §5 (flagged): the spec names the high-level
+// `McpServer.registerTool`, but in @modelcontextprotocol/sdk v1.29.0 that API
+// accepts ONLY a Zod schema for `inputSchema` and converts it to JSON Schema
+// internally — it cannot consume a pre-built JSON Schema (a raw JSON object is
+// coerced to an empty schema; verified against the SDK source). The spec's
+// load-bearing requirement (deliverables #3/#4: tool inputSchemas built LIVE
+// from GET /tools via toJsonSchema, so they never drift) is only satisfiable by
+// serving that JSON Schema verbatim — which the low-level `Server` does. So we
+// use `Server` + ListTools/CallTool handlers. Same SDK, same transport; the
+// only difference is toJsonSchema's output IS the wire inputSchema, unmodified.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { ApiError, fetchTools, getRun, resolveApiKey, submitRun } from "./client.js";
+import { toJsonSchema } from "./schema.js";
+const GET_RUN_TOOL = "get_run";
+const VERSION = "1.0.0";
+// structuredContent contracts (advertised as each tool's outputSchema).
+const RUN_CREATED_OUTPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        run_id: { type: "string", description: "Poll this id with get_run for status + output URLs." },
+        credits_charged: { type: "number" },
+    },
+    required: ["run_id", "credits_charged"],
+    additionalProperties: false,
+};
+const GET_RUN_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        run_id: { type: "string", description: "The run id returned by a generation tool." },
+    },
+    required: ["run_id"],
+    additionalProperties: false,
+};
+const GET_RUN_OUTPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        status: { type: "string", description: "queued | processing | completed | failed" },
+        output: { type: "array", items: { type: "string" }, description: "Output URLs when completed." },
+        error: { type: ["string", "null"] },
+    },
+    required: ["status", "output"],
+    additionalProperties: false,
+};
+/** Build the (fully wired) MCP server. Reads AGENTHOOK_API_KEY and fails loud
+ * BEFORE any network call if it is missing; then fetches the live tool schema
+ * and registers the 4 generation tools + get_run. Throws on failure — the
+ * caller (main.ts) writes the message to stderr and exits non-zero. */
+export async function buildServer() {
+    if (!resolveApiKey()) {
+        throw new Error("AGENTHOOK_API_KEY is not set. Add your key (ah_...) to the MCP server's env. " +
+            "Get one at https://getagenthook.com.");
+    }
+    const tools = await fetchTools();
+    const generationTools = new Set(tools.map((t) => t.name));
+    const toolList = [
+        ...tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: toJsonSchema(t.params),
+            outputSchema: RUN_CREATED_OUTPUT_SCHEMA,
+        })),
+        {
+            name: GET_RUN_TOOL,
+            description: "Fetch the status and output URLs of a run created by a generation tool. Poll this until status is 'completed' or 'failed'.",
+            inputSchema: GET_RUN_INPUT_SCHEMA,
+            outputSchema: GET_RUN_OUTPUT_SCHEMA,
+        },
+    ];
+    const server = new Server({ name: "agenthook", version: VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: toolList }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name } = request.params;
+        const args = (request.params.arguments ?? {});
+        try {
+            if (name === GET_RUN_TOOL) {
+                const run = await getRun(String(args.run_id ?? ""));
+                const structured = { status: run.status, output: run.output, error: run.error };
+                return { structuredContent: structured, content: [{ type: "text", text: JSON.stringify(structured) }] };
+            }
+            if (generationTools.has(name)) {
+                const created = await submitRun(name, args);
+                const structured = { run_id: created.run_id, credits_charged: created.credits_charged };
+                return {
+                    structuredContent: structured,
+                    content: [
+                        {
+                            type: "text",
+                            text: `Run ${created.run_id} submitted (${created.credits_charged} credits charged). Call get_run with this run_id to fetch the result.`,
+                        },
+                    ],
+                };
+            }
+            throw new Error(`Unknown tool: ${name}`);
+        }
+        catch (e) {
+            // Surface API/errors to the agent as a tool error (not a protocol crash).
+            const msg = e instanceof ApiError ? e.message : e instanceof Error ? e.message : String(e);
+            return { isError: true, content: [{ type: "text", text: msg }] };
+        }
+    });
+    return server;
+}
+/** Boot: build the server and connect it to stdio. */
+export async function startServer() {
+    const server = await buildServer();
+    await server.connect(new StdioServerTransport());
+    console.error("agenthook MCP server ready on stdio.");
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@getagenthook/mcp",
+  "version": "1.0.0",
+  "description": "Local stdio MCP server for the AgentHook hosted media-generation API — make character-consistent UGC video, images, and captions from any MCP client.",
+  "license": "Apache-2.0",
+  "homepage": "https://getagenthook.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AvivK5498/agenthook.git"
+  },
+  "mcpName": "io.github.AvivK5498/agenthook",
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "ai",
+    "video-generation",
+    "image-generation",
+    "agents"
+  ],
+  "type": "module",
+  "bin": {
+    "agenthook-mcp": "./dist/main.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  }
+}