spaps-mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 - 2026-06-15
+
+- Initial SPAPS MCP stdio server with docs, auth discovery, capability, wizard,
+  and integration verification tools.
+- Bundles wizard steps from the canonical repository source at build time.

package/README.md

@@ -0,0 +1,76 @@
+# spaps-mcp
+
+`spaps-mcp` exposes SPAPS documentation, endpoint contracts, auth discovery,
+capability checks, and integration wizard steps to MCP-capable agents.
+
+## Metadata
+
+- `package_name`: `spaps-mcp`
+- `latest_version`: `0.1.0`
+- `minimum_runtime`: `Node.js >=18.0.0`
+- `api_base_url`: `https://api.sweetpotato.dev`
+
+## Installation
+
+```bash
+npm install spaps-mcp
+```
+
+## Claude Code
+
+The Sweet Potato repo also includes a portable root `.mcp.example.json` for
+local checkouts.
+
+```json
+{
+  "mcpServers": {
+    "spaps": {
+      "command": "npx",
+      "args": ["spaps-mcp"],
+      "env": {
+        "SPAPS_API_URL": "http://localhost:3301",
+        "SPAPS_API_KEY": "spaps_pub_replace_me",
+        "SPAPS_ORIGIN": "http://localhost:3000"
+      }
+    }
+  }
+}
+```
+
+## Generic MCP
+
+Run the stdio server directly:
+
+```bash
+SPAPS_API_URL=https://api.sweetpotato.dev \
+SPAPS_API_KEY=spaps_pub_replace_me \
+SPAPS_ORIGIN=https://your-app.example \
+npx spaps-mcp
+```
+
+Secret-key tools are disabled by default. To enable graph contract and decision
+explain tools, configure a secret SPAPS key and opt in explicitly:
+
+```bash
+SPAPS_API_KEY=spaps_sec_replace_me \
+SPAPS_MCP_ENABLE_SECRET_TOOLS=true \
+npx spaps-mcp
+```
+
+## Tools
+
+- `searchDocs`
+- `getEndpoint`
+- `getErrorCode`
+- `getExample`
+- `listAuthMethods`
+- `capabilityCheck`
+- `getCapabilityContract`
+- `capabilityExplain`
+- `listWizardSteps`
+- `getWizardStep`
+- `verifyIntegration`
+
+Wizard steps are copied from the canonical
+`agent-instructions/spaps-wizard-steps/` directory during package build. They are
+not maintained by hand inside this package.

package/dist/chunk-GPBTYWDD.js

