@fidensa/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,149 @@
+# @fidensa/mcp-server
+
+MCP server for [Fidensa](https://fidensa.com) — the independent AI capability certification authority.
+
+Gives your AI agent structured access to Fidensa certification data through the Model Context Protocol. Check trust scores, search for certified alternatives, compare capabilities side-by-side, and verify signed artifacts — all through MCP tool calls.
+
+## Quick Start
+
+```bash
+npx @fidensa/mcp-server
+```
+
+Or install globally:
+
+```bash
+npm install -g @fidensa/mcp-server
+fidensa-mcp-server
+```
+
+## Configuration
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `FIDENSA_API_KEY` | No* | API key for full access. Get one free at [fidensa.com/docs/api](https://fidensa.com/docs/api) |
+| `FIDENSA_BASE_URL` | No | Override API base URL (default: `https://fidensa.com`) |
+
+\* `check_certification` and `search_capabilities` work without an API key. Other tools require a free Registered-tier key.
+
+## Tools
+
+| Tool | Auth | Description |
+|------|------|-------------|
+| `check_certification` | None | Quick trust check — status, score, grade, tier |
+| `search_capabilities` | None | Search for certified capabilities by keyword |
+| `get_contract` | API key | Full certification contract with all evidence |
+| `compare_capabilities` | API key | Side-by-side comparison of 2-5 capabilities |
+| `verify_artifact` | API key | Verify cryptographic signatures on .cert.json artifacts |
+| `report_experience` | — | Consumer experience reporting (coming soon) |
+
+## Agent Configuration
+
+### Claude Code
+
+Add to your Claude Code MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "fidensa": {
+      "command": "npx",
+      "args": ["@fidensa/mcp-server"],
+      "env": {
+        "FIDENSA_API_KEY": "fid_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "fidensa": {
+      "command": "npx",
+      "args": ["@fidensa/mcp-server"],
+      "env": {
+        "FIDENSA_API_KEY": "fid_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Windsurf / VS Code
+
+Add to your MCP configuration:
+
+```json
+{
+  "servers": {
+    "fidensa": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@fidensa/mcp-server"],
+      "env": {
+        "FIDENSA_API_KEY": "fid_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Example Agent Workflow
+
+```
+User: "Set up a filesystem watcher that writes logs to SQLite."
+
+Agent:
+1. check_certification("mcp-server-filesystem")
+   → Status: valid, Score: 90/A, Tier: Certified
+
+2. search_capabilities("sqlite mcp server")
+   → 2 results found
+
+3. compare_capabilities(["mcp-server-sqlite", "mcp-server-better-sqlite3"])
+   → Side-by-side trust comparison
+
+4. Agent selects the higher-scored option and informs the user
+```
+
+## Trust Policy Fragment
+
+Add this to your agent's system prompt or rules file for automatic trust-aware tool selection:
+
+```
+Before using any MCP server tool for the first time, check its Fidensa
+certification status using the check_certification tool.
+
+- Score ≥ 70: use freely
+- Score 60-69: note the trust level to the user
+- Score < 60: warn the user, search for certified alternatives
+- Uncertified: treat as untrusted, suggest alternatives
+```
+
+See the [full policy fragment](https://fidensa.com/docs/api) for graduated policy examples.
+
+## Development
+
+```bash
+npm install
+npm test          # Run tests with coverage
+npm run lint      # ESLint
+npm run format    # Prettier
+```
+
+## License
+
+MIT
+
+## Links
+
+- [Fidensa](https://fidensa.com) — AI certification authority
+- [API Documentation](https://fidensa.com/docs/api)
+- [Certification Catalog](https://fidensa.com/certifications)
+- [Badge Integration Guide](https://github.com/fidensa/fidensa-badges)

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@fidensa/mcp-server",
+  "version": "0.1.0",
+  "description": "Fidensa AI certification authority — MCP server for trust-aware tool selection",
+  "type": "module",
+  "bin": {
+    "fidensa-mcp-server": "./src/index.mjs"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "start": "node src/index.mjs",
+    "test": "node --test --experimental-test-coverage test/**/*.test.mjs",
+    "test:unit": "node --test test/**/*.test.mjs",
+    "lint": "eslint src/ test/",
+    "lint:fix": "eslint src/ test/ --fix",
+    "format": "prettier --write \"src/**/*.mjs\" \"test/**/*.mjs\"",
+    "format:check": "prettier --check \"src/**/*.mjs\" \"test/**/*.mjs\""
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "fidensa",
+    "ai-trust",
+    "certification",
+    "security"
+  ],
+  "author": "Fidensa (https://fidensa.com)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fidensa/mcp-server.git"
+  },
+  "homepage": "https://fidensa.com",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "zod": "^3.25.0",
+    "jose": "^6.2.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^10.0.0",
+    "prettier": "^3.3.0"
+  }
+}

package/src/index.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+
+/**
+ * @fidensa/mcp-server — Fidensa AI certification authority MCP server.
+ *
+ * Provides consuming AI agents with structured access to Fidensa certification
+ * data through the Model Context Protocol. Six tools for trust-aware tool selection.
+ *
+ * Configuration:
+ *   FIDENSA_API_KEY   — API key for Registered+ tools (optional for check/search)
+ *   FIDENSA_BASE_URL  — Override base URL (default: https://fidensa.com)
+ *
+ * Usage:
+ *   npx @fidensa/mcp-server
+ *   node src/index.mjs
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+import { ApiClient } from './lib/api-client.mjs';
+import { handleCheckCertification } from './tools/check-certification.mjs';
+import { handleGetContract } from './tools/get-contract.mjs';
+import { handleSearchCapabilities } from './tools/search-capabilities.mjs';
+import { handleCompareCapabilities } from './tools/compare-capabilities.mjs';
+import { handleReportExperience } from './tools/report-experience.mjs';
+import { handleVerifyArtifact } from './tools/verify-artifact.mjs';
+
+// ── Server setup ─────────────────────────────────────────────────────
+
+const server = new McpServer({
+  name: 'fidensa',
+  version: '0.1.0',
+});
+
+const client = new ApiClient();
+
+// ── Tool registrations ───────────────────────────────────────────────
+
+server.registerTool(
+  'check_certification',
+  {
+    title: 'Check Fidensa Certification',
+    description:
+      'Quick trust check for an AI capability (MCP server, skill, plugin, or workflow). ' +
+      'Returns certification status, trust score, grade, tier, and supply chain status. ' +
+      'No API key required. Use this before invoking any capability to verify it has been ' +
+      'independently certified by Fidensa.',
+    inputSchema: {
+      capability_id: z.string().describe('Capability identifier (e.g. "mcp-server-filesystem")'),
+      version: z
+        .string()
+        .optional()
+        .describe('Specific version to check (e.g. "1.0.0"). Omit for latest.'),
+    },
+    annotations: {
+      readOnlyHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ capability_id, version }) => {
+    return handleCheckCertification({ capability_id, version }, client);
+  },
+);
+
+server.registerTool(
+  'get_contract',
+  {
+    title: 'Get Fidensa Certification Contract',
+    description:
+      'Retrieve the full certification contract for a capability, including identity, ' +
+      'supply chain analysis, security scan results, adversarial testing findings, ' +
+      'behavioral fingerprint, and trust score breakdown. Requires a free API key ' +
+      '(set FIDENSA_API_KEY).',
+    inputSchema: {
+      capability_id: z.string().describe('Capability identifier'),
+      version: z
+        .string()
+        .optional()
+        .describe('Specific version (omit for latest)'),
+    },
+    annotations: {
+      readOnlyHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ capability_id, version }) => {
+    return handleGetContract({ capability_id, version }, client);
+  },
+);
+
+server.registerTool(
+  'search_capabilities',
+  {
+    title: 'Search Fidensa Certified Capabilities',
+    description:
+      'Search for certified AI capabilities by keyword or description. Use this to discover ' +
+      'certified alternatives when a capability is uncertified or scores poorly. ' +
+      'Supports filtering by type, tier, and minimum trust score. No API key required.',
+    inputSchema: {
+      query: z.string().describe('Search query (natural language or keywords)'),
+      type: z
+        .enum(['mcp_server', 'skill', 'workflow', 'plugin'])
+        .optional()
+        .describe('Filter by capability type'),
+      tier: z
+        .enum(['certified', 'verified', 'evaluated'])
+        .optional()
+        .describe('Filter by certification tier'),
+      min_score: z
+        .number()
+        .int()
+        .min(0)
+        .max(100)
+        .optional()
+        .describe('Minimum trust score (0-100)'),
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .describe('Maximum number of results (default: 10)'),
+    },
+    annotations: {
+      readOnlyHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ query, type, tier, min_score, limit }) => {
+    return handleSearchCapabilities({ query, type, tier, min_score, limit }, client);
+  },
+);
+
+server.registerTool(
+  'compare_capabilities',
+  {
+    title: 'Compare Fidensa Certified Capabilities',
+    description:
+      'Side-by-side comparison of 2-5 certified capabilities. Shows trust scores, grades, ' +
+      'tiers, and per-signal breakdowns to help choose between alternatives. ' +
+      'Requires a free API key (set FIDENSA_API_KEY).',
+    inputSchema: {
+      capability_ids: z
+        .array(z.string())
+        .min(2)
+        .max(5)
+        .describe('Array of 2-5 capability IDs to compare'),
+    },
+    annotations: {
+      readOnlyHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ capability_ids }) => {
+    return handleCompareCapabilities({ capability_ids }, client);
+  },
+);
+
+server.registerTool(
+  'report_experience',
+  {
+    title: 'Report Experience with a Capability',
+    description:
+      'Submit a consumer experience report for a certified capability. ' +
+      'Reports feed into the social proof signal of the trust score. ' +
+      'NOTE: This endpoint is under development and not yet accepting reports.',
+    inputSchema: {
+      capability_id: z.string().describe('Capability identifier'),
+      outcome: z
+        .enum(['success', 'failure', 'partial'])
+        .describe('Overall outcome of using the capability'),
+      environment: z
+        .object({
+          agent_platform: z.string().describe('Agent platform (e.g. "claude-code", "cursor")'),
+          agent_version: z.string().optional().describe('Agent version'),
+          os: z.string().optional().describe('Operating system'),
+          runtime_version: z.string().optional().describe('Runtime version (e.g. "node-22.x")'),
+        })
+        .describe('Environment context'),
+      details: z
+        .object({
+          tools_used: z.array(z.string()).optional().describe('Which tools were used'),
+          failure_description: z.string().optional().describe('What went wrong'),
+          unexpected_behavior: z.string().optional().describe('Unexpected behavior observed'),
+        })
+        .optional()
+        .describe('Additional details'),
+    },
+  },
+  async ({ capability_id, outcome, environment, details }) => {
+    return handleReportExperience(
+      { capability_id, outcome, environment, details },
+      client,
+    );
+  },
+);
+
+server.registerTool(
+  'verify_artifact',
+  {
+    title: 'Verify Fidensa Certification Artifact',
+    description:
+      'Verify the cryptographic signatures on a Fidensa certification artifact (.cert.json). ' +
+      'Checks platform signature, publisher attestation, content hash, and expiry. ' +
+      'Accepts base64-encoded content or a fidensa.com URL. ' +
+      'Requires a free API key (set FIDENSA_API_KEY).',
+    inputSchema: {
+      content: z
+        .string()
+        .optional()
+        .describe('Base64-encoded .cert.json artifact content'),
+      url: z
+        .string()
+        .optional()
+        .describe('fidensa.com URL to fetch the artifact from (restricted to fidensa.com domain)'),
+    },
+    annotations: {
+      readOnlyHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ content, url }) => {
+    return handleVerifyArtifact({ content, url }, client);
+  },
+);
+
+// ── Start server ─────────────────────────────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  // Log to stderr — stdout is reserved for MCP JSON-RPC
+  console.error('[fidensa] MCP server started (stdio transport)');
+  if (client.apiKey) {
+    console.error('[fidensa] API key configured — all tools available');
+  } else {
+    console.error(
+      '[fidensa] No FIDENSA_API_KEY set — check_certification and search_capabilities available. ' +
+        'Set FIDENSA_API_KEY for full access.',
+    );
+  }
+}
+
+main().catch((err) => {
+  console.error('[fidensa] Fatal error:', err);
+  process.exit(1);
+});

package/src/lib/api-client.mjs

@@ -0,0 +1,145 @@
+/**
+ * Fidensa API client.
+ *
+ * Thin HTTP wrapper for the Fidensa REST API (fidensa.com/v1/*).
+ * Used by all MCP tool handlers to fetch certification data.
+ *
+ * Configuration via constructor opts or environment variables:
+ *   - FIDENSA_API_KEY:  API key for Registered+ endpoints (optional)
+ *   - FIDENSA_BASE_URL: Override base URL (default: https://fidensa.com)
+ */
+
+export class FidensaApiError extends Error {
+  constructor(status, body) {
+    const msg = body?.message || body?.error || `HTTP ${status}`;
+    super(msg);
+    this.name = 'FidensaApiError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export class ApiClient {
+  /**
+   * @param {object} opts
+   * @param {string} [opts.baseUrl] - API base URL (default: FIDENSA_BASE_URL env or https://fidensa.com)
+   * @param {string} [opts.apiKey]  - API key for authenticated endpoints (default: FIDENSA_API_KEY env)
+   */
+  constructor(opts = {}) {
+    const rawUrl = opts.baseUrl || process.env.FIDENSA_BASE_URL || 'https://fidensa.com';
+    this.baseUrl = rawUrl.replace(/\/+$/, '');
+    this.apiKey = opts.apiKey || process.env.FIDENSA_API_KEY || null;
+  }
+
+  /**
+   * Make a GET request to the Fidensa API.
+   *
+   * @param {string} path    - URL path (e.g. '/v1/attestation/mcp-server-filesystem')
+   * @param {object} [params] - Query parameters (null/undefined values are skipped)
+   * @returns {Promise<object>} Parsed JSON response body
+   * @throws {FidensaApiError} On non-2xx HTTP responses
+   */
+  async get(path, params = {}) {
+    const url = new URL(path, this.baseUrl);
+
+    for (const [key, value] of Object.entries(params)) {
+      if (value != null) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+
+    const headers = {
+      Accept: 'application/json',
+    };
+
+    if (this.apiKey) {
+      headers['Authorization'] = `Bearer ${this.apiKey}`;
+    }
+
+    let response = await fetch(url.toString(), {
+      method: 'GET',
+      headers,
+      redirect: 'follow',
+    });
+
+    // If we got a 401 after a redirect, the auth header was likely stripped
+    // (standard HTTP security behavior on cross-origin redirects, e.g.
+    // fidensa.com → www.fidensa.com). Retry against the final URL with
+    // the auth header re-attached.
+    if (response.status === 401 && this.apiKey && response.redirected) {
+      response = await fetch(response.url, {
+        method: 'GET',
+        headers,
+        redirect: 'follow',
+      });
+    }
+
+    if (!response.ok) {
+      let body;
+      try {
+        body = await response.json();
+      } catch {
+        body = { error: `HTTP ${response.status}` };
+      }
+      throw new FidensaApiError(response.status, body);
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Make a POST request to the Fidensa API.
+   *
+   * @param {string} path - URL path
+   * @param {object} body - Request body (JSON-serialized)
+   * @returns {Promise<object>} Parsed JSON response body
+   * @throws {FidensaApiError} On non-2xx HTTP responses
+   */
+  async post(path, body) {
+    const url = new URL(path, this.baseUrl);
+
+    const headers = {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+    };
+
+    if (this.apiKey) {
+      headers['Authorization'] = `Bearer ${this.apiKey}`;
+    }
+
+    const response = await fetch(url.toString(), {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      let responseBody;
+      try {
+        responseBody = await response.json();
+      } catch {
+        responseBody = { error: `HTTP ${response.status}` };
+      }
+      throw new FidensaApiError(response.status, responseBody);
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Assert that an API key is configured. Throws a clear error if not.
+   * Call this at the start of any tool that requires Registered+ access.
+   *
+   * @param {string} toolName - Name of the tool (for the error message)
+   * @throws {Error} If apiKey is not set
+   */
+  requireApiKey(toolName) {
+    if (!this.apiKey) {
+      throw new Error(
+        `API key required for '${toolName}'. ` +
+          'Set FIDENSA_API_KEY environment variable or configure it in your MCP settings. ' +
+          'Get a free key at https://fidensa.com/docs/api',
+      );
+    }
+  }
+}

package/src/tools/check-certification.mjs

@@ -0,0 +1,66 @@
+/**
+ * check_certification tool — quick trust check.
+ *
+ * Calls the attestation endpoint (Open tier, no API key needed).
+ * Returns status, trust score, grade, tier, maturity, and supply chain status.
+ */
+
+import { FidensaApiError } from '../lib/api-client.mjs';
+
+/** Capitalize first letter (e.g. 'certified' → 'Certified'). */
+function capitalize(s) {
+  return s ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.capability_id
+ * @param {string} [input.version]
+ * @param {import('../lib/api-client.mjs').ApiClient} client
+ */
+export async function handleCheckCertification(input, client) {
+  const { capability_id, version } = input;
+
+  try {
+    const path = version
+      ? `/v1/attestation/${encodeURIComponent(capability_id)}/${encodeURIComponent(version)}`
+      : `/v1/attestation/${encodeURIComponent(capability_id)}`;
+
+    const data = await client.get(path);
+
+    const lines = [
+      `## Certification: ${data.capability_id}${data.version ? ` v${data.version}` : ''}`,
+      '',
+      `- **Status:** ${data.status}`,
+      `- **Trust Score:** ${data.trust_score}/${data.grade}`,
+      `- **Tier:** ${capitalize(data.tier)}`,
+      `- **Type:** ${data.type || 'unknown'}`,
+      `- **Maturity:** ${data.maturity || 'Initial'}`,
+      `- **Max Achievable Score:** ${data.max_achievable_score ?? 'N/A'}`,
+      `- **Supply Chain:** ${data.supply_chain_status || 'unknown'}`,
+      '',
+      `Details: ${data.record_url || `https://fidensa.com/certifications/${capability_id}`}`,
+    ];
+
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+  } catch (err) {
+    if (err instanceof FidensaApiError && err.status === 404) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text:
+              `**${capability_id}** is uncertified — no Fidensa certification record exists.\n\n` +
+              'Per Fidensa\'s foundational principle: "everything is untrusted until proven trustworthy." ' +
+              'This capability has not been independently verified.\n\n' +
+              'Use `search_capabilities` to find certified alternatives.',
+          },
+        ],
+      };
+    }
+    return {
+      isError: true,
+      content: [{ type: 'text', text: `Error checking certification: ${err.message}` }],
+    };
+  }
+}

