mcp-server-mcpindex 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to `mcp-server-mcpindex` are recorded here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-05-28
+
+### Added
+
+- **`check_tool_trust(server_id, tool_name)` MCP tool.** Pre-invocation advisory trust verdict for a specific tool on an MCP server. Returns the v1 verdict contract (directive, status, dimensions, freshness, honest_limits). Fail-CLOSED: returns `UNVERIFIED` + `status: ERROR` when the upstream endpoint is unreachable, returns 404, times out, or returns malformed data. Never coerces to ALLOW.
+- **`assess_server(server_id)` MCP tool.** Aggregated pre-flight verdict across all tools on a server. Same verdict shape as `check_tool_trust`. Use for "is THIS server worth integrating?" decisions.
+- **`src/trust.mjs` library export.** The trust client is exported as a plain ES module (`checkToolTrust`, `assessServer`, `VERDICT_CONTRACT_VERSION`, `V1_HONEST_LIMITS`) so non-MCP consumers can call it directly.
+- **Verdict contract version pin.** `verdict_contract_version: "1.0.0"` is included on every verdict response.
+- **v1 honest limits floor.** Every verdict ships with at least `conformance_monitored_not_enforced`, `calibrated_false_v1`, and `advisory_deployment` in `honest_limits`. Upstream cannot remove the floor.
+- **README integration guide.** Worked example of wrapping `check_tool_trust` as a pre-invocation gate (LangChain / DSPy / Mastra / Composio / raw LLM-tool-call style), including the fail-CLOSED handling for UNVERIFIED.
+- **Test suite.** `node --test test/trust.test.mjs`. Covers the fail-CLOSED invariant (unreachable, 404, timeout, malformed payload, missing args), the happy-path verdict shape, dimension normalization, unknown-directive downgrade, and the honest_limits floor.
+- **npm scripts.** `npm run build` (syntax check) and `npm test`.
+
+### Changed
+
+- Package description updated to mention the advisory trust verdicts.
+- Embedded server version bumped to `0.2.0`.
+
+### Notes for integrators
+
+`check_tool_trust` is **v1 advisory**. Conformance is monitored, not enforced. The verdict is a recommendation; the agent (or the human reviewing the agent) is the decision-maker. Never treat UNVERIFIED as ALLOW.
+
+## [0.1.0] - 2026-04-30
+
+### Added
+
+- Initial release. Tools: `recommend_mcp_for_task`, `search_mcp_servers`, `get_install_command`, `compare_servers`.
+- Stdio MCP transport via `@modelcontextprotocol/sdk`.
+- Backend defaults to `https://mcpindex.ai`; override with `MCPINDEX_API_BASE`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bhartis LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# mcp-server-mcpindex
+
+> An MCP server for finding MCP servers, plus advisory trust verdicts agent frameworks can call before invoking a tool.
+
+A drop-in MCP server that lets your agent discover, compare, install, and pre-flight other MCP servers from inside the agent loop. Backed by [mcpindex.ai](https://mcpindex.ai) - the agent-native index of 3,500+ MCP servers indexed daily from the official registry.
+
+## Install
+
+```bash
+npm install -g mcp-server-mcpindex
+```
+
+## Use it from Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcpindex": {
+      "command": "npx",
+      "args": ["-y", "mcp-server-mcpindex"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Then ask:
+
+> "Find me an MCP server that can read PDFs and write the contents to S3."
+
+Claude calls `recommend_mcp_for_task` and returns the top 3 ranked servers with install commands.
+
+## Use it from Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcpindex": {
+      "command": "npx",
+      "args": ["-y", "mcp-server-mcpindex"]
+    }
+  }
+}
+```
+
+## Use it from Cline
+
+Add to your Cline settings:
+
+```bash
+npx -y mcp-server-mcpindex
+```
+
+## Tools exposed
+
+| Tool | What it does |
+| --- | --- |
+| `recommend_mcp_for_task` | Pass a natural-language task. Returns top 3 servers with reasoning, install commands, quality scores. |
+| `search_mcp_servers` | Keyword + semantic search across the full registry. Optional category filter. |
+| `get_install_command` | Get the exact install JSON for a server + a target client (Claude Desktop, Cursor, Cline, Zed). |
+| `compare_servers` | Side-by-side comparison of 2-5 servers - quality scores, install paths, env vars. |
+| `check_tool_trust` | Pre-invocation advisory verdict for a specific tool on a server. Fail-CLOSED: returns UNVERIFIED when no verdict on file. |
+| `assess_server` | Aggregated pre-flight verdict across all tools on a server. Same shape as `check_tool_trust`. |
+
+## Agent-framework integration: pre-invocation trust gate
+
+`check_tool_trust` is the integration surface that lets agent frameworks (Composio, Mastra, LangChain, DSPy, raw LLM-tool-call loops) ask "is this tool safe to invoke right now?" before dispatching the call.
+
+### Verdict contract (v1)
+
+```jsonc
+{
+  "directive": "ALLOW" | "DENY" | "REVIEW" | "UNVERIFIED",
+  "status":    "EVALUATED" | "STALE" | "ERROR",
+  "dimensions": [
+    { "id": "tool_safety", "verdict": "PASS", "severity": "INFO" }
+  ],
+  "expires_at": "2026-06-30T00:00:00Z",
+  "honest_limits": [
+    "conformance_monitored_not_enforced",
+    "calibrated_false_v1",
+    "advisory_deployment"
+  ],
+  "verdict_contract_version": "1.0.0",
+  "server_id": "github",
+  "tool_name": "create_pull_request",
+  "source_url": "https://mcpindex.ai/api/v1/trust/tool/github/create_pull_request",
+  "fetched_at": "2026-05-28T18:42:11.118Z"
+}
+```
+
+The free-tier verdict ships directives + dimensions + freshness. Evidence quotes, LLM rationale, and chain history are paid-tier surfaces and intentionally omitted here.
+
+### Honest limits (pin these to your gate UI)
+
+Every v1 verdict ships with these three caveats, and your gate SHOULD surface them on every dispatch decision:
+
+1. `conformance_monitored_not_enforced` - publishers self-declare; mcpindex monitors drift but does not block at the network layer.
+2. `calibrated_false_v1` - dimension severities are not yet calibrated against real-world incident data.
+3. `advisory_deployment` - the verdict is advisory; the agent (or human reviewing the agent) is the decision-maker.
+
+History anchoring: OTS Bitcoin-anchored history; Bitcoin-finalized at N=6 confirmations (~1 hr); pending in ~10 min. Sub-window precision asserted, not proven.
+
+### Integration pattern (LangChain-style, direct LLM-tool-call convention)
+
+```js
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+const mcpindex = new Client({ name: 'gate', version: '1.0.0' }, { capabilities: {} });
+await mcpindex.connect(new StdioClientTransport({
+  command: 'npx', args: ['-y', 'mcp-server-mcpindex'],
+}));
+
+// gateToolCall wraps any agent tool dispatch. Plug it in front of
+// the LangChain / DSPy / Mastra / Composio tool-call hook.
+async function gateToolCall({ serverId, toolName, invoke, askHuman }) {
+  const res = await mcpindex.callTool({
+    name: 'check_tool_trust',
+    arguments: { server_id: serverId, tool_name: toolName },
+  });
+  const verdict = JSON.parse(res.content[0].text);
+
+  // Pin the v1 caveats in the audit log no matter what.
+  audit.log({ verdict, caveats: verdict.honest_limits });
+
+  switch (verdict.directive) {
+    case 'ALLOW':
+      return invoke();
+
+    case 'DENY':
+      throw new Error(
+        `mcpindex denied ${serverId}/${toolName}: ${JSON.stringify(verdict.dimensions)}`,
+      );
+
+    case 'REVIEW':
+      // Fail-CLOSED to human. Do NOT auto-execute on REVIEW.
+      return askHuman({ verdict, action: `${serverId}/${toolName}` });
+
+    case 'UNVERIFIED':
+      // No verdict on file (or upstream unreachable). Fail-CLOSED.
+      // Recommend human review. Do NOT fail-open to invoke().
+      return askHuman({
+        verdict,
+        action: `${serverId}/${toolName}`,
+        note: 'No trust verdict on file. Human review required before first use.',
+      });
+
+    default:
+      // Unknown directive. Fail-CLOSED.
+      return askHuman({ verdict, action: `${serverId}/${toolName}` });
+  }
+}
+```
+
+### The load-bearing rule: never fail-open
+
+If the verdict endpoint is unreachable, returns 404, times out, or returns malformed JSON, `check_tool_trust` returns `directive: "UNVERIFIED"` + `status: "ERROR"`. It never silently coerces to ALLOW. Your gate code SHOULD treat UNVERIFIED as "human review required", never as "looks fine, ship it."
+
+This is tested. See `test/trust.test.mjs`.
+
+### Using the library directly (without MCP)
+
+The trust client is also exported as a plain ES module:
+
+```js
+import { checkToolTrust, assessServer } from 'mcp-server-mcpindex/src/trust.mjs';
+
+const verdict = await checkToolTrust({
+  serverId: 'github',
+  toolName: 'create_pull_request',
+});
+
+if (verdict.directive !== 'ALLOW') {
+  // Hand to a human, log, or block.
+}
+```
+
+## Backend
+
+By default, calls go to `https://mcpindex.ai`. Override with `MCPINDEX_API_BASE=...` if you self-host.
+
+The free tier is rate-limited to 60 req/min/IP. Paid keys are coming for higher throughput and the full evidence-bearing verdict (evidence quotes, LLM rationale, chain history).
+
+## License
+
+MIT.
+
+## Project
+
+- Website: [mcpindex.ai](https://mcpindex.ai)
+- Methodology: [mcpindex.ai/methodology](https://mcpindex.ai/methodology)
+- Source: [github.com/mcpindex-ai](https://github.com/mcpindex-ai)
+
+Unofficial. Not affiliated with Anthropic.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "mcp-server-mcpindex",
+  "version": "0.2.0",
+  "description": "An MCP server for finding MCP servers, plus advisory trust verdicts (check_tool_trust, assess_server) for agent frameworks. Drop-in for Claude Desktop, Cursor, Cline, Zed.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "cursor",
+    "agent",
+    "discovery",
+    "trust",
+    "tool-safety",
+    "governance"
+  ],
+  "homepage": "https://mcpindex.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mcpindex-ai/mcp-server-mcpindex"
+  },
+  "bugs": {
+    "url": "https://github.com/mcpindex-ai/mcp-server-mcpindex/issues"
+  },
+  "author": "Bhartis LLC <hello@mcpindex.ai>",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/index.mjs",
+  "bin": {
+    "mcp-server-mcpindex": "src/index.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node --check src/index.mjs && node --check src/trust.mjs",
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}

package/src/index.mjs

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+// mcp-server-mcpindex - an MCP server for finding MCP servers.
+// Backend: api.mcpindex.ai (versioned, free tier - no key needed for v0).
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+export { checkToolTrust, assessServer, VERDICT_CONTRACT_VERSION, V1_HONEST_LIMITS } from './trust.mjs';
+
+const API_BASE = process.env.MCPINDEX_API_BASE ?? 'https://mcpindex.ai';
+const PKG_VERSION = '0.2.0';
+
+const server = new Server(
+  { name: 'mcp-server-mcpindex', version: PKG_VERSION },
+  { capabilities: { tools: {} } },
+);
+
+const TOOLS = [
+  {
+    name: 'recommend_mcp_for_task',
+    description:
+      'Recommend the best MCP servers for a natural-language task. Returns top 3 ranked picks with reasoning, install commands, and quality scores. Use this when the user asks for the right MCP server for a task they want to do.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task: {
+          type: 'string',
+          description:
+            'Natural-language description of the task, e.g. "read PDFs and write to S3" or "search GitHub and open a PR".',
+        },
+      },
+      required: ['task'],
+    },
+  },
+  {
+    name: 'search_mcp_servers',
+    description:
+      'Keyword + semantic search across the full MCP server registry. Use when the user knows what tool category they want but not which server.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search query.' },
+        category: {
+          type: 'string',
+          description:
+            'Optional category filter (e.g. database, browser, github, productivity).',
+        },
+        limit: {
+          type: 'number',
+          description: 'Max results (default 10, max 50).',
+          default: 10,
+        },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'get_install_command',
+    description:
+      'Get the exact install command for a given MCP server and client. Returns a JSON block ready to paste into the client config.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        server_slug: {
+          type: 'string',
+          description:
+            'Slug of the server (from search_mcp_servers or recommend_mcp_for_task results).',
+        },
+        client: {
+          type: 'string',
+          enum: ['claude-desktop', 'cursor', 'cline', 'zed'],
+          description: 'Target client.',
+        },
+      },
+      required: ['server_slug', 'client'],
+    },
+  },
+  {
+    name: 'compare_servers',
+    description:
+      'Side-by-side comparison of 2-5 MCP servers - quality scores, install paths, transport types, env vars.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        slugs: {
+          type: 'array',
+          items: { type: 'string' },
+          minItems: 2,
+          maxItems: 5,
+          description: 'Server slugs to compare.',
+        },
+      },
+      required: ['slugs'],
+    },
+  },
+  {
+    name: 'check_tool_trust',
+    description:
+      'Pre-invocation trust check for a specific tool on an MCP server. Returns an advisory verdict object (directive ALLOW | DENY | REVIEW | UNVERIFIED, dimensions, freshness). v1 advisory; conformance monitored not enforced; verdicts may be UNVERIFIED if not yet probed. Agents SHOULD treat UNVERIFIED as "human review required", never as ALLOW.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        server_id: {
+          type: 'string',
+          description: 'Server slug (e.g. "github", "filesystem"). Same id used by search_mcp_servers.',
+        },
+        tool_name: {
+          type: 'string',
+          description: 'Tool name as exposed by the server (e.g. "create_pull_request").',
+        },
+      },
+      required: ['server_id', 'tool_name'],
+    },
+  },
+  {
+    name: 'assess_server',
+    description:
+      'Aggregated pre-flight trust assessment across all tools on an MCP server. Same verdict shape as check_tool_trust. Use for "is THIS server worth integrating?" decisions. v1 advisory; conformance monitored not enforced; verdicts may be UNVERIFIED if not yet probed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        server_id: {
+          type: 'string',
+          description: 'Server slug to assess.',
+        },
+      },
+      required: ['server_id'],
+    },
+  },
+];
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+async function api(path) {
+  const res = await fetch(`${API_BASE}${path}`, {
+    headers: { 'User-Agent': 'mcp-server-mcpindex/0.1.0' },
+  });
+  if (!res.ok) {
+    throw new Error(`mcpindex API ${res.status}: ${await res.text()}`);
+  }
+  return res.json();
+}
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args } = req.params;
+  try {
+    let result;
+    switch (name) {
+      case 'recommend_mcp_for_task': {
+        const data = await api(
+          `/api/v1/recommend?task=${encodeURIComponent(args.task)}`,
+        );
+        result = formatRecommend(data);
+        break;
+      }
+      case 'search_mcp_servers': {
+        const params = new URLSearchParams({
+          q: args.query,
+          limit: String(Math.min(50, args.limit ?? 10)),
+        });
+        if (args.category) params.set('category', args.category);
+        const data = await api(`/api/v1/search?${params.toString()}`);
+        result = formatSearch(data);
+        break;
+      }
+      case 'get_install_command': {
+        const data = await api(`/api/v1/server/${encodeURIComponent(args.server_slug)}`);
+        result = formatInstall(data, args.client);
+        break;
+      }
+      case 'compare_servers': {
+        const rows = await Promise.all(
+          args.slugs.map((s) => api(`/api/v1/server/${encodeURIComponent(s)}`)),
+        );
+        result = formatCompare(rows);
+        break;
+      }
+      case 'check_tool_trust': {
+        const { checkToolTrust } = await import('./trust.mjs');
+        const verdict = await checkToolTrust({
+          serverId: args.server_id,
+          toolName: args.tool_name,
+          apiBase: API_BASE,
+          userAgent: `mcp-server-mcpindex/${PKG_VERSION}`,
+        });
+        result = JSON.stringify(verdict, null, 2);
+        break;
+      }
+      case 'assess_server': {
+        const { assessServer } = await import('./trust.mjs');
+        const verdict = await assessServer({
+          serverId: args.server_id,
+          apiBase: API_BASE,
+          userAgent: `mcp-server-mcpindex/${PKG_VERSION}`,
+        });
+        result = JSON.stringify(verdict, null, 2);
+        break;
+      }
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+    return { content: [{ type: 'text', text: result }] };
+  } catch (err) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: `Error calling ${name}: ${err instanceof Error ? err.message : err}`,
+        },
+      ],
+    };
+  }
+});
+
+function formatRecommend(data) {
+  const lines = [`Top ${data.recommendations.length} for: "${data.task}"`, ''];
+  for (const r of data.recommendations) {
+    lines.push(`[${r.rank}] ${r.title}  ·  QS ${r.qualityScore}/100  ·  ${r.category}`);
+    lines.push(`    ${r.name}@${r.qualityScore ? '' : ''}`);
+    lines.push(`    ${r.reasoning}`);
+    const install = r.installs.npm
+      ? `npx -y ${r.installs.npm}`
+      : r.installs.pypi
+        ? `uvx ${r.installs.pypi}`
+        : r.installs.docker
+          ? `docker run --rm -i ${r.installs.docker}`
+          : r.installs.remote
+            ? `Remote: ${r.installs.remote}`
+            : 'manual install - see detail page';
+    lines.push(`    $ ${install}`);
+    lines.push(`    ${r.url}`);
+    lines.push('');
+  }
+  lines.push(`Source: ${data.note ?? ''}`);
+  return lines.join('\n');
+}
+
+function formatSearch(data) {
+  const lines = [`${data.total} results for: "${data.query}"`, ''];
+  for (const r of data.results) {
+    lines.push(`- ${r.title}  (${r.name})  ·  QS ${r.qualityScore}/100  ·  ${r.category}`);
+    lines.push(`  ${r.description}`);
+    lines.push(`  ${r.url}`);
+  }
+  return lines.join('\n');
+}
+
+function formatInstall(server, client) {
+  // server here is the per-server JSON we expose at /api/v1/server/<slug>.
+  // Returns a code block with the appropriate install snippet.
+  const target = (server.installs ?? []).find((i) => i.client === client) ?? server.installs?.[0];
+  if (!target) return `No install path available for ${server.name}`;
+  return [
+    `${server.title} (${server.name}) - ${client}`,
+    '',
+    target.json
+      ? '```json\n' + target.json + '\n```'
+      : '```bash\n' + target.command + '\n```',
+    target.notes ? '\n' + target.notes : '',
+    `\n${server.url ?? `https://mcpindex.ai/server/${server.slug}`}`,
+  ].join('\n');
+}
+
+function formatCompare(rows) {
+  const header = ['name', 'category', 'quality', 'install', 'env vars'];
+  const data = rows.map((r) => [
+    r.name,
+    r.category,
+    String(r.qualityScore ?? ''),
+    r.installs?.[0]?.label ?? 'manual',
+    String(r.envVars?.length ?? 0),
+  ]);
+  const widths = header.map((h, i) =>
+    Math.max(h.length, ...data.map((row) => row[i].length)),
+  );
+  const fmt = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join('  ');
+  return [fmt(header), fmt(widths.map((w) => '-'.repeat(w))), ...data.map(fmt)].join('\n');
+}
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error('[mcp-server-mcpindex] connected via stdio');

