@jini-ai/mcp 0.1.2 → 0.3.0

package/dist/server/tools/tool-catalog-tools.js

@@ -2,7 +2,7 @@
  * @module @jini-ai/mcp/server/tools/tool-catalog-tools
  *
  * `search_tools` / `describe_tool` — the discovery half of `ai-control-plane.md` §29 /
- * `PROP-tool-catalog-discovery-2026-07-26.md` §6.1, proxying `@jini-ai/http`'s
+ * `PROP-tool-catalog-discovery-2026-07-26.md` §6.1, proxying `@jini-ai/http-kit`'s
  * `GET /api/tools/search` / `GET /api/tools/:id` exactly as `run-tools.ts`'s tools proxy
  * `runs.ts` — no separate authorization mechanism, no caching, no state.
  *
@@ -12,7 +12,7 @@
  * Finding a tool id here grants nothing (`PROP` §6.3).
  */
 import { getDaemonJson } from '../daemon-client.js';
-import { requireString } from '../tool-protocol.js';
+import { daemonCallOptions, requireString } from '../tool-protocol.js';
 const READ_ANNOTATIONS = {
     readOnlyHint: true,
     idempotentHint: true,
@@ -21,12 +21,48 @@ const READ_ANNOTATIONS = {
 /** `search_tools` -> `GET /api/tools/search` (`packages/http/src/tool-catalog.ts`'s `toolCatalogSearchRoute`). */
 export const searchToolsTool = {
     name: 'search_tools',
-    description: 'Search the durable tool catalog by keyword. Returns ranked {id, description, source, score} candidates only — no input schemas, so this stays cheap to call broadly. Call describe_tool on the 1-3 candidates that look right before calling execute_delegated_tool.',
+    description: 'Search the durable tool catalog. Returns ranked {id, description, source, score} candidates only — no input schemas, so this stays cheap to call broadly. Call describe_tool on the 1-3 candidates that look right before calling execute_delegated_tool. If nothing in the results fits, re-search with a higher limit or different phrasing rather than assuming the tool does not exist.',
     inputSchema: {
         type: 'object',
         properties: {
-            query: { type: 'string', description: 'Keywords to search for, e.g. "navigate page" or "fill form". Required.' },
-            limit: { type: 'number', description: 'Max hits to return (1-25). Optional, defaults to 10.' },
+            // Descriptive phrasing, NOT keywords — and the example matters as much as the instruction.
+            // The catalog is matched on tool *descriptions* (BM25 over description text), so a query
+            // written in the register of a description retrieves far better than a keyword bag. Measured
+            // on an independent n=130 blind set: terse keywords 25% top-1, descriptive phrasing 72%.
+            // This field previously read 'Keywords to search for, e.g. "navigate page" or "fill form"',
+            // which is the 25% form. It also directly contradicted the descriptive guidance a host server
+            // may inject upstream (a host's agent-daemon systemOverlay said the opposite), so a caller was
+            // given two conflicting instructions — with this one sitting on the parameter itself, read at
+            // the moment the query is composed.
+            //
+            // NOT measured: which instruction won. The hypothesis was that a two-word example outranks
+            // prose guidance, but the conflict was removed before anyone measured it, so treat that as
+            // untested rather than established. What IS measured, on the coherent state after this fix:
+            // 35/35 real search_tools calls across 24 live CLI sessions used descriptive phrasing.
+            // Keep the example long-form; shortening it re-creates the 25% form.
+            query: {
+                type: 'string',
+                description: 'Describe what the tool you need DOES, the way its own documentation would describe it — a full phrase, not a keyword bag. Name the thing being acted on and the action, and include likely synonyms for both. Example: for a request like "how many people visited last week", write "retrieve site traffic and visitor analytics counts for a date range" rather than "visitors last week". Descriptive phrasing retrieves substantially better than terse keywords, because the catalog is matched on tool descriptions. Required.',
+            },
+            // Bounds mirror `packages/http-kit/src/tool-catalog.ts`'s `parseSearchInput`
+            // exactly (`MAX_SEARCH_LIMIT = 25`, `DEFAULT_SEARCH_LIMIT = 10`, integers only,
+            // `>= 1`). Declared rather than left as a bare `number` so MCP validation and the
+            // route agree: otherwise `0`/`1.5` pass here and are refused downstream, and `26`
+            // passes here and is silently clamped — the caller is told one contract and given
+            // another.
+            // The escalation clause is the cheap half of a measured ceiling. On the same n=130 blind set,
+            // with the host's operator-vocabulary + doc2query index folded in, the right tool is in the
+            // default top 10 for 98% of cases and in the top 20 for 100% — so the residual misses are
+            // ranked just below the cutoff, never absent. Raising the DEFAULT to 20 would buy those 2
+            // cases at ~900 extra tokens on every single call; telling the caller to escalate on demand
+            // buys the same ceiling only when it is needed. Same lever as the descriptive-phrasing fix
+            // above: a prompt change, not an LLM call.
+            limit: {
+                type: 'integer',
+                minimum: 1,
+                maximum: 25,
+                description: 'Max hits to return (1-25). Optional, defaults to 10. If none of the returned candidates fit what you need, search again with a HIGHER limit (try 25) before concluding no tool exists — the right tool is in the top 10 about 98% of the time and in the top 20 100% of the time, so a near-miss is ranked just below the default cutoff rather than missing.',
+            },
         },
         required: ['query'],
         additionalProperties: false,
@@ -37,9 +73,7 @@ export const searchToolsTool = {
         const params = new URLSearchParams({ q: args.query });
         if (typeof args.limit === 'number')
             params.set('limit', String(args.limit));
-        const data = await getDaemonJson(ctx.baseUrl, `/api/tools/search?${params.toString()}`, {
-            fetchImpl: ctx.fetchImpl,
-        });
+        const data = await getDaemonJson(ctx.baseUrl, `/api/tools/search?${params.toString()}`, daemonCallOptions(ctx));
         return data.hits;
     },
 };
@@ -58,7 +92,7 @@ export const describeToolTool = {
     annotations: { ...READ_ANNOTATIONS, title: 'Describe a tool' },
     handler: async (args, ctx) => {
         requireString(args.id, 'id');
-        return getDaemonJson(ctx.baseUrl, `/api/tools/${encodeURIComponent(args.id)}`, { fetchImpl: ctx.fetchImpl });
+        return getDaemonJson(ctx.baseUrl, `/api/tools/${encodeURIComponent(args.id)}`, daemonCallOptions(ctx));
     },
 };
 /** Both tool-catalog discovery tools, ready to pass as `createMcpToolServer`'s `tools` option. */

package/dist/server/tools/tool-catalog-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-catalog-tools.js","sourceRoot":"","sources":["../../../src/server/tools/tool-catalog-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAmB,MAAM,qBAAqB,CAAC;AAErE,MAAM,gBAAgB,GAAG;IACvB,YAAY,EAAE,IAAI;IAClB,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,KAAK;CACZ,CAAC;AAWX,kHAAkH;AAClH,MAAM,CAAC,MAAM,eAAe,GAAe;IACzC,IAAI,EAAE,cAAc;IACpB,WAAW,EACT,sQAAsQ;IACxQ,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,wEAAwE,EAAE;YAChH,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sDAAsD,EAAE;SAC/F;QACD,QAAQ,EAAE,CAAC,OAAO,CAAC;QACnB,oBAAoB,EAAE,KAAK;KAC5B;IACD,WAAW,EAAE,EAAE,GAAG,gBAAgB,EAAE,KAAK,EAAE,yBAAyB,EAAE;IACtE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAC3B,aAAa,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACnC,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACtD,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ;YAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5E,MAAM,IAAI,GAAG,MAAM,aAAa,CAA4B,GAAG,CAAC,OAAO,EAAE,qBAAqB,MAAM,CAAC,QAAQ,EAAE,EAAE,EAAE;YACjH,SAAS,EAAE,GAAG,CAAC,SAAS;SACzB,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;CACF,CAAC;AAEF,kHAAkH;AAClH,MAAM,CAAC,MAAM,gBAAgB,GAAe;IAC1C,IAAI,EAAE,eAAe;IACrB,WAAW,EACT,sMAAsM;IACxM,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,6CAA6C,EAAE;SACnF;QACD,QAAQ,EAAE,CAAC,IAAI,CAAC;QAChB,oBAAoB,EAAE,KAAK;KAC5B;IACD,WAAW,EAAE,EAAE,GAAG,gBAAgB,EAAE,KAAK,EAAE,iBAAiB,EAAE;IAC9D,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAC3B,aAAa,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAC7B,OAAO,aAAa,CAAC,GAAG,CAAC,OAAO,EAAE,cAAc,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;IAC/G,CAAC;CACF,CAAC;AAEF,kGAAkG;AAClG,MAAM,CAAC,MAAM,kBAAkB,GAA0B,CAAC,eAAe,EAAE,gBAAgB,CAAC,CAAC"}
+{"version":3,"file":"tool-catalog-tools.js","sourceRoot":"","sources":["../../../src/server/tools/tool-catalog-tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@jini-ai/mcp",
-  "version": "0.1.2",
+  "version": "0.3.0",
+  "description": "Model Context Protocol adapters: server config schema and IO, an MCP client, and agent-side MCP server installation.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -10,10 +11,10 @@
   "jini": {
     "domain": "integration",
     "kind": "protocol-adapter",
-    "runtime": "node",
-    "admission": "incubating"
+    "runtime": "node"
   },
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -21,6 +22,9 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./bin": {
+      "default": "./dist/bin/serve.js"
     }
   },
   "bin": {
@@ -39,10 +43,11 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
+    "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "undici": "^7.25.0",
-    "@jini-ai/cli": "0.1.2",
-    "@jini-ai/platform": "0.1.2"
+    "@jini-ai/cli": "0.3.0",
+    "@jini-ai/platform": "0.3.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && chmod +x dist/bin/serve.js",