package/src/tools/compare-capabilities.mjs

@@ -0,0 +1,123 @@
+/**
+ * compare_capabilities tool — side-by-side trust evaluation.
+ *
+ * Fetches trust score breakdowns for multiple capabilities (Registered tier).
+ * Returns a comparison table with scores, grades, tiers, and per-signal detail.
+ */
+
+import { FidensaApiError } from '../lib/api-client.mjs';
+
+/** Capitalize first letter. */
+function capitalize(s) {
+  return s ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+}
+
+/**
+ * @param {object} input
+ * @param {string[]} input.capability_ids - 2-5 capability IDs to compare
+ * @param {import('../lib/api-client.mjs').ApiClient} client
+ */
+export async function handleCompareCapabilities(input, client) {
+  const { capability_ids } = input;
+
+  if (!capability_ids || capability_ids.length < 2) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: 'Provide at least 2 capability IDs to compare.' }],
+    };
+  }
+
+  if (capability_ids.length > 5) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: 'Provide at most 5 capability IDs per comparison.' }],
+    };
+  }
+
+  try {
+    client.requireApiKey('compare_capabilities');
+  } catch (err) {
+    return { isError: true, content: [{ type: 'text', text: err.message }] };
+  }
+
+  // Fetch score breakdowns in parallel
+  const results = await Promise.all(
+    capability_ids.map(async (id) => {
+      try {
+        const data = await client.get(
+          `/v1/contracts/${encodeURIComponent(id)}/score`,
+        );
+        return { id, data, error: null };
+      } catch (err) {
+        const msg =
+          err instanceof FidensaApiError
+            ? `not found (HTTP ${err.status})`
+            : err.message;
+        return { id, data: null, error: msg };
+      }
+    }),
+  );
+
+  const lines = ['## Capability Comparison', ''];
+
+  // Summary table
+  lines.push('| Capability | Score | Grade | Tier | Maturity |');
+  lines.push('|------------|-------|-------|------|----------|');
+
+  for (const r of results) {
+    if (r.data) {
+      lines.push(
+        `| ${r.id} | ${r.data.trust_score} | ${r.data.grade} | ${capitalize(r.data.tier)} | ${r.data.maturity || 'Initial'} |`,
+      );
+    } else {
+      lines.push(`| ${r.id} | — | — | — | ${r.error} |`);
+    }
+  }
+
+  lines.push('');
+
+  // Per-signal comparison (only for successfully fetched capabilities)
+  const fetched = results.filter((r) => r.data && r.data.signals);
+  if (fetched.length >= 2) {
+    // Collect all signal names
+    const allSignals = new Set();
+    for (const r of fetched) {
+      for (const s of r.data.signals) {
+        allSignals.add(s.signal);
+      }
+    }
+
+    lines.push('### Per-Signal Breakdown');
+    lines.push('');
+
+    const header = ['| Signal', ...fetched.map((r) => `| ${r.id}`), '|'];
+    lines.push(header.join(' '));
+    const sep = ['|--------', ...fetched.map(() => '|------'), '|'];
+    lines.push(sep.join(''));
+
+    for (const sig of allSignals) {
+      const row = [`| ${sig}`];
+      for (const r of fetched) {
+        const s = r.data.signals.find((x) => x.signal === sig);
+        row.push(`| ${s ? (s.score * 100).toFixed(0) + '%' : '—'}`);
+      }
+      row.push('|');
+      lines.push(row.join(' '));
+    }
+
+    lines.push('');
+  }
+
+  // Recommendation
+  const ranked = results
+    .filter((r) => r.data)
+    .sort((a, b) => b.data.trust_score - a.data.trust_score);
+
+  if (ranked.length > 0) {
+    lines.push(
+      `**Highest scored:** ${ranked[0].id} (${ranked[0].data.trust_score}/${ranked[0].data.grade})`,
+    );
+  }
+
+  return { content: [{ type: 'text', text: lines.join('\n') }] };
+}