package/src/trust.mjs

@@ -0,0 +1,164 @@
+// trust.mjs - check_tool_trust / assess_server verdict client.
+//
+// Contract (v1 advisory, free tier):
+//   {
+//     directive: "ALLOW" | "DENY" | "REVIEW" | "UNVERIFIED",
+//     status: "EVALUATED" | "STALE" | "ERROR",
+//     dimensions: [{ id, verdict, severity }],
+//     expires_at: string | null,
+//     honest_limits: string[],
+//     verdict_contract_version: "1.0.0",
+//     server_id, tool_name?, source_url, fetched_at
+//   }
+//
+// Fail-CLOSED: if the upstream endpoint is unreachable, returns 404, or
+// returns malformed data, we return directive=UNVERIFIED, status=ERROR.
+// We NEVER fake an ALLOW. This is the load-bearing safety invariant.
+
+export const VERDICT_CONTRACT_VERSION = '1.0.0';
+
+export const V1_HONEST_LIMITS = Object.freeze([
+  'conformance_monitored_not_enforced',
+  'calibrated_false_v1',
+  'advisory_deployment',
+]);
+
+const VALID_DIRECTIVES = new Set(['ALLOW', 'DENY', 'REVIEW', 'UNVERIFIED']);
+const VALID_STATUSES = new Set(['EVALUATED', 'STALE', 'ERROR']);
+const VALID_VERDICTS = new Set(['PASS', 'FAIL', 'UNVERIFIED']);
+const VALID_SEVERITIES = new Set(['INFO', 'LOW', 'MEDIUM', 'HIGH', 'CRITICAL']);
+
+const DEFAULT_TIMEOUT_MS = 5000;
+
+function unverifiedResponse({ serverId, toolName, sourceUrl, reason }) {
+  return {
+    directive: 'UNVERIFIED',
+    status: 'ERROR',
+    dimensions: [],
+    expires_at: null,
+    honest_limits: [...V1_HONEST_LIMITS, `unverified_reason:${reason}`],
+    verdict_contract_version: VERDICT_CONTRACT_VERSION,
+    server_id: serverId,
+    ...(toolName ? { tool_name: toolName } : {}),
+    source_url: sourceUrl,
+    fetched_at: new Date().toISOString(),
+  };
+}
+
+function normalizeDimensions(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const d of raw) {
+    if (!d || typeof d !== 'object') continue;
+    const id = typeof d.id === 'string' ? d.id : null;
+    const verdict = VALID_VERDICTS.has(d.verdict) ? d.verdict : 'UNVERIFIED';
+    const severity = VALID_SEVERITIES.has(d.severity) ? d.severity : 'INFO';
+    if (!id) continue;
+    out.push({ id, verdict, severity });
+  }
+  return out;
+}
+
+function shapeVerdict({ raw, serverId, toolName, sourceUrl }) {
+  // Defensive: if upstream returns garbage, treat as UNVERIFIED.
+  if (!raw || typeof raw !== 'object') {
+    return unverifiedResponse({ serverId, toolName, sourceUrl, reason: 'empty_payload' });
+  }
+
+  const directive = VALID_DIRECTIVES.has(raw.directive) ? raw.directive : 'UNVERIFIED';
+  const status = VALID_STATUSES.has(raw.status)
+    ? raw.status
+    : directive === 'UNVERIFIED'
+      ? 'ERROR'
+      : 'EVALUATED';
+  const dimensions = normalizeDimensions(raw.dimensions);
+  const expires_at = typeof raw.expires_at === 'string' ? raw.expires_at : null;
+
+  // honest_limits: always include the v1 defaults; merge in any extras the
+  // server sent. Never let the upstream remove the v1 floor.
+  const extra = Array.isArray(raw.honest_limits)
+    ? raw.honest_limits.filter((s) => typeof s === 'string')
+    : [];
+  const honest_limits = Array.from(new Set([...V1_HONEST_LIMITS, ...extra]));
+
+  return {
+    directive,
+    status,
+    dimensions,
+    expires_at,
+    honest_limits,
+    verdict_contract_version: VERDICT_CONTRACT_VERSION,
+    server_id: serverId,
+    ...(toolName ? { tool_name: toolName } : {}),
+    source_url: sourceUrl,
+    fetched_at: new Date().toISOString(),
+  };
+}
+
+async function fetchVerdict({ url, userAgent, fetchImpl, timeoutMs }) {
+  const f = fetchImpl ?? fetch;
+  const controller = new AbortController();
+  const t = setTimeout(() => controller.abort(), timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  try {
+    const res = await f(url, {
+      headers: { 'User-Agent': userAgent, Accept: 'application/json' },
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      return { ok: false, reason: `http_${res.status}` };
+    }
+    const data = await res.json();
+    return { ok: true, data };
+  } catch (err) {
+    const reason = err && err.name === 'AbortError' ? 'timeout' : 'network_error';
+    return { ok: false, reason };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+export async function checkToolTrust({
+  serverId,
+  toolName,
+  apiBase = 'https://mcpindex.ai',
+  userAgent = `mcp-server-mcpindex/${VERDICT_CONTRACT_VERSION}`,
+  fetchImpl,
+  timeoutMs,
+}) {
+  if (!serverId || !toolName) {
+    return unverifiedResponse({
+      serverId: serverId ?? '',
+      toolName: toolName ?? '',
+      sourceUrl: '',
+      reason: 'missing_args',
+    });
+  }
+  const url = `${apiBase}/api/v1/trust/tool/${encodeURIComponent(serverId)}/${encodeURIComponent(toolName)}`;
+  const r = await fetchVerdict({ url, userAgent, fetchImpl, timeoutMs });
+  if (!r.ok) {
+    return unverifiedResponse({ serverId, toolName, sourceUrl: url, reason: r.reason });
+  }
+  return shapeVerdict({ raw: r.data, serverId, toolName, sourceUrl: url });
+}
+
+export async function assessServer({
+  serverId,
+  apiBase = 'https://mcpindex.ai',
+  userAgent = `mcp-server-mcpindex/${VERDICT_CONTRACT_VERSION}`,
+  fetchImpl,
+  timeoutMs,
+}) {
+  if (!serverId) {
+    return unverifiedResponse({
+      serverId: '',
+      sourceUrl: '',
+      reason: 'missing_args',
+    });
+  }
+  const url = `${apiBase}/api/v1/trust/server/${encodeURIComponent(serverId)}`;
+  const r = await fetchVerdict({ url, userAgent, fetchImpl, timeoutMs });
+  if (!r.ok) {
+    return unverifiedResponse({ serverId, sourceUrl: url, reason: r.reason });
+  }
+  return shapeVerdict({ raw: r.data, serverId, sourceUrl: url });
+}