mcp-server-mcpindex 0.3.9 → 0.3.11

package/CHANGELOG.md

@@ -4,6 +4,21 @@ 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.3.11] - 2026-07-18
+
+### Fixed
+
+- **Verdict `status` no longer overstates screening completeness.** The live API emits `status: "PARTIAL"` for a description-level screen, but the client's `VALID_STATUSES` omitted `PARTIAL` and coerced it *up* to `EVALUATED` (a full screen) — dishonest for a trust tool. `PARTIAL` now passes through verbatim, an unknown status is coerced *down* to `STALE` (never up to `EVALUATED`), and the `granularity` field (e.g. `"description-level"`) is now preserved instead of dropped.
+- **README:** documents the `PARTIAL` status + `granularity`, and clarifies that `status: "ERROR"` also covers "no verdict on file yet" (not only endpoint failures).
+
+## [0.3.10] - 2026-07-18
+
+### Fixed
+
+- **`get_install_command` no longer advertises or mislabels a `zed` client.** `zed` was in the client enum but the install builder never produced a zed config, so a zed request silently returned a different client's config under a `zed` header. Removed `zed` from the enum, and `formatInstall` now labels any fallback honestly (never presents one client's config under another client's name).
+- **`check_tool_trust` schema example uses a real registry slug.** The `server_id` example was `"github"`, a short name that never resolves (always ERROR/UNVERIFIED); it now shows a real long-form slug (e.g. `io-github-microsoft-playwright-mcp`) and states it is not a short name.
+- **`compare_servers` description no longer promises "transport types"** that the output table never contained.
+
 ## [0.3.9] - 2026-07-15
 
 ### Changed

package/README.md

@@ -97,12 +97,15 @@ npx -y mcp-server-mcpindex@latest
 
 `check_tool_trust` is the **directory client** integration surface (not the in-path `mcpindex-gate`). It lets agent frameworks (Composio, Mastra, LangChain, DSPy, raw LLM-tool-call loops) ask for an advisory screen verdict before dispatching a call. At v1 you will see REVIEW or UNVERIFIED — not a safety clearance.
 
+> **Using Mastra?** The sibling package `@mcp-index/mastra` ships this exact screen as a ready-made `beforeToolCall` hook - `npm i @mcp-index/mastra`, no wiring required.
+
 ### Verdict contract (v1)
 
 ```jsonc
 {
   "directive": "ALLOW" | "DENY" | "REVIEW" | "UNVERIFIED",
-  "status":    "EVALUATED" | "STALE" | "ERROR",
+  "status":    "EVALUATED" | "PARTIAL" | "STALE" | "ERROR",
+  "granularity": "description-level" | null,  // scope of a PARTIAL screen
   "dimensions": [
     { "id": "tool_safety", "verdict": "PASS", "severity": "INFO" }
   ],
@@ -190,7 +193,9 @@ async function gateToolCall({ serverId, toolName, invoke, askHuman }) {
 
 ### 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."
+If the verdict endpoint is unreachable, returns 404, times out, returns malformed JSON, **or has no verdict on file yet for that server**, `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."
+
+`status` is telemetry about screen completeness, distinct from the `directive` trust decision: `EVALUATED` (full screen), `PARTIAL` (only part of the surface, e.g. description-level — see `granularity`), `STALE` (verdict past its freshness window), `ERROR` (unreachable / no verdict on file). A `PARTIAL` screen is never reported as `EVALUATED`.
 
 This is tested. See `test/trust.test.mjs`.
 