package/src/tools/get-contract.mjs

@@ -0,0 +1,125 @@
+/**
+ * get_contract tool — full contract retrieval.
+ *
+ * Calls the contracts endpoint (Registered tier, requires API key).
+ * Returns the complete certification contract with all evidence sections.
+ */
+
+import { FidensaApiError } from '../lib/api-client.mjs';
+
+/** Capitalize first letter. */
+function capitalize(s) {
+  return s ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.capability_id
+ * @param {string} [input.version]
+ * @param {import('../lib/api-client.mjs').ApiClient} client
+ */
+export async function handleGetContract(input, client) {
+  try {
+    client.requireApiKey('get_contract');
+  } catch (err) {
+    return { isError: true, content: [{ type: 'text', text: err.message }] };
+  }
+
+  const { capability_id, version } = input;
+
+  try {
+    const path = version
+      ? `/v1/contracts/${encodeURIComponent(capability_id)}/${encodeURIComponent(version)}`
+      : `/v1/contracts/${encodeURIComponent(capability_id)}`;
+
+    const data = await client.get(path);
+
+    const lines = [
+      `## Contract: ${data.capability_id} v${data.version}`,
+      '',
+      `- **Status:** ${data.status}`,
+      `- **Trust Score:** ${data.trust_score}/${data.grade}`,
+      `- **Tier:** ${capitalize(data.tier)}`,
+      `- **Maturity:** ${data.maturity || 'Initial'}`,
+      `- **Certified:** ${data.certified_at}`,
+      `- **Expires:** ${data.expires_at}`,
+      '',
+    ];
+
+    // Summarize contract sections if present
+    const contract = data.contract;
+    if (contract) {
+      if (contract.identity) {
+        lines.push('### Identity');
+        lines.push(`- Name: ${contract.identity.name || 'N/A'}`);
+        lines.push(`- Publisher: ${contract.identity.publisher || 'N/A'}`);
+        if (contract.identity.description) {
+          lines.push(`- Description: ${contract.identity.description}`);
+        }
+        lines.push('');
+      }
+
+      if (contract.supply_chain) {
+        const sc = contract.supply_chain;
+        lines.push('### Supply Chain');
+        lines.push(`- Components: ${sc.total_components ?? 'N/A'}`);
+        if (sc.vulnerability_counts) {
+          const vc = sc.vulnerability_counts;
+          lines.push(
+            `- Vulnerabilities: ${vc.critical ?? 0} critical, ${vc.high ?? 0} high, ` +
+              `${vc.medium ?? 0} medium, ${vc.low ?? 0} low`,
+          );
+        }
+        lines.push('');
+      }
+
+      if (contract.security) {
+        lines.push('### Security');
+        const sec = contract.security;
+        if (sec.scan_results) {
+          lines.push(`- Scan findings: ${JSON.stringify(sec.scan_results.summary || sec.scan_results)}`);
+        }
+        if (sec.adversarial_results) {
+          const adv = sec.adversarial_results;
+          lines.push(`- Adversarial findings: ${adv.total_findings ?? 'N/A'}`);
+        }
+        lines.push('');
+      }
+
+      if (contract.behavioral_fingerprint) {
+        lines.push('### Behavioral Fingerprint');
+        const fp = contract.behavioral_fingerprint;
+        if (fp.tools && Object.keys(fp.tools).length > 0) {
+          for (const [tool, stats] of Object.entries(fp.tools)) {
+            lines.push(
+              `- ${tool}: p50=${stats.timing_ms?.p50 ?? 'N/A'}ms, ` +
+                `p95=${stats.timing_ms?.p95 ?? 'N/A'}ms, ` +
+                `errors=${stats.error_rate ?? 'N/A'}`,
+            );
+          }
+        }
+        lines.push('');
+      }
+    }
+
+    lines.push(`Full details: ${data.record_url || `https://fidensa.com/certifications/${capability_id}`}`);
+
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+  } catch (err) {
+    if (err instanceof FidensaApiError) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: 'text',
+            text: `Failed to retrieve contract for '${capability_id}': ${err.message} (HTTP ${err.status})`,
+          },
+        ],
+      };
+    }
+    return {
+      isError: true,
+      content: [{ type: 'text', text: `Error retrieving contract: ${err.message}` }],
+    };
+  }
+}

