vigile_check_provenance

Instructions

Implementation Reference

• src/tools/check-provenance.ts:7-38 (handler)

  The core handler function `checkProvenance` that executes the provenance lookup logic. It calls the Vigile API at `/api/v1/memory/sources/{sourceId}`, and returns a formatted markdown string with provenance context, source type, generation timestamp, provenance completeness flag, and the full source payload JSON.

  export async function checkProvenance(
    baseUrl: string,
    apiKey: string,
    sourceId: string,
  ): Promise<string> {
    const { ok, status, data } = await fetchVigile(
      baseUrl,
      apiKey,
      `/api/v1/memory/sources/${encodeURIComponent(sourceId)}`
    );
  
    if (!ok) {
      return `Provenance lookup failed for ${sourceId}: ${data?.detail || `HTTP ${status}`}`;
    }
  
    const source = data?.source || {};
    const lines = [
      `## Provenance: ${sourceId}`,
      "",
      data?.answer_context || "No provenance context returned.",
      "",
      `Source Type: ${source.source_type || "unknown"}`,
      `Generated At: ${source.generated_at || "unknown"}`,
      `Provenance Complete: ${Boolean(data?.provenance_complete)}`,
      "",
      "### Source Payload",
      "```json",
      JSON.stringify(source.body || {}, null, 2),
      "```",
    ];
    return lines.join("\n");
  }

• src/index.ts:169-170 (schema)

  Input schema (Zod) for the `source_id` parameter: a string of 3-128 characters describing the canonical source identifier.

    source_id: z.string().min(3).max(128).describe("Canonical source identifier"),
  },

• src/index.ts:165-175 (registration)

  Registration of the tool `vigile_check_provenance` on the MCP server with description, schema, and handler that delegates to `checkProvenance()` from the handler module.

  server.tool(
    "vigile_check_provenance",
    "Fetch canonical provenance payload for a memory source ID.",
    {
      source_id: z.string().min(3).max(128).describe("Canonical source identifier"),
    },
    async ({ source_id }) => {
      const result = await checkProvenance(API_BASE, API_KEY, source_id);
      return { content: [{ type: "text" as const, text: result }] };
    }
  );

• src/tools/api.ts:5-46 (helper)

  The `fetchVigile` helper used by the handler to make authenticated HTTP requests to the Vigile API. It handles authorization, error sanitization, and returns structured `{ ok, status, data }` responses.

  export async function fetchVigile(
    baseUrl: string,
    apiKey: string,
    path: string,
    options?: { method?: string; body?: string }
  ): Promise<{ ok: boolean; status: number; data: any }> {
    const headers: Record<string, string> = {
      "Content-Type": "application/json",
      "User-Agent": "vigile-mcp/0.1.7",
    };
  
    if (apiKey) {
      headers["Authorization"] = `Bearer ${apiKey}`;
    }
  
    try {
      const res = await fetch(`${baseUrl}${path}`, {
        method: options?.method || "GET",
        headers,
        body: options?.body,
      });
  
      const data = await res.json().catch(() => null);
      return { ok: res.ok, status: res.status, data };
    } catch (error: any) {
      // Sanitize error message — don't leak internal details like
      // hostnames, ports, file paths, or stack traces
      const rawMsg = error?.message || "Unknown error";
      const safeMsg = rawMsg.includes("ECONNREFUSED") || rawMsg.includes("ENOTFOUND")
        ? "API server unreachable"
        : rawMsg.includes("ETIMEDOUT") || rawMsg.includes("timeout")
        ? "Request timed out"
        : rawMsg.includes("ECONNRESET")
        ? "Connection reset"
        : "Connection failed";
      return {
        ok: false,
        status: 0,
        data: { detail: safeMsg },
      };
    }
  }

• src/index.ts:24-24 (registration)

  Import of the `checkProvenance` function from the handler module into the main server entry point.

  import { checkProvenance } from "./tools/check-provenance.js";