@neottia/searchable-mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dragos Cirjan
+
+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,13 @@
+# @neottia/searchable-mcp
+
+Generic stdio MCP server for the five Searchable tools.
+
+```sh
+pnpm dlx @neottia/searchable-mcp
+```
+
+Run the command from the project working directory after setting `modules.searchable.enabled: true`. The server exposes tools only. Use MCP `tools/list` to verify `web_search`, `web_fetch`, `web_stash`, `web_grep`, and `web_ask`.
+
+The server resolves the complete `@neottia/config-registry` snapshot once for its working directory and passes the immutable Searchable shard to its runtime and tools. It forwards request cancellation, returns object results as structured content and JSON text, and returns redacted structured errors as text. It owns one Searchable runtime and closes network and cache resources with `server.close()` or process termination.
+
+Read the [Searchable MCP guide](https://github.com/dragoscirjan/neottia/blob/main/docs/mcp/searchable.md).

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createSearchableServer } from './server.js';
+const server = createSearchableServer();
+let closing = false;
+async function close() {
+    if (closing)
+        return;
+    closing = true;
+    await server.close();
+}
+process.once('SIGINT', () => void close());
+process.once('SIGTERM', () => void close());
+await server.connect(new StdioServerTransport());
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAErD,MAAM,MAAM,GAAG,sBAAsB,EAAE,CAAC;AACxC,IAAI,OAAO,GAAG,KAAK,CAAC;AACpB,KAAK,UAAU,KAAK;IAClB,IAAI,OAAO;QAAE,OAAO;IACpB,OAAO,GAAG,IAAI,CAAC;IACf,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;AACvB,CAAC;AACD,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC;AAC3C,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC;AAC5C,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './server.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './server.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,13 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ResolvedConfigSnapshot } from '@neottia/config';
+import { type SearchableConfigInput, type SearchableRuntimeFactory } from '@neottia/searchable-core';
+export interface CreateSearchableServerOptions {
+    readonly cwd?: string;
+    readonly name?: string;
+    readonly version?: string;
+    readonly snapshot?: ResolvedConfigSnapshot;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly configOverrides?: Partial<SearchableConfigInput>;
+    readonly runtimeFactory?: SearchableRuntimeFactory;
+}
+export declare function createSearchableServer(options?: CreateSearchableServerOptions): Server;

package/dist/server.js

@@ -0,0 +1,59 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { resolveHostConfigSnapshot } from '@neottia/config-registry';
+import { createSearchableRuntime, findSearchableTool, searchableToolJsonSchema, SEARCHABLE_TOOLS, SearchableError, searchableConfigContribution, serializeSearchableError, } from '@neottia/searchable-core';
+export function createSearchableServer(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const snapshot = resolveHostConfigSnapshot({
+        interactive: false,
+        cwd,
+        ...(options.snapshot ? { snapshot: options.snapshot } : {}),
+        ...(options.env ? { env: options.env } : {}),
+        ...(options.configOverrides ? { overrides: { modules: { searchable: options.configOverrides } } } : {}),
+    });
+    const config = snapshot.get(searchableConfigContribution);
+    const runtime = (options.runtimeFactory ?? createSearchableRuntime)({ cwd, config });
+    const server = new Server({ name: options.name ?? '@neottia/searchable-mcp', version: options.version ?? '0.1.0' }, { capabilities: { tools: {} } });
+    const baseClose = server.close.bind(server);
+    let closePromise;
+    server.close = () => {
+        closePromise ??= Promise.allSettled([runtime.close(), baseClose()]).then((results) => {
+            const errors = results.flatMap((result) => (result.status === 'rejected' ? [result.reason] : []));
+            if (errors.length)
+                throw new AggregateError(errors, 'Searchable MCP shutdown failed.');
+        });
+        return closePromise;
+    };
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: SEARCHABLE_TOOLS.map((definition) => ({
+            name: definition.name,
+            description: definition.description,
+            inputSchema: searchableToolJsonSchema(definition.name, 'input'),
+            outputSchema: searchableToolJsonSchema(definition.name, 'output'),
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const definition = findSearchableTool(request.params.name);
+        if (!definition)
+            return toolError(new SearchableError('validation', 'TOOL_NOT_FOUND', `Unknown tool: ${request.params.name}`));
+        try {
+            const result = await definition.run({ cwd, services: runtime, signal: extra.signal, config }, request.params.arguments ?? {});
+            const structured = result;
+            return {
+                content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+                structuredContent: structured,
+            };
+        }
+        catch (error) {
+            return toolError(error instanceof SearchableError
+                ? error
+                : new SearchableError('service', 'SERVICE_FAILED', 'Searchable service failed.'));
+        }
+    });
+    return server;
+}
+function toolError(error) {
+    const body = serializeSearchableError(error);
+    return { content: [{ type: 'text', text: JSON.stringify(body) }], isError: true };
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@neottia/searchable-mcp",
+  "version": "0.2.0",
+  "description": "Generic MCP stdio server for Neottia Searchable",
+  "author": "Dragos Cirjan",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dragoscirjan/neottia.git",
+    "directory": "packages/searchable-mcp"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "searchable-mcp": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.16.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@neottia/config": "^0.2.0",
+    "@neottia/config-registry": "^0.2.0",
+    "@neottia/searchable-core": "0.2.0"
+  },
+  "devDependencies": {
+    "@templ-project/tsconfig": "^0.2.2",
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "@neottia/testkit": "0.1.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "pretest": "node ../../scripts/run-unless-workspace-prebuilt.mjs pnpm --filter @neottia/searchable-mcp... run build",
+    "test": "vitest run --root ../.. packages/searchable-mcp/src",
+    "typecheck": "tsc --noEmit"
+  }
+}