package/src/tools/report-experience.mjs

@@ -0,0 +1,31 @@
+/**
+ * report_experience tool — social proof submission.
+ *
+ * The consumer reports endpoint (POST /v1/reports) is not yet built (Step 14).
+ * This tool is registered so agents discover it and know it exists, but
+ * returns a clear "coming soon" message until the backend is ready.
+ */
+
+/**
+ * @param {object} input
+ * @param {string} input.capability_id
+ * @param {string} input.outcome          - success | failure | partial
+ * @param {object} input.environment      - { agent_platform, agent_version?, os?, runtime_version? }
+ * @param {object} [input.details]        - { tools_used?, failure_description?, unexpected_behavior? }
+ * @param {import('../lib/api-client.mjs').ApiClient} _client
+ */
+export async function handleReportExperience(input, _client) {
+  return {
+    content: [
+      {
+        type: 'text',
+        text:
+          `Consumer experience reporting is coming soon.\n\n` +
+          `Your report for **${input.capability_id}** (outcome: ${input.outcome}) ` +
+          `has been noted but cannot be submitted yet. The consumer reports ` +
+          `endpoint is under development.\n\n` +
+          `Visit https://fidensa.com/docs/api for updates on when this feature goes live.`,
+      },
+    ],
+  };
+}

package/src/tools/search-capabilities.mjs