@@ -217,6 +222,18 @@ By default, calls go to `https://mcpindex.ai`. Override with `MCPINDEX_API_BASE=
 
 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).
 
+## Related packages
+
+Three ways to bring mcpindex into an agent, for different surfaces:
+
+| Package | Install | What it does |
+| --- | --- | --- |
+| **`mcp-server-mcpindex`** *(this package)* | `npm i -g mcp-server-mcpindex` | Directory + advisory screen as an MCP server: find servers by task, and `check_tool_trust` before a call. |
+| **`@mcp-index/mastra`** | `npm i @mcp-index/mastra` | The same advisory screen wired into Mastra as a `beforeToolCall` hook (warn / enforce). |
+| **`@mcp-index/sdk`** | `npm i @mcp-index/sdk` | In-path drift gate: `wrap()` an MCP session and HOLD a call when a tool's contract drifts from your pin. |
+
+**Advisory screen vs drift gate:** this package and `@mcp-index/mastra` ask mcpindex "has this tool been vetted?" (a network verdict). `@mcp-index/sdk` asks a different question locally: "did this tool's contract change since I pinned it?" Complementary, and none depends on another.
+
 ## License
 
 MIT.

package/manifest.json

@@ -2,11 +2,11 @@
   "manifest_version": "0.2",
   "name": "mcp-server-mcpindex",
   "display_name": "mcpindex",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "description": "The MCP directory that vets servers, not just lists them: search by task, then get an advisory screen on a server before an agent calls its tools. Advisory, conformance monitored not enforced, not a safety verdict.",
   "long_description": "mcpindex is the MCP directory that vets servers, not just lists them. Search by task to find the right server (ranked picks with install commands and quality scores), then get an advisory screen on a specific tool or a whole server before your agent calls it: whether each tool does what it claims. check_tool_trust and assess_server return an advisory verdict (REVIEW / UNVERIFIED at v1), backed by conformance monitoring and a live drift ledger, and fail closed to human review. Zero-config: queries the public mcpindex.ai API, no credentials. Monitored, not enforced; not a safety verdict and not an in-path gate.",
   "author": {
-    "name": "Bhartis LLC",
+    "name": "mcpindex.ai",
     "email": "hello@mcpindex.ai",
     "url": "https://mcpindex.ai"
   },
@@ -31,7 +31,9 @@
     "entry_point": "src/index.mjs",
     "mcp_config": {
       "command": "node",
-      "args": ["${__dirname}/src/index.mjs"],
+      "args": [
+        "${__dirname}/src/index.mjs"
+      ],
       "env": {
         "MCPINDEX_API_BASE": "${user_config.api_base}"
       }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "mcp-server-mcpindex",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "mcpName": "io.github.gautamgb/mcp-server-mcpindex",
-  "description": "The MCP directory that vets servers, not just lists them. Search by task, then get an advisory screen on a server before your agent calls its tools: whether each tool does what it claims, backed by conformance monitoring and a public drift ledger. Advisory (REVIEW / UNVERIFIED), monitored not enforced, not a safety verdict. Drop-in for Claude Desktop, Claude Code, Cursor, Gemini CLI, Cline, Zed.",
+  "description": "The MCP directory that vets servers, not just lists them. Search by task, then get an advisory screen on a server before your agent calls its tools: whether each tool does what it claims, backed by conformance monitoring and a public drift ledger. Advisory (REVIEW / UNVERIFIED), monitored not enforced, not a safety verdict. Drop-in for Claude Desktop, Claude Code, Cursor, Gemini CLI, Cline.",
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -24,7 +24,7 @@
   "bugs": {
     "url": "https://github.com/mcpindex-ai/mcpindex-web/issues"
   },
-  "author": "Bhartis LLC <hello@mcpindex.ai>",
+  "author": "mcpindex.ai <hello@mcpindex.ai>",
   "license": "MIT",
   "type": "module",
   "main": "src/index.mjs",

package/src/index.mjs

@@ -85,7 +85,11 @@ const TOOLS = [
         },
         client: {
           type: 'string',
-          enum: ['claude-desktop', 'claude-code', 'cursor', 'gemini-cli', 'cline', 'zed'],
+          // Only clients the API actually generates a config for. 'zed' was advertised
+          // but never produced (buildInstalls has no zed branch), so a zed request silently
+          // fell back to another client's config; dropped until a real zed generator exists.
+          // formatInstall also labels any fallback honestly as defense-in-depth.
+          enum: ['claude-desktop', 'claude-code', 'cursor', 'gemini-cli', 'cline'],
           description: 'Target client.',
         },
       },
@@ -119,7 +123,8 @@ const TOOLS = [
       properties: {
         server_id: {
           type: 'string',
-          description: 'Server slug (e.g. "github", "filesystem"). Same id used by search_mcp_servers.',
+          description:
+            'Registry slug from search_mcp_servers / recommend results, e.g. "io-github-microsoft-playwright-mcp" (NOT a short name like "github").',
         },
         tool_name: {
           type: 'string',
@@ -266,15 +271,24 @@ function formatSearch(data) {
 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];
+  const exact = (server.installs ?? []).find((i) => i.client === client);
+  const target = exact ?? server.installs?.[0];
   if (!target) return `No install path available for ${server.name}`;
+  // Never mislabel a fallback as the requested client: if this server publishes no
+  // config for `client`, show the header for the config we're ACTUALLY returning and
+  // say so, so an agent doesn't paste (e.g.) a claude-desktop block into another client.
+  const shownClient = exact ? client : (target.client ?? client);
+  const fallbackNote = exact
+    ? ''
+    : `\n(No ${client}-specific config published for this server; showing the ${shownClient} config.)`;
   return [
-    `${server.title} (${server.name}) - ${client}`,
+    `${server.title} (${server.name}) - ${shownClient}`,
     '',
     target.json
       ? '```json\n' + target.json + '\n```'
       : '```bash\n' + target.command + '\n```',
     target.notes ? '\n' + target.notes : '',
+    fallbackNote,
     `\n${server.url ?? `https://mcpindex.ai/server/${server.slug}`}`,
   ].join('\n');
 }

package/src/tools-meta.json

@@ -17,7 +17,7 @@
   {
     "name": "compare_servers",
     "title": "Compare MCP servers",
-    "description": "Side-by-side comparison of 2-5 MCP servers - quality scores, install paths, transport types, env vars."
+    "description": "Side-by-side comparison of 2-5 MCP servers - quality scores, install paths, env vars."
   },
   {
     "name": "check_tool_trust",

package/src/trust.mjs

@@ -3,7 +3,8 @@
 // Contract (v1 advisory, free tier):
 //   {
 //     directive: "ALLOW" | "DENY" | "REVIEW" | "UNVERIFIED",
-//     status: "EVALUATED" | "STALE" | "ERROR",
+//     status: "EVALUATED" | "PARTIAL" | "STALE" | "ERROR",
+//     granularity: string | null,   // e.g. "description-level" for a PARTIAL screen
 //     dimensions: [{ id, verdict, severity }],
 //     expires_at: string | null,
 //     honest_limits: string[],
@@ -14,6 +15,12 @@
 // 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.
+//
+// status is TELEMETRY about screen completeness (not the trust decision — that is
+// `directive`). PARTIAL means the screen only covered part of the surface (e.g.
+// description-level, not the live tool); it must NEVER be reported as EVALUATED. An
+// unexpected/unknown status is coerced DOWN to STALE (conservative), never up to
+// EVALUATED — overstating completeness is the one direction a trust tool must not drift.
 
 export const VERDICT_CONTRACT_VERSION = '1.0.0';
 
@@ -24,7 +31,7 @@ export const V1_HONEST_LIMITS = Object.freeze([
 ]);
 
 const VALID_DIRECTIVES = new Set(['ALLOW', 'DENY', 'REVIEW', 'UNVERIFIED']);
-const VALID_STATUSES = new Set(['EVALUATED', 'STALE', 'ERROR']);
+const VALID_STATUSES = new Set(['EVALUATED', 'PARTIAL', 'STALE', 'ERROR']);
 const VALID_VERDICTS = new Set(['PASS', 'FAIL', 'UNVERIFIED']);
 const VALID_SEVERITIES = new Set(['INFO', 'LOW', 'MEDIUM', 'HIGH', 'CRITICAL']);
 
@@ -34,6 +41,7 @@ function unverifiedResponse({ serverId, toolName, sourceUrl, reason }) {
   return {
     directive: 'UNVERIFIED',
     status: 'ERROR',
+    granularity: null,
     dimensions: [],
     expires_at: null,
     honest_limits: [...V1_HONEST_LIMITS, `unverified_reason:${reason}`],
@@ -66,11 +74,17 @@ function shapeVerdict({ raw, serverId, toolName, sourceUrl }) {
   }
 
   const directive = VALID_DIRECTIVES.has(raw.directive) ? raw.directive : 'UNVERIFIED';
+  // Known status passes through verbatim (incl. PARTIAL). An UNKNOWN status is coerced
+  // conservatively: ERROR when there's no directive, else STALE — NEVER 'EVALUATED',
+  // which would falsely claim a complete screen.
   const status = VALID_STATUSES.has(raw.status)
     ? raw.status
     : directive === 'UNVERIFIED'
       ? 'ERROR'
-      : 'EVALUATED';
+      : 'STALE';
+  // Screen granularity (e.g. "description-level"); pass through so callers can see a
+  // PARTIAL screen's scope instead of silently losing it.
+  const granularity = typeof raw.granularity === 'string' ? raw.granularity : null;
   const dimensions = normalizeDimensions(raw.dimensions);
   const expires_at = typeof raw.expires_at === 'string' ? raw.expires_at : null;
 
@@ -84,6 +98,7 @@ function shapeVerdict({ raw, serverId, toolName, sourceUrl }) {
   return {
     directive,
     status,
+    granularity,
     dimensions,
     expires_at,
     honest_limits,