trust_passport

Instructions

Implementation Reference

• src/index.ts:83-125 (schema)

  TrustPassportResponse interface — defines the schema for the trust passport API response, including artifact info, capabilities with confidence/matches/success_rate, and trust metadata (score, data_access_risk, permissions, failure_modes, observed_outcomes).

  interface TrustPassportResponse {
    unfragile: {
      version: string;
      artifact: {
        id: string;
        slug: string;
        name: string;
        type: string;
        url: string;
        page_url: string;
        status: string;
        verified: boolean;
        categories: string[];
      };
      capabilities: Array<{
        id: string;
        uri: string;
        name: string;
        description: string;
        intents: string[];
        best_for: string[];
        limitations: string[];
        requires: string[];
        confidence: number;
        matches: number;
        success_rate: number;
      }>;
      trust: {
        score: number;
        verified: boolean;
        data_access_risk: "low" | "moderate" | "high";
        permissions: string[];
        failure_modes: string[];
        observed_outcomes: {
          matches: number;
          success_rate: number;
          avg_confidence: number;
          top_intents: string[];
        };
      };
    };
    _links: Record<string, string>;
  }

• src/index.ts:547-563 (registration)

  Registration of the 'trust_passport' tool with the MCP server. Defines the tool name, description, schema (slug parameter via Zod), and handler function. Calls passportAPI(slug) and formats result via formatPassport().

  // Tool 5: Trust passport
  server.tool(
    "trust_passport",
    "Get the machine-readable trust passport for an AI artifact. Use this before an agent selects a tool, API, MCP server, model, repo, or framework for a task. Returns capability URIs, permissions, data access risk, known failure modes, observed outcomes, and trust score.",
    {
      slug: z.string().min(1).max(200).describe("Artifact slug (e.g., 'cursor', 'claude-code', 'langchain')"),
    },
    async ({ slug }) => {
      log("trust_passport", slug);
      try {
        const data = await passportAPI(slug);
        return { content: [{ type: "text" as const, text: formatPassport(data) }] };
      } catch (err) {
        return { content: [{ type: "text" as const, text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
      }
    }
  );

• src/index.ts:554-562 (handler)

  The handler function for the trust_passport tool. Logs the call, calls passportAPI(slug) to fetch the trust passport data, and formats the response using formatPassport() or returns an error message.

  async ({ slug }) => {
    log("trust_passport", slug);
    try {
      const data = await passportAPI(slug);
      return { content: [{ type: "text" as const, text: formatPassport(data) }] };
    } catch (err) {
      return { content: [{ type: "text" as const, text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
    }
  }

• src/index.ts:205-227 (helper)

  passportAPI(slug) — helper function that makes the HTTP request to the Unfragile API endpoint /api/v1/passport/{slug}. Handles headers, timeout (15s), error responses, and returns parsed TrustPassportResponse JSON.

  async function passportAPI(slug: string): Promise<TrustPassportResponse> {
    const headers: Record<string, string> = { Accept: "application/json" };
    if (API_KEY) headers["X-API-Key"] = API_KEY;
  
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), 15_000);
  
    try {
      const res = await fetch(`${API_BASE}/api/v1/passport/${encodeURIComponent(slug)}`, {
        headers,
        signal: controller.signal,
      });
  
      if (!res.ok) {
        const text = await res.text();
        throw new Error(`Unfragile passport API error ${res.status}: ${text}`);
      }
  
      return res.json() as Promise<TrustPassportResponse>;
    } finally {
      clearTimeout(timeout);
    }
  }

• src/index.ts:348-384 (helper)

  formatPassport(data) — helper function that formats the TrustPassportResponse into human-readable text. Outputs artifact name, type, trust score, data access risk, permissions, failure modes, observed outcomes, capability URIs, and links to full passport JSON and artifact page.

  function formatPassport(data: TrustPassportResponse): string {
    const p = data.unfragile;
    const lines: string[] = [];
    lines.push(`# Trust Passport: ${p.artifact.name}`);
    lines.push(`**Type:** ${p.artifact.type} | **Trust Score:** ${p.trust.score}/100 | **Verified:** ${p.trust.verified ? "Yes ✓" : "No"}`);
    lines.push(`**Data access risk:** ${p.trust.data_access_risk}`);
    lines.push(`**URL:** ${p.artifact.url}`);
  
    if (p.trust.permissions.length > 0) {
      lines.push(`\n## Permissions / Requirements`);
      for (const permission of p.trust.permissions) lines.push(`- ${permission}`);
    }
  
    if (p.trust.failure_modes.length > 0) {
      lines.push(`\n## Known Failure Modes`);
      for (const failure of p.trust.failure_modes) lines.push(`- ${failure}`);
    }
  
    lines.push(`\n## Observed Outcomes`);
    lines.push(`- Matches: ${p.trust.observed_outcomes.matches}`);
    lines.push(`- Success rate: ${Math.round(p.trust.observed_outcomes.success_rate * 100)}%`);
    lines.push(`- Avg confidence: ${Math.round(p.trust.observed_outcomes.avg_confidence * 100)}%`);
    if (p.trust.observed_outcomes.top_intents.length > 0) {
      lines.push(`- Top intents: ${p.trust.observed_outcomes.top_intents.join(", ")}`);
    }
  
    if (p.capabilities.length > 0) {
      lines.push(`\n## Capability URIs`);
      for (const cap of p.capabilities.slice(0, 8)) {
        lines.push(`- \`${cap.uri}\` — ${cap.name} (${Math.round(cap.confidence * 100)}% confidence)`);
      }
    }
  
    lines.push(`\n→ Full passport JSON: ${data._links.self}`);
    lines.push(`→ Artifact page: ${p.artifact.page_url}`);
    return lines.join("\n");
  }