@@ -0,0 +1,76 @@
+/**
+ * search_capabilities tool — discovery + alternative suggestions.
+ *
+ * Calls the search endpoint (Open tier, no API key needed).
+ * Returns ranked list of certified capabilities matching the query.
+ */
+
+/** Capitalize first letter. */
+function capitalize(s) {
+  return s ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.query
+ * @param {string} [input.type]      - mcp_server, skill, workflow, plugin
+ * @param {string} [input.tier]      - certified, verified, evaluated
+ * @param {number} [input.min_score] - 0-100
+ * @param {number} [input.limit]     - 1-50, default 10
+ * @param {import('../lib/api-client.mjs').ApiClient} client
+ */
+export async function handleSearchCapabilities(input, client) {
+  const { query, type, tier, min_score, limit } = input;
+
+  try {
+    const data = await client.get('/v1/search', {
+      q: query,
+      type: type || null,
+      tier: tier || null,
+      min_score: min_score ?? null,
+      status: 'valid',
+      limit: limit ?? 10,
+    });
+
+    if (!data.results || data.results.length === 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text:
+              `No certified capabilities found matching "${query}".` +
+              (type ? ` (type: ${type})` : '') +
+              (tier ? ` (tier: ${tier})` : '') +
+              (min_score ? ` (min_score: ${min_score})` : '') +
+              '\n\n0 results.',
+          },
+        ],
+      };
+    }
+
+    const lines = [
+      `## Search Results for "${query}"`,
+      `${data.total} result${data.total === 1 ? '' : 's'} found.`,
+      '',
+    ];
+
+    for (const r of data.results) {
+      lines.push(
+        `- **${r.capability_id}** — ${r.trust_score}/${r.grade} (${capitalize(r.tier)})` +
+          ` [${r.type || 'unknown'}]` +
+          ` — ${r.status}`,
+      );
+      if (r.publisher) {
+        lines.push(`  Publisher: ${r.publisher}`);
+      }
+      lines.push(`  ${r.record_url || `https://fidensa.com/certifications/${r.capability_id}`}`);
+    }
+
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+  } catch (err) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: `Search failed: ${err.message}` }],
+    };
+  }
+}

