panini-connector-mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,704 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/tools/install.ts
+import { z } from "zod";
+function buildInstall(input) {
+  const {
+    language,
+    framework,
+    storage,
+    existing_table = "blog_posts",
+    url_template = "https://yoursite.com/blog/{slug}"
+  } = input;
+  const envVars = envVarsFor(storage);
+  const verifyCommand = language === "python" ? `panini-connector test --url https://your-site.com/api/seo-connector --secret $SEO_CONNECTOR_SECRET` : `npx panini-connector test --url https://your-site.com/api/seo-connector --secret $SEO_CONNECTOR_SECRET`;
+  if (language === "node") {
+    return buildNode(framework, storage, existing_table, url_template, envVars, verifyCommand);
+  }
+  return buildPython(framework, storage, existing_table, url_template, envVars, verifyCommand);
+}
+function buildNode(framework, storage, table, urlTemplate, envVars, verifyCommand) {
+  const isCustomDb = storage === "custom_db";
+  const peerDeps = [
+    storage === "postgres" ? "pg" : null,
+    isCustomDb ? "mysql2   # or mongodb / mssql / your DB driver" : null,
+    framework === "express" ? "express" : null
+  ].filter(Boolean);
+  const install = `npm install panini-connector` + (peerDeps.length ? `
+npm install ${peerDeps.join(" ")}` : "");
+  const storageImport = storage === "supabase" ? "import { SupabaseStorage } from 'panini-connector/storage/supabase'" : storage === "postgres" ? "import { PostgresStorage } from 'panini-connector/storage/postgres'" : isCustomDb ? `import type { StorageAdapter, Post } from 'panini-connector'
+import mysql from 'mysql2/promise'   // \u2190 swap for your DB driver` : "import { MemoryStorage } from 'panini-connector'";
+  const storageInstance = isCustomDb ? "new MyStorage()" : storage === "supabase" || storage === "postgres" ? renderExistingTableInstance(storage, table, urlTemplate) : "new MemoryStorage()";
+  const customDbClass = isCustomDb ? renderCustomDbClass(table, urlTemplate) : "";
+  const nextAppCode = `import { createHandler } from 'panini-connector/next-app'
+${storageImport}
+${customDbClass}
+const handler = createHandler({
+  storage: ${storageInstance},
+})
+export const POST = handler`;
+  const nextPagesCode = `import { createHandler } from 'panini-connector/next-pages'
+${storageImport}
+${customDbClass}
+export const config = { api: { bodyParser: false } }
+
+export default createHandler({
+  storage: ${storageInstance},
+})`;
+  const expressCode = `import express from 'express'
+import { mount } from 'panini-connector/express'
+${storageImport}
+${customDbClass}
+const app = express()
+
+mount(app, {
+  path: '/api/seo-connector',
+  storage: ${storageInstance},
+})
+
+app.use(express.json())  // Safe here \u2014 comes AFTER mount()
+app.listen(3000)`;
+  const filePath = framework === "next_app" ? "app/api/seo-connector/route.ts" : framework === "next_pages" ? "pages/api/seo-connector.ts" : "server.ts";
+  const code = framework === "next_app" ? nextAppCode : framework === "next_pages" ? nextPagesCode : expressCode;
+  const postNote = buildPostNote(framework, storage);
+  return {
+    install_command: install,
+    files: [{ path: filePath, content: code, language: "typescript" }],
+    env_vars: envVars,
+    post_install_note: postNote,
+    verify_command: verifyCommand
+  };
+}
+function renderExistingTableInstance(storage, table, urlTemplate) {
+  const cls = storage === "supabase" ? "SupabaseStorage" : "PostgresStorage";
+  return `new ${cls}({
+    table: '${table}',
+    externalIdColumn: 'id',
+    externalUrlTemplate: '${urlTemplate}',
+    toRow: (post) => ({
+      title: post.title,
+      slug: post.slug,
+      content: post.body_html,
+      description: post.excerpt || post.seo_meta?.description || '',
+      meta_title: post.seo_meta?.title || post.title,
+      meta_description: post.seo_meta?.description || post.excerpt,
+      featured_image_url: post.featured_image_url,
+      author_name: post.author_name,
+      status: post.status || 'published',
+      category: 'seo',
+      external_source: 'panini',
+      published_at: new Date().toISOString(),
+    }),
+  })`;
+}
+function renderCustomDbClass(table, urlTemplate) {
+  const slugTemplate = urlTemplate.replace("{slug}", "${post.slug}");
+  return `
+class MyStorage implements StorageAdapter {
+  async ping() {
+    return { site_name: '${table}', version: '1.0' }
+  }
+
+  async create_post(post: Post) {
+    const conn = await mysql.createConnection(process.env.DATABASE_URL!)
+    const [result] = await conn.execute(
+      \`INSERT INTO ${table}
+         (title, slug, content, description, status, external_source)
+         VALUES (?, ?, ?, ?, ?, ?)\`,
+      [post.title, post.slug, post.body_html,
+       post.excerpt || post.seo_meta?.description || '',
+       'published', 'panini'],
+    )
+    await conn.end()
+    const externalId = String((result as { insertId: number }).insertId)
+    return {
+      external_id: externalId,
+      external_url: \`${slugTemplate}\`,
+    }
+  }
+
+  async update_post(externalId: string, post: Post) {
+    const conn = await mysql.createConnection(process.env.DATABASE_URL!)
+    await conn.execute(
+      \`UPDATE ${table} SET title=?, content=?, description=? WHERE id=?\`,
+      [post.title, post.body_html, post.excerpt || '', externalId],
+    )
+    await conn.end()
+    return { external_id: externalId, external_url: \`${slugTemplate}\` }
+  }
+
+  async delete_post(externalId: string) {
+    const conn = await mysql.createConnection(process.env.DATABASE_URL!)
+    await conn.execute(\`DELETE FROM ${table} WHERE id=?\`, [externalId])
+    await conn.end()
+  }
+}
+`;
+}
+function buildPostNote(framework, storage) {
+  const parts = [];
+  if (storage === "custom_db") {
+    parts.push(
+      "Fill in the 4 methods of MyStorage with your DB queries \u2014 swap mysql2 for your driver (mongodb, mssql, cosmos, etc.)."
+    );
+  }
+  if (framework === "next_pages") {
+    parts.push(
+      "You MUST keep the `export const config = { api: { bodyParser: false } }` line \u2014 Next's default JSON parser would consume the raw bytes we need for HMAC verification."
+    );
+  }
+  if (framework === "express") {
+    parts.push(
+      "If you already have `express.json()` mounted globally, move it BELOW the `mount()` call so the SDK can read raw request bytes."
+    );
+  }
+  return parts.length ? parts.join(" ") : void 0;
+}
+function buildPython(framework, storage, table, urlTemplate, envVars, verifyCommand) {
+  const isCustomDb = storage === "custom_db";
+  const storageExtra = storage === "memory" || isCustomDb ? "" : `,${storage}`;
+  const install = `pip install "panini-connector[${framework}${storageExtra}] @ git+https://github.com/prak16/PaniniOS.git@main#subdirectory=sdk/panini-connector-py"` + (isCustomDb ? "\npip install pymysql   # or motor / pymongo / pymssql" : "");
+  const storageArg = isCustomDb ? "storage=MyStorage()" : storage === "supabase" || storage === "postgres" ? renderPyExistingTable(storage, table, urlTemplate) : `storage="${storage}"`;
+  const customDbClass = isCustomDb ? renderPyCustomDbClass(table, urlTemplate) : "";
+  const extraImport = isCustomDb ? "" : storage === "supabase" || storage === "postgres" ? `
+from panini_connector.storage.${storage} import ${storage === "supabase" ? "SupabaseStorage" : "PostgresStorage"}
+` : "\n";
+  let filePath = "main.py";
+  let code = "";
+  if (framework === "fastapi") {
+    filePath = "main.py";
+    code = `from fastapi import FastAPI
+from panini_connector import mount${extraImport}${customDbClass}
+app = FastAPI()
+mount(
+    app,
+    path="/api/seo-connector",
+    ${storageArg},
+)`;
+  } else if (framework === "django") {
+    filePath = "urls.py";
+    code = `from django.urls import path
+from panini_connector.framework.django import view${extraImport}${customDbClass}
+urlpatterns = [
+    # ... your existing routes ...
+    path(
+        "api/seo-connector",
+        view(${storageArg}),
+        name="panini_connector",
+    ),
+]`;
+  } else {
+    filePath = "app.py";
+    code = `from flask import Flask
+from panini_connector import mount_flask${extraImport}${customDbClass}
+app = Flask(__name__)
+mount_flask(
+    app,
+    path="/api/seo-connector",
+    ${storageArg},
+)`;
+  }
+  const parts = [];
+  if (isCustomDb) {
+    parts.push(
+      "Fill in the 4 methods of MyStorage with your DB queries \u2014 swap pymysql for your driver (motor / pymongo / pymssql / etc.)."
+    );
+  }
+  if (framework === "django") {
+    parts.push("Requires Django 4.1+ for async views. CSRF exemption is handled by the SDK.");
+  }
+  return {
+    install_command: install,
+    files: [{ path: filePath, content: code, language: "python" }],
+    env_vars: envVars,
+    post_install_note: parts.length ? parts.join(" ") : void 0,
+    verify_command: verifyCommand
+  };
+}
+function renderPyExistingTable(storage, table, urlTemplate) {
+  const cls = storage === "supabase" ? "SupabaseStorage" : "PostgresStorage";
+  return `storage=${cls}(
+        table="${table}",
+        external_id_column="id",
+        external_url_template="${urlTemplate}",
+        to_row=lambda post: {
+            "title": post["title"],
+            "slug": post["slug"],
+            "content": post["body_html"],
+            "description": post.get("excerpt") or post.get("seo_meta", {}).get("description", ""),
+            "meta_title": post.get("seo_meta", {}).get("title") or post["title"],
+            "meta_description": post.get("seo_meta", {}).get("description") or post.get("excerpt", ""),
+            "featured_image_url": post.get("featured_image_url"),
+            "author_name": post.get("author_name"),
+            "status": post.get("status", "published"),
+            "category": "seo",
+            "external_source": "panini",
+        },
+    )`;
+}
+function renderPyCustomDbClass(table, urlTemplate) {
+  const slugTemplate = urlTemplate.replace("{slug}", '{post["slug"]}');
+  return `
+import os
+import pymysql
+
+
+class MyStorage:
+    async def ping(self):
+        return {"site_name": "${table}", "version": "1.0"}
+
+    async def create_post(self, post):
+        conn = pymysql.connect(host="localhost", user="user", password="pass", db="dbname")
+        with conn.cursor() as cur:
+            cur.execute(
+                """INSERT INTO ${table}
+                   (title, slug, content, description, status, external_source)
+                   VALUES (%s, %s, %s, %s, %s, %s)""",
+                (post["title"], post["slug"], post["body_html"],
+                 post.get("excerpt", ""), "published", "panini"),
+            )
+            external_id = cur.lastrowid
+        conn.commit(); conn.close()
+        return {"external_id": str(external_id), "external_url": f"${slugTemplate}"}
+
+    async def update_post(self, external_id, post):
+        conn = pymysql.connect(host="localhost", user="user", password="pass", db="dbname")
+        with conn.cursor() as cur:
+            cur.execute(
+                """UPDATE ${table} SET title=%s, content=%s, description=%s WHERE id=%s""",
+                (post["title"], post["body_html"], post.get("excerpt", ""), external_id),
+            )
+        conn.commit(); conn.close()
+        return {"external_id": external_id, "external_url": f"${slugTemplate}"}
+
+    async def delete_post(self, external_id):
+        conn = pymysql.connect(host="localhost", user="user", password="pass", db="dbname")
+        with conn.cursor() as cur:
+            cur.execute("DELETE FROM ${table} WHERE id=%s", (external_id,))
+        conn.commit(); conn.close()
+
+
+`;
+}
+function envVarsFor(storage) {
+  const base = "SEO_CONNECTOR_SECRET=<call generate_shared_secret to get one>";
+  if (storage === "supabase") {
+    return `${base}
+SUPABASE_URL=https://xxxxx.supabase.co
+SUPABASE_SERVICE_ROLE_KEY=<service_role key, NOT anon>`;
+  }
+  if (storage === "postgres") {
+    return `${base}
+DATABASE_URL=postgresql://user:pass@host:5432/dbname`;
+  }
+  if (storage === "custom_db") {
+    return `${base}
+# Whatever env vars YOUR DB driver needs \u2014 e.g. for MySQL:
+DATABASE_URL=mysql://user:pass@host:3306/dbname`;
+  }
+  return base + "\n# (in-memory needs no extra env vars \u2014 posts vanish on restart)";
+}
+function registerInstallTool(server) {
+  server.registerTool(
+    "install_panini_connector",
+    {
+      title: "Install panini-connector on a site",
+      description: "Given the customer's stack (language + framework + storage), returns the exact commands, code, and env vars to wire panini-connector into their self-hosted site. The AI agent should: (1) call this tool, (2) run the install_command in the project root, (3) write each file to the path shown, (4) prompt the user to set the env_vars on their hosting platform, (5) tell them to redeploy, then (6) call verify_panini_connector to confirm the setup works end-to-end.",
+      inputSchema: {
+        language: z.enum(["node", "python"]).describe("The customer site's runtime language."),
+        framework: z.enum(["next_app", "next_pages", "express", "fastapi", "django", "flask"]).describe(
+          "The customer's web framework. next_app = Next.js App Router, next_pages = Next.js Pages Router. Must match `language`: node \u2192 next_app|next_pages|express; python \u2192 fastapi|django|flask."
+        ),
+        storage: z.enum(["supabase", "postgres", "custom_db", "memory"]).describe(
+          "Where posts land. supabase = Supabase via PostgREST. postgres = direct Postgres DSN. custom_db = MySQL/Mongo/MSSQL/CosmosDB/CMS \u2014 SDK generates a StorageAdapter class scaffold. memory = ephemeral in-memory (testing only, posts vanish on restart)."
+        ),
+        existing_table: z.string().optional().describe(
+          `Name of the customer's existing blog/posts table (e.g. "blog_posts"). For supabase/postgres, seeds the toRow mapping. For custom_db, seeds the SQL. Defaults to "blog_posts".`
+        ),
+        url_template: z.string().optional().describe(
+          'URL where published posts appear on the customer site. Use {slug} and/or {id} placeholders. Example: "https://mysite.com/blog/{slug}". Defaults to "https://yoursite.com/blog/{slug}".'
+        )
+      },
+      outputSchema: {
+        install_command: z.string(),
+        files: z.array(
+          z.object({
+            path: z.string(),
+            content: z.string(),
+            language: z.string()
+          })
+        ),
+        env_vars: z.string(),
+        post_install_note: z.string().optional(),
+        verify_command: z.string()
+      }
+    },
+    async (args) => {
+      const result = buildInstall(args);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        structuredContent: result
+      };
+    }
+  );
+}
+
+// src/tools/verify.ts
+import { createHmac } from "crypto";
+import { z as z2 } from "zod";
+var VERSION = "1";
+function computeSignature(secret, timestamp, rawBody) {
+  return "sha256=" + createHmac("sha256", secret).update(timestamp + "." + rawBody, "utf-8").digest("hex");
+}
+async function fireOp(url, secret, body, timeoutMs) {
+  const raw = JSON.stringify(body);
+  const ts = String(Math.floor(Date.now() / 1e3));
+  const sig = computeSignature(secret, ts, raw);
+  const controller = new AbortController();
+  const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const r = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Compass-Timestamp": ts,
+        "X-Compass-Signature": sig,
+        "X-Compass-Version": VERSION
+      },
+      body: raw,
+      signal: controller.signal
+    });
+    clearTimeout(timeoutHandle);
+    let parsed;
+    const text = await r.text();
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = text.slice(0, 500);
+    }
+    return { httpStatus: r.status, body: parsed };
+  } catch (e) {
+    clearTimeout(timeoutHandle);
+    const msg = e instanceof Error ? e.message : String(e);
+    return { httpStatus: 0, body: null, error: msg };
+  }
+}
+function newRequestId() {
+  return "mcp-verify-" + Date.now().toString(16) + "-" + Math.floor(Math.random() * 1e6).toString(16);
+}
+async function runVerify(input) {
+  const url = input.url;
+  const secret = input.secret;
+  const timeoutMs = input.timeout_ms ?? 1e4;
+  const ops = [];
+  let externalId;
+  const slug = `panini-mcp-smoke-${Date.now().toString(36)}`;
+  {
+    const req = { op: "ping", version: VERSION, request_id: newRequestId() };
+    const r = await fireOp(url, secret, req, timeoutMs);
+    const passed = r.httpStatus === 200;
+    ops.push({
+      op: "ping",
+      status: passed ? "pass" : "fail",
+      http_status: r.httpStatus,
+      response_body: r.body,
+      error: r.error
+    });
+    if (!passed) {
+      return summarize(url, ops);
+    }
+  }
+  {
+    const req = {
+      op: "create_post",
+      version: VERSION,
+      request_id: newRequestId(),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      post: {
+        title: "MCP verify smoke test",
+        slug,
+        body_html: "<p>Auto-generated by verify_panini_connector. Safe to delete.</p>",
+        excerpt: "MCP smoke test",
+        categories: [],
+        tags: [],
+        featured_image_url: "",
+        author_name: "panini-connector-mcp",
+        seo_meta: { title: "MCP smoke", description: "MCP smoke" },
+        json_ld: [],
+        status: "draft"
+      }
+    };
+    const r = await fireOp(url, secret, req, timeoutMs);
+    const passed = r.httpStatus === 200;
+    const body = r.body;
+    if (passed && body?.external_id) externalId = body.external_id;
+    ops.push({
+      op: "create_post",
+      status: passed ? "pass" : "fail",
+      http_status: r.httpStatus,
+      response_body: r.body,
+      error: r.error
+    });
+    if (!passed || !externalId) return summarize(url, ops);
+  }
+  {
+    const req = {
+      op: "update_post",
+      version: VERSION,
+      request_id: newRequestId(),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      external_id: externalId,
+      post: {
+        title: "MCP verify smoke test (updated)",
+        slug,
+        body_html: "<p>Updated. Safe to delete.</p>",
+        excerpt: "updated",
+        categories: [],
+        tags: [],
+        featured_image_url: "",
+        author_name: "panini-connector-mcp",
+        seo_meta: {},
+        json_ld: [],
+        status: "draft"
+      }
+    };
+    const r = await fireOp(url, secret, req, timeoutMs);
+    ops.push({
+      op: "update_post",
+      status: r.httpStatus === 200 ? "pass" : "fail",
+      http_status: r.httpStatus,
+      response_body: r.body,
+      error: r.error
+    });
+  }
+  {
+    const req = {
+      op: "delete_post",
+      version: VERSION,
+      request_id: newRequestId(),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      external_id: externalId,
+      post: {}
+    };
+    const r = await fireOp(url, secret, req, timeoutMs);
+    ops.push({
+      op: "delete_post",
+      status: r.httpStatus === 200 ? "pass" : "fail",
+      http_status: r.httpStatus,
+      response_body: r.body,
+      error: r.error
+    });
+  }
+  return summarize(url, ops);
+}
+function summarize(url, ops) {
+  const passes = ops.filter((o) => o.status === "pass").length;
+  const fails = ops.length - passes;
+  const ok = fails === 0 && ops.length === 4;
+  const summary = ok ? `\u2713 All 4 ops passed against ${url}. Connector is wired correctly.` : `\u2717 ${fails}/${ops.length} ops failed against ${url}. See per-op detail.`;
+  return { ok, url, ops, summary };
+}
+function registerVerifyTool(server) {
+  server.registerTool(
+    "verify_panini_connector",
+    {
+      title: "Verify a deployed panini-connector endpoint",
+      description: "Fire all 4 HMAC-signed operations (ping, create_post, update_post, delete_post) at the customer's deployed connector URL. Returns per-op status + diagnostics. Call this AFTER install_panini_connector's code has been written + env vars set + site redeployed, to confirm the round-trip works. If any op fails, the response_body will contain the customer's handler error text \u2014 enough to debug (wrong secret? missing table column? RLS policy? etc.). Cleans up after itself by deleting the smoke-test post.",
+      inputSchema: {
+        url: z2.string().url().describe(
+          'The full HTTPS URL of the deployed connector endpoint. Must end with the mount path (usually "/api/seo-connector"). Example: "https://mysite.com/api/seo-connector"'
+        ),
+        secret: z2.string().min(8).describe(
+          "The SEO_CONNECTOR_SECRET value set as an env var on the customer site. Must match byte-for-byte or all signatures will 401."
+        ),
+        timeout_ms: z2.number().int().min(1e3).max(6e4).optional().describe("Per-op HTTP timeout in ms. Default 10000.")
+      },
+      outputSchema: {
+        ok: z2.boolean(),
+        url: z2.string(),
+        ops: z2.array(
+          z2.object({
+            op: z2.enum(["ping", "create_post", "update_post", "delete_post"]),
+            status: z2.enum(["pass", "fail"]),
+            http_status: z2.number().optional(),
+            response_body: z2.any().optional(),
+            error: z2.string().optional()
+          })
+        ),
+        summary: z2.string()
+      }
+    },
+    async (args) => {
+      const result = await runVerify(args);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        structuredContent: result
+      };
+    }
+  );
+}
+
+// src/tools/secret.ts
+import { randomBytes } from "crypto";
+import { z as z3 } from "zod";
+function generateSharedSecret() {
+  const secret = randomBytes(32).toString("hex");
+  return { secret, length_bytes: 32 };
+}
+function registerSecretTool(server) {
+  server.registerTool(
+    "generate_shared_secret",
+    {
+      title: "Generate shared secret",
+      description: 'Generate a cryptographically-random 32-byte hex secret. Use this as the SEO_CONNECTOR_SECRET env var on the customer site AND paste the same value into the Panini dashboard "Shared secret" field \u2014 both sides must match for HMAC signatures to verify.',
+      inputSchema: {},
+      outputSchema: {
+        secret: z3.string().describe("64-character hex string (32 raw bytes)"),
+        length_bytes: z3.number().describe("Number of raw bytes before hex-encoding")
+      }
+    },
+    async () => {
+      const result = generateSharedSecret();
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        structuredContent: result
+      };
+    }
+  );
+}
+
+// src/tools/schema.ts
+import { z as z4 } from "zod";
+var ENVELOPE_CONTRACT = {
+  http_method: "POST",
+  request_headers: {
+    "Content-Type": "application/json",
+    "X-Compass-Timestamp": "<unix seconds, string>",
+    "X-Compass-Signature": "sha256=<64-hex-chars, HMAC-SHA256 over `${timestamp}.${raw_body}` with SEO_CONNECTOR_SECRET>",
+    "X-Compass-Version": "1"
+  },
+  request_body_shape: {
+    op: "create_post | update_post | delete_post | ping",
+    version: "1",
+    request_id: "<uuid>",
+    timestamp: "<ISO-8601 datetime>",
+    post: {
+      title: "string",
+      slug: "string (URL-safe)",
+      body_html: "string (rendered HTML)",
+      excerpt: "string (short summary)",
+      categories: "[string]",
+      tags: "[string]",
+      featured_image_url: "string (absolute URL) | null",
+      author_name: "string | null",
+      seo_meta: { title: "string", description: "string" },
+      json_ld: "[object] (Schema.org structured data)",
+      status: "publish | draft"
+    },
+    external_id: "<string, only for update_post + delete_post>"
+  },
+  response_success: {
+    http_status: 200,
+    body: {
+      ok: true,
+      external_id: "<your DB primary key for this post>",
+      external_url: "<publicly-viewable URL, e.g. https://mysite.com/blog/slug>"
+    }
+  },
+  response_ping: {
+    http_status: 200,
+    body: {
+      ok: true,
+      site_name: "<display name>",
+      version: "1",
+      supported_ops: ["ping", "create_post", "update_post", "delete_post"]
+    }
+  },
+  response_errors: {
+    signature_fail: { http_status: 401, body: { ok: false, error: "signature verification failed" } },
+    bad_envelope: { http_status: 400, body: { ok: false, error: "<parse error detail>" } },
+    unknown_post: { http_status: 404, body: { ok: false, error: "no post with external_id=<id>" } },
+    internal_error: { http_status: 500, body: { ok: false, error: "<internal>" } }
+  },
+  replay_window_seconds: 300,
+  hmac_pseudocode: 'expected = "sha256=" + HMAC_SHA256(SEO_CONNECTOR_SECRET, timestamp + "." + raw_body).hex_lower()\nif not constant_time_equal(expected, X-Compass-Signature): reject 401\nif abs(now_unix_seconds - int(timestamp)) > 300: reject 401',
+  laravel_example: `// PHP / Laravel \u2014 verify signature in a controller method
+$ts     = $request->header('X-Compass-Timestamp');
+$sig    = $request->header('X-Compass-Signature');
+$body   = $request->getContent();  // raw bytes, before any JSON parsing
+$expect = 'sha256=' . hash_hmac('sha256', "$ts.$body", env('SEO_CONNECTOR_SECRET'));
+if (!hash_equals($expect, $sig)) return response()->json(['ok' => false], 401);
+if (abs(time() - (int)$ts) > 300) return response()->json(['ok' => false], 401);
+$payload = json_decode($body, true);
+// ... route on $payload['op'], write to your DB, respond {ok, external_id, external_url}`
+};
+function getEnvelopeSchema() {
+  return ENVELOPE_CONTRACT;
+}
+function registerSchemaTool(server) {
+  server.registerTool(
+    "get_envelope_schema",
+    {
+      title: "Get envelope schema",
+      description: "Return the raw HTTP envelope contract Panini uses to POST to customer sites. Use this when the customer stack is NOT Node or Python (e.g. Laravel, Rails, Go, .NET, Rust) and you need to hand-implement the connector in their language. Includes request/response shapes, HMAC verification pseudocode, and a Laravel example.",
+      inputSchema: {},
+      outputSchema: {
+        http_method: z4.string(),
+        request_headers: z4.record(z4.string()),
+        request_body_shape: z4.record(z4.any()),
+        response_success: z4.record(z4.any()),
+        response_ping: z4.record(z4.any()),
+        response_errors: z4.record(z4.any()),
+        replay_window_seconds: z4.number(),
+        hmac_pseudocode: z4.string(),
+        laravel_example: z4.string()
+      }
+    },
+    async () => {
+      const result = getEnvelopeSchema();
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        structuredContent: result
+      };
+    }
+  );
+}
+
+// src/index.ts
+function log(message) {
+  process.stderr.write(`[panini-connector-mcp] ${message}
+`);
+}
+async function main() {
+  const server = new McpServer(
+    {
+      name: "panini-connector-mcp",
+      version: "0.1.0"
+    },
+    {
+      capabilities: {
+        tools: {}
+      }
+    }
+  );
+  registerInstallTool(server);
+  registerVerifyTool(server);
+  registerSecretTool(server);
+  registerSchemaTool(server);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  log("server ready (stdio) \u2014 tools: install_panini_connector, verify_panini_connector, generate_shared_secret, get_envelope_schema");
+}
+main().catch((err) => {
+  process.stderr.write(`[panini-connector-mcp] fatal: ${err?.stack ?? err}
+`);
+  process.exit(1);
+});
+export {
+  log
+};
+//# sourceMappingURL=index.js.map