@@ -0,0 +1,496 @@
+// src/http.ts
+var SpapsHttpError = class extends Error {
+  data;
+  constructor(data) {
+    super(data.message);
+    this.name = "SpapsHttpError";
+    this.data = data;
+  }
+};
+function resolveConfig(env = process.env) {
+  const apiUrl = (env.SPAPS_API_URL || "http://localhost:3301").replace(/\/+$/, "");
+  const enableSecretTools = ["1", "true", "yes", "on"].includes(
+    String(env.SPAPS_MCP_ENABLE_SECRET_TOOLS || "").toLowerCase()
+  );
+  return {
+    apiUrl,
+    apiKey: env.SPAPS_API_KEY || void 0,
+    bearerToken: env.SPAPS_AUTH_TOKEN || void 0,
+    origin: env.SPAPS_ORIGIN || void 0,
+    enableSecretTools,
+    wizardDir: env.SPAPS_WIZARD_STEPS_DIR || void 0
+  };
+}
+function appendQuery(url, query) {
+  if (!query) {
+    return;
+  }
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== void 0) {
+      url.searchParams.set(key, String(value));
+    }
+  }
+}
+function unwrapEnvelope(payload, status, requestId) {
+  if (!payload || typeof payload !== "object") {
+    return payload;
+  }
+  const record = payload;
+  if (record.success === false) {
+    const error = typeof record.error === "object" && record.error ? record.error : {};
+    throw new SpapsHttpError({
+      status,
+      code: typeof error.code === "string" ? error.code : "SPAPS_ERROR",
+      message: typeof error.message === "string" ? error.message : "SPAPS request failed",
+      request_id: typeof record.request_id === "string" ? record.request_id : requestId,
+      details: error.details,
+      diagnostics: record.diagnostics,
+      remediations: record.remediations
+    });
+  }
+  if (record.success === true && Object.prototype.hasOwnProperty.call(record, "data")) {
+    return record.data;
+  }
+  return payload;
+}
+var SpapsHttpClient = class {
+  config;
+  fetchFn;
+  constructor(config, fetchFn = fetch) {
+    this.config = config;
+    this.fetchFn = fetchFn;
+  }
+  async get(path, options = {}) {
+    return this.request("GET", path, options);
+  }
+  async post(path, body, options = {}) {
+    return this.request("POST", path, { ...options, body });
+  }
+  async request(method, path, options = {}) {
+    const url = new URL(path, `${this.config.apiUrl}/`);
+    appendQuery(url, options.query);
+    const headers = {
+      accept: "application/json"
+    };
+    if (options.body !== void 0) {
+      headers["content-type"] = "application/json";
+    }
+    if (this.config.apiKey) {
+      headers["X-API-Key"] = this.config.apiKey;
+    }
+    if (this.config.bearerToken) {
+      headers.authorization = `Bearer ${this.config.bearerToken}`;
+    }
+    if (this.config.origin) {
+      headers.origin = this.config.origin;
+    }
+    const response = await this.fetchFn(url, {
+      method,
+      headers,
+      body: options.body === void 0 ? void 0 : JSON.stringify(options.body)
+    });
+    const requestId = response.headers.get("x-request-id") || void 0;
+    const text = await response.text();
+    const payload = text ? JSON.parse(text) : null;
+    if (!response.ok) {
+      const record = payload && typeof payload === "object" ? payload : {};
+      const error = typeof record.error === "object" && record.error ? record.error : {};
+      throw new SpapsHttpError({
+        status: response.status,
+        code: typeof error.code === "string" ? error.code : `HTTP_${response.status}`,
+        message: typeof error.message === "string" ? error.message : response.statusText,
+        request_id: typeof record.request_id === "string" ? record.request_id : requestId,
+        details: error.details,
+        diagnostics: record.diagnostics,
+        remediations: record.remediations
+      });
+    }
+    return unwrapEnvelope(payload, response.status, requestId);
+  }
+};
+function docsPath(method, path) {
+  const normalizedMethod = method.toUpperCase();
+  const normalizedPath = path.replace(/^\/+/, "");
+  return `/api/docs/endpoints/${encodeURIComponent(normalizedMethod)}/${normalizedPath}`;
+}
+function docsPathWithCapturedLeadingSlash(method, path) {
+  const normalizedMethod = method.toUpperCase();
+  const normalizedPath = path.replace(/^\/+/, "");
+  return `/api/docs/endpoints/${encodeURIComponent(normalizedMethod)}//${normalizedPath}`;
+}
+
+// src/resources.ts
+import { readFile } from "fs/promises";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+function packagedResourcesDir() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "resources");
+}
+function resourceDefinition(name, filename, title, description, mimeType = "text/markdown") {
+  const uri = `spaps://resources/${filename}`;
+  return {
+    name,
+    uri,
+    title,
+    description,
+    mimeType,
+    async read() {
+      return {
+        contents: [{
+          uri,
+          mimeType,
+          text: await readFile(resolve(packagedResourcesDir(), filename), "utf8")
+        }]
+      };
+    }
+  };
+}
+function buildResourceDefinitions() {
+  return [
+    resourceDefinition(
+      "llms",
+      "llms.txt",
+      "SPAPS llms.txt",
+      "Published SPAPS AI documentation index.",
+      "text/plain"
+    ),
+    resourceDefinition(
+      "glossary",
+      "glossary.md",
+      "SPAPS Glossary",
+      "Shared SPAPS terminology and auth/payment vocabulary."
+    ),
+    resourceDefinition(
+      "surfaceContract",
+      "SPAPS_SURFACE_CONTRACT.md",
+      "SPAPS Surface Contract",
+      "Contract boundaries for SPAPS CLI, SDK, docs, and server surfaces."
+    )
+  ];
+}
+
+// src/wizard.ts
+import { readFile as readFile2, readdir } from "fs/promises";
+import { dirname as dirname2, resolve as resolve2 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+function packagedWizardDir() {
+  return resolve2(dirname2(fileURLToPath2(import.meta.url)), "wizard");
+}
+function resolveWizardDir(explicitDir) {
+  return explicitDir || packagedWizardDir();
+}
+function parseStepNumber(filename) {
+  const match = /^step-(\d+)-.*\.md$/.exec(filename);
+  return match ? Number.parseInt(match[1], 10) : null;
+}
+async function readLock(wizardDir) {
+  try {
+    const payload = JSON.parse(await readFile2(resolve2(wizardDir, "wizard.lock"), "utf8"));
+    return new Map((payload.steps || []).map((step) => [step.path, step.sha256]));
+  } catch {
+    return /* @__PURE__ */ new Map();
+  }
+}
+async function stepFilenames(wizardDir) {
+  const entries = await readdir(wizardDir);
+  return entries.filter((entry) => entry.startsWith("step-") && entry.endsWith(".md")).sort();
+}
+async function titleFor(wizardDir, filename) {
+  const content = await readFile2(resolve2(wizardDir, filename), "utf8");
+  const firstLine = content.split(/\r?\n/, 1)[0] || filename;
+  return firstLine.replace(/^#\s*/, "").trim();
+}
+async function listWizardSteps(wizardDir) {
+  const lock = await readLock(wizardDir);
+  const files = await stepFilenames(wizardDir);
+  const steps = await Promise.all(files.map(async (filename) => {
+    const step = parseStepNumber(filename);
+    if (step === null) {
+      throw new Error(`Invalid wizard step filename: ${filename}`);
+    }
+    return {
+      step,
+      path: filename,
+      title: await titleFor(wizardDir, filename),
+      sha256: lock.get(filename)
+    };
+  }));
+  return { count: steps.length, steps };
+}
+async function getWizardStep(wizardDir, stepNumber) {
+  const listed = await listWizardSteps(wizardDir);
+  const summary = listed.steps.find((step) => step.step === stepNumber);
+  if (!summary) {
+    throw new Error(`Wizard step ${stepNumber} not found`);
+  }
+  const content = await readFile2(resolve2(wizardDir, summary.path), "utf8");
+  return { ...summary, content };
+}
+
+// src/tools.ts
+import { z } from "zod";
+function jsonResult(payload) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+  };
+}
+function errorResult(error) {
+  if (error instanceof SpapsHttpError) {
+    return jsonResult({
+      ok: false,
+      error: error.data
+    });
+  }
+  return {
+    isError: true,
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        ok: false,
+        error: {
+          code: "SPAPS_MCP_ERROR",
+          message: error instanceof Error ? error.message : String(error)
+        }
+      }, null, 2)
+    }]
+  };
+}
+function guarded(handler) {
+  return async (input) => {
+    try {
+      return await handler(input);
+    } catch (error) {
+      const result = errorResult(error);
+      result.isError = true;
+      return result;
+    }
+  };
+}
+function requireSecretTools(config) {
+  if (config.enableSecretTools) {
+    return null;
+  }
+  return {
+    isError: true,
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        ok: false,
+        error: {
+          code: "SPAPS_MCP_SECRET_TOOL_DISABLED",
+          message: "Set SPAPS_MCP_ENABLE_SECRET_TOOLS=true and configure a secret SPAPS_API_KEY before using this tool."
+        }
+      }, null, 2)
+    }]
+  };
+}
+function buildToolDefinitions({ config, fetchFn, client = new SpapsHttpClient(config, fetchFn) }) {
+  const wizardDir = resolveWizardDir(config.wizardDir);
+  return [
+    {
+      name: "searchDocs",
+      title: "Search SPAPS Docs",
+      description: "Search SPAPS documentation through the authenticated docs search API.",
+      inputSchema: {
+        query: z.string().min(3),
+        context: z.string().optional(),
+        limit: z.number().int().min(1).max(20).optional(),
+        includeExamples: z.boolean().optional(),
+        language: z.string().optional()
+      },
+      handler: guarded(async (input) => jsonResult(await client.post("/api/docs/search", input)))
+    },
+    {
+      name: "getEndpoint",
+      title: "Get Endpoint Metadata",
+      description: "Fetch endpoint docs and manifest metadata for one SPAPS route.",
+      inputSchema: {
+        method: z.string().min(1),
+        path: z.string().min(1)
+      },
+      handler: guarded(async (input) => {
+        const method = String(input.method);
+        const path = String(input.path);
+        try {
+          return jsonResult(await client.get(docsPath(method, path)));
+        } catch (error) {
+          if (error instanceof SpapsHttpError && error.data.status === 404) {
+            return jsonResult(await client.get(docsPathWithCapturedLeadingSlash(method, path)));
+          }
+          throw error;
+        }
+      })
+    },
+    {
+      name: "getErrorCode",
+      title: "Get Error Code",
+      description: "Fetch SPAPS error-code documentation.",
+      inputSchema: {
+        code: z.string().min(1),
+        includeExamples: z.boolean().optional()
+      },
+      handler: guarded(async (input) => jsonResult(await client.get(
+        `/api/docs/errors/${encodeURIComponent(String(input.code))}`,
+        { query: { includeExamples: input.includeExamples } }
+      )))
+    },
+    {
+      name: "getExample",
+      title: "Get Example",
+      description: "Fetch a named SPAPS integration example.",
+      inputSchema: {
+        feature: z.string().min(1),
+        language: z.string().optional()
+      },
+      handler: guarded(async (input) => jsonResult(await client.get(
+        `/api/docs/examples/${encodeURIComponent(String(input.feature))}`,
+        { query: { language: input.language } }
+      )))
+    },
+    {
+      name: "listAuthMethods",
+      title: "List Auth Methods",
+      description: "Return the public auth-method matrix for the configured SPAPS application key.",
+      inputSchema: {},
+      handler: guarded(async () => jsonResult(await client.get("/api/auth/methods")))
+    },
+    {
+      name: "capabilityCheck",
+      title: "Capability Check",
+      description: "Run a SPAPS access decision. Publishable callers must provide a self-scoped bearer token when required by the API.",
+      inputSchema: {
+        actor: z.record(z.string(), z.unknown()),
+        action: z.string().min(1),
+        resource: z.record(z.string(), z.unknown()),
+        controls: z.record(z.string(), z.unknown()).optional(),
+        context: z.record(z.string(), z.unknown()).optional()
+      },
+      handler: guarded(async (input) => jsonResult(await client.post("/api/access/decide", input)))
+    },
+    {
+      name: "getCapabilityContract",
+      title: "Get Capability Contract",
+      description: "Fetch the machine-readable capability graph contract. Requires explicit secret-tool opt-in.",
+      inputSchema: {},
+      handler: guarded(async () => {
+        const disabled = requireSecretTools(config);
+        return disabled || jsonResult(await client.get("/api/contract"));
+      })
+    },
+    {
+      name: "capabilityExplain",
+      title: "Explain Capability Decision",
+      description: "Explain a prior capability decision trace by ID. Requires explicit secret-tool opt-in.",
+      inputSchema: {
+        decision_id: z.string().uuid()
+      },
+      handler: guarded(async (input) => {
+        const disabled = requireSecretTools(config);
+        return disabled || jsonResult(await client.get(`/api/graph/explain/${encodeURIComponent(String(input.decision_id))}`));
+      })
+    },
+    {
+      name: "listWizardSteps",
+      title: "List Wizard Steps",
+      description: "List bundled SPAPS Integration Wizard steps from the canonical build artifact.",
+      inputSchema: {},
+      handler: guarded(async () => jsonResult(await listWizardSteps(wizardDir)))
+    },
+    {
+      name: "getWizardStep",
+      title: "Get Wizard Step",
+      description: "Return one SPAPS Integration Wizard step by number.",
+      inputSchema: {
+        step: z.number().int().min(1).max(12)
+      },
+      handler: guarded(async (input) => jsonResult(await getWizardStep(wizardDir, Number(input.step))))
+    },
+    {
+      name: "verifyIntegration",
+      title: "Verify SPAPS Integration",
+      description: "Run non-mutating health checks against the configured or supplied SPAPS base URL.",
+      inputSchema: {
+        target_base_url: z.string().url().optional(),
+        include_auth_methods: z.boolean().optional()
+      },
+      handler: guarded(async (input) => {
+        const targetConfig = input.target_base_url ? { ...config, apiUrl: String(input.target_base_url).replace(/\/+$/, "") } : config;
+        const targetClient = input.target_base_url ? new SpapsHttpClient(targetConfig, fetchFn) : client;
+        const results = [
+          { test: "health", success: false, details: null },
+          { test: "ready", success: false, details: null },
+          { test: "local_mode_contract", success: false, details: null }
+        ];
+        results[0].details = await targetClient.get("/health");
+        results[0].success = true;
+        results[1].details = await targetClient.get("/health/ready");
+        results[1].success = true;
+        results[2].details = await targetClient.get("/health/local-mode");
+        results[2].success = true;
+        if (input.include_auth_methods) {
+          results.push({
+            test: "auth_methods",
+            success: true,
+            details: await targetClient.get("/api/auth/methods")
+          });
+        }
+        return jsonResult({
+          success: true,
+          summary: `${results.filter((result) => result.success).length}/${results.length} tests passed`,
+          target_base_url: targetConfig.apiUrl,
+          results,
+          next_steps: [`See docs at ${targetConfig.apiUrl}/docs`]
+        });
+      })
+    }
+  ];
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+function createSpapsMcpServer(options = {}) {
+  const config = options.config || resolveConfig();
+  const client = new SpapsHttpClient(config, options.fetchFn);
+  const server = new McpServer({
+    name: "spaps-mcp",
+    version: "0.1.0"
+  });
+  for (const tool of buildToolDefinitions({ config, client })) {
+    server.registerTool(
+      tool.name,
+      {
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema
+      },
+      tool.handler
+    );
+  }
+  for (const resource of buildResourceDefinitions()) {
+    server.registerResource(
+      resource.name,
+      resource.uri,
+      {
+        title: resource.title,
+        description: resource.description,
+        mimeType: resource.mimeType
+      },
+      resource.read
+    );
+  }
+  return server;
+}
+
+export {
+  SpapsHttpError,
+  resolveConfig,
+  SpapsHttpClient,
+  docsPath,
+  docsPathWithCapturedLeadingSlash,
+  buildResourceDefinitions,
+  resolveWizardDir,
+  listWizardSteps,
+  getWizardStep,
+  buildToolDefinitions,
+  createSpapsMcpServer
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import {
+  createSpapsMcpServer
+} from "./chunk-GPBTYWDD.js";
+
+// src/cli.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+var server = createSpapsMcpServer();
+await server.connect(new StdioServerTransport());

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+interface SpapsMcpConfig {
+    apiUrl: string;
+    apiKey?: string;
+    bearerToken?: string;
+    origin?: string;
+    enableSecretTools: boolean;
+    wizardDir?: string;
+}
+interface RequestOptions {
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+}
+type FetchLike = typeof fetch;
+interface SpapsHttpErrorData {
+    status: number;
+    code: string;
+    message: string;
+    request_id?: string;
+    details?: unknown;
+    diagnostics?: unknown;
+    remediations?: unknown;
+}
+declare class SpapsHttpError extends Error {
+    data: SpapsHttpErrorData;
+    constructor(data: SpapsHttpErrorData);
+}
+declare function resolveConfig(env?: NodeJS.ProcessEnv): SpapsMcpConfig;
+declare class SpapsHttpClient {
+    private readonly config;
+    private readonly fetchFn;
+    constructor(config: SpapsMcpConfig, fetchFn?: FetchLike);
+    get(path: string, options?: RequestOptions): Promise<unknown>;
+    post(path: string, body?: unknown, options?: RequestOptions): Promise<unknown>;
+    request(method: string, path: string, options?: RequestOptions): Promise<unknown>;
+}
+declare function docsPath(method: string, path: string): string;
+declare function docsPathWithCapturedLeadingSlash(method: string, path: string): string;
+
+interface CreateServerOptions {
+    config?: SpapsMcpConfig;
+    fetchFn?: FetchLike;
+}
+declare function createSpapsMcpServer(options?: CreateServerOptions): McpServer;
+
+interface ToolResult {
+    [key: string]: unknown;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}
+type ToolHandler = (input: Record<string, unknown>) => Promise<ToolResult>;
+interface ToolDefinition {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: Record<string, z.ZodTypeAny>;
+    handler: ToolHandler;
+}
+interface ToolBuildOptions {
+    config: SpapsMcpConfig;
+    client?: SpapsHttpClient;
+    fetchFn?: FetchLike;
+}
+declare function buildToolDefinitions({ config, fetchFn, client }: ToolBuildOptions): ToolDefinition[];
+
+interface ResourceDefinition {
+    name: string;
+    uri: string;
+    title: string;
+    description: string;
+    mimeType: string;
+    read(): Promise<{
+        contents: Array<{
+            uri: string;
+            mimeType: string;
+            text: string;
+        }>;
+    }>;
+}
+declare function buildResourceDefinitions(): ResourceDefinition[];
+
+interface WizardStepSummary {
+    step: number;
+    path: string;
+    title: string;
+    sha256?: string;
+}
+interface WizardStep extends WizardStepSummary {
+    content: string;
+}
+declare function resolveWizardDir(explicitDir?: string): string;
+declare function listWizardSteps(wizardDir: string): Promise<{
+    count: number;
+    steps: WizardStepSummary[];
+}>;
+declare function getWizardStep(wizardDir: string, stepNumber: number): Promise<WizardStep>;
+
+export { type ResourceDefinition, SpapsHttpClient, SpapsHttpError, type SpapsHttpErrorData, type SpapsMcpConfig, type ToolDefinition, type ToolResult, type WizardStep, type WizardStepSummary, buildResourceDefinitions, buildToolDefinitions, createSpapsMcpServer, docsPath, docsPathWithCapturedLeadingSlash, getWizardStep, listWizardSteps, resolveConfig, resolveWizardDir };