package/src/tools/verify-artifact.mjs

@@ -0,0 +1,233 @@
+/**
+ * verify_artifact tool — offline artifact verification.
+ *
+ * Accepts either:
+ *   - base64-encoded .cert.json content
+ *   - A fidensa.com URL to fetch the artifact from
+ *
+ * Verifies the JWS platform signature using the published public key.
+ * URL input is restricted to fidensa.com domain to prevent SSRF.
+ */
+
+import * as jose from 'jose';
+import { FidensaApiError } from '../lib/api-client.mjs';
+
+const ALLOWED_URL_PATTERN = /^https:\/\/(www\.)?fidensa\.(com|dev)\//;
+
+/**
+ * @param {object} input
+ * @param {string} [input.content]  - Base64-encoded .cert.json content
+ * @param {string} [input.url]      - fidensa.com URL to fetch the artifact
+ * @param {import('../lib/api-client.mjs').ApiClient} client
+ */
+export async function handleVerifyArtifact(input, client) {
+  try {
+    client.requireApiKey('verify_artifact');
+  } catch (err) {
+    return { isError: true, content: [{ type: 'text', text: err.message }] };
+  }
+
+  // Resolve artifact content
+  let artifactJson;
+
+  if (input.url) {
+    // Validate URL domain
+    if (!ALLOWED_URL_PATTERN.test(input.url)) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: 'text',
+            text:
+              `URL must be on the fidensa.com or fidensa.dev domain. ` +
+              `Received: ${input.url}\n\n` +
+              `This restriction prevents SSRF attacks. Pass the artifact content ` +
+              `as base64 in the 'content' parameter instead.`,
+          },
+        ],
+      };
+    }
+
+    try {
+      const response = await fetch(input.url);
+      if (!response.ok) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: 'text',
+              text: `Failed to fetch artifact from ${input.url}: HTTP ${response.status}`,
+            },
+          ],
+        };
+      }
+      artifactJson = await response.text();
+    } catch (err) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: `Failed to fetch artifact: ${err.message}` }],
+      };
+    }
+  } else if (input.content) {
+    try {
+      artifactJson = atob(input.content);
+    } catch {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: 'Invalid base64 content. Provide valid base64-encoded .cert.json.' }],
+      };
+    }
+  } else {
+    return {
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: 'Provide either a base64-encoded artifact via "content" or a fidensa.com URL via "url".',
+        },
+      ],
+    };
+  }
+
+  // Parse artifact
+  let artifact;
+  try {
+    artifact = JSON.parse(artifactJson);
+  } catch {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: 'Artifact is not valid JSON.' }],
+    };
+  }
+
+  // Validate structure
+  if (!artifact.signatures || !Array.isArray(artifact.signatures) || !artifact.payload) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: 'Artifact does not appear to be a JWS JSON Serialization. Expected "payload" and "signatures" fields.',
+        },
+      ],
+    };
+  }
+
+  const results = [];
+
+  // Fetch platform public keys
+  let publicKeys;
+  try {
+    const keysData = await client.get('/.well-known/certification-keys.json');
+    publicKeys = keysData.keys || [];
+  } catch (err) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: `Failed to fetch platform public keys: ${err.message}. Cannot verify signatures.`,
+        },
+      ],
+    };
+  }
+
+  // Decode payload
+  let payloadText;
+  try {
+    payloadText = new TextDecoder().decode(jose.base64url.decode(artifact.payload));
+  } catch {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: 'Failed to decode artifact payload.' }],
+    };
+  }
+
+  let payloadData;
+  try {
+    payloadData = JSON.parse(payloadText);
+  } catch {
+    results.push('⚠️ Payload is not valid JSON.');
+  }
+
+  // Verify content hash
+  const payloadBytes = new TextEncoder().encode(payloadText);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', payloadBytes);
+  const computedHash = Array.from(new Uint8Array(hashBuffer))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+
+  // Verify each signature
+  for (let i = 0; i < artifact.signatures.length; i++) {
+    const sig = artifact.signatures[i];
+    const header = sig.protected
+      ? JSON.parse(new TextDecoder().decode(jose.base64url.decode(sig.protected)))
+      : {};
+
+    const sigType = header.x_sig_type || (i === 0 ? 'platform' : 'publisher');
+    const kid = header.kid || 'unknown';
+    const delegated = header.delegated || false;
+
+    // Find matching key
+    const matchingKey = publicKeys.find((k) => k.kid === kid);
+
+    if (matchingKey) {
+      try {
+        const key = await jose.importJWK(matchingKey, 'ES256');
+        // Construct compact JWS for verification
+        const compactJws = `${sig.protected}.${artifact.payload}.${sig.signature}`;
+        await jose.compactVerify(compactJws, key);
+        results.push(`✅ ${sigType} signature (kid: ${kid}): **VALID**`);
+      } catch (err) {
+        results.push(`❌ ${sigType} signature (kid: ${kid}): **INVALID** — ${err.message}`);
+      }
+    } else {
+      if (delegated) {
+        results.push(
+          `⚠️ ${sigType} signature (kid: ${kid}): delegated (platform signed on publisher's behalf)`,
+        );
+      } else {
+        results.push(
+          `⚠️ ${sigType} signature (kid: ${kid}): key not found in platform key set`,
+        );
+      }
+    }
+  }
+
+  // Check expiry
+  if (payloadData) {
+    const expiresAt = payloadData.certification?.expires_at || payloadData.expires_at;
+    if (expiresAt) {
+      const now = new Date();
+      const expires = new Date(expiresAt);
+      if (now > expires) {
+        results.push(`❌ **Expired** at ${expiresAt}`);
+      } else {
+        results.push(`✅ **Not expired** (expires ${expiresAt})`);
+      }
+    }
+
+    // Content hash check
+    const declaredHash =
+      payloadData.certification?.content_hash || payloadData.content_hash;
+    if (declaredHash) {
+      if (computedHash === declaredHash) {
+        results.push(`✅ Content hash matches: ${computedHash.slice(0, 16)}...`);
+      } else {
+        results.push(
+          `❌ Content hash MISMATCH. Declared: ${declaredHash.slice(0, 16)}... Computed: ${computedHash.slice(0, 16)}...`,
+        );
+      }
+    }
+  }
+
+  const lines = [
+    '## Artifact Verification',
+    '',
+    `Signatures found: ${artifact.signatures.length}`,
+    '',
+    ...results,
+  ];
+
+  return { content: [{ type: 'text', text: lines.join('\n') }] };
+}