@nacho-labs/mcp-semantic-search 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nacho Labs 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,174 @@
+# @nacho-labs/mcp-semantic-search
+
+MCP server that gives AI coding tools persistent semantic memory. Index
+decisions, patterns, and project context — recall them by meaning, not keywords.
+
+Powered by [@nacho-labs/nachos-embeddings](https://github.com/nacho-labs-llc/nachos-embeddings).
+Runs entirely locally with [Transformers.js](https://huggingface.co/docs/transformers.js) —
+no API keys, no cloud, no costs.
+
+## Prerequisites
+
+- **Node.js 18+**
+- **Internet on first run** to download the embedding model (~25MB, cached permanently)
+
+## Quick start
+
+### Claude Code
+
+```bash
+claude mcp add --transport stdio semantic-search -- npx @nacho-labs/mcp-semantic-search
+```
+
+### Cursor / VS Code / any MCP client
+
+Add to your MCP config (`.mcp.json`, `mcp.json`, or client-specific config):
+
+```json
+{
+  "mcpServers": {
+    "semantic-search": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@nacho-labs/mcp-semantic-search"]
+    }
+  }
+}
+```
+
+That's it. Your AI tool now has six semantic memory tools.
+
+## Tools
+
+| Tool | Description |
+| ---- | ----------- |
+| `semantic_search` | Search indexed documents by meaning |
+| `semantic_index` | Add a document to the index |
+| `semantic_index_batch` | Add multiple documents at once |
+| `semantic_remove` | Remove a document by ID |
+| `semantic_stats` | Get index size, store location, and config |
+| `semantic_clear` | Remove all documents (requires confirmation) |
+
+## What it does
+
+```text
+You ask Claude: "How do we handle rate limiting?"
+                 |
+Claude calls:    semantic_search("rate limiting")
+                 |
+Server embeds:   query -> 384-dimension vector
+                 |
+Cosine search:   against all indexed vectors
+                 |
+Returns:         "We throttle API requests using sliding windows..."
+                 (matched by meaning, not keywords)
+```
+
+The embedding model understands meaning:
+
+| Query | Finds |
+| ----- | ----- |
+| "rate limiting" | "We throttle API requests using sliding windows" |
+| "how to deploy" | "Production runs via docker compose up with..." |
+| "error handling" | "We use Result types instead of try/catch for..." |
+
+## What to index
+
+High-value content for project memory:
+
+**Architecture decisions** — "We chose PostgreSQL over DynamoDB because we need
+complex joins for the reporting module."
+
+**Code patterns** — "Authentication middleware is in src/middleware/auth.ts.
+Uses JWT with RS256, tokens expire after 1 hour, refresh tokens after 30 days."
+
+**Conventions** — "All API endpoints return { data, error, meta } shape.
+Errors use RFC 7807 problem details format."
+
+**Debugging insights** — "If the worker queue backs up, check Redis memory.
+The default maxmemory-policy is noeviction which causes write failures."
+
+## Configuration
+
+### CLI arguments
+
+```bash
+npx @nacho-labs/mcp-semantic-search \
+  --store /path/to/store.json \
+  --similarity 0.5 \
+  --model Xenova/all-mpnet-base-v2 \
+  --cache-dir /tmp/models
+```
+
+### Environment variables
+
+| Variable | Description | Default |
+| -------- | ----------- | ------- |
+| `MCP_SEMANTIC_STORE` | Path to persistence file | `.semantic-store.json` |
+| `MCP_SEMANTIC_SIMILARITY` | Min similarity threshold (0-1) | `0.6` |
+| `MCP_SEMANTIC_MODEL` | Embedding model | `Xenova/all-MiniLM-L6-v2` |
+| `MCP_SEMANTIC_CACHE_DIR` | Model cache directory | `.cache/transformers` |
+
+### With environment variables in MCP config
+
+```json
+{
+  "mcpServers": {
+    "semantic-search": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@nacho-labs/mcp-semantic-search"],
+      "env": {
+        "MCP_SEMANTIC_STORE": "/home/user/.semantic-memory/project.json",
+        "MCP_SEMANTIC_SIMILARITY": "0.5"
+      }
+    }
+  }
+}
+```
+
+## Performance
+
+| Operation | Time |
+| --------- | ---- |
+| Server startup (model cached) | ~500ms |
+| Server startup (first run) | ~2-5s |
+| Index a document | ~10-50ms |
+| Search 1000 documents | ~5-10ms |
+
+**Memory:** ~100MB for model + ~1.5KB per document.
+
+The in-memory store works well up to ~10K documents. Beyond that, consider a
+dedicated vector database.
+
+## Persistence
+
+The index is saved to disk automatically after every write operation (index,
+remove, clear). On startup, the server loads the existing store if present.
+
+Default location: `.semantic-store.json` in the working directory.
+
+## How it's built
+
+This MCP server is a thin wrapper around two packages:
+
+- **[@nacho-labs/nachos-embeddings](https://www.npmjs.com/package/@nacho-labs/nachos-embeddings)** — Local vector embeddings and semantic search
+- **[@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk)** — Official MCP TypeScript SDK
+
+The embeddings package can also be used directly in your own code. See its
+[README](https://github.com/nacho-labs-llc/nachos-embeddings) for the
+standalone API.
+
+## Development
+
+```bash
+git clone https://github.com/nacho-labs-llc/mcp-semantic-search.git
+cd mcp-semantic-search
+npm install
+npm run build
+npm start
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * MCP Semantic Search Server
+ *
+ * Gives AI tools (Claude Code, Cursor, etc.) persistent semantic memory
+ * powered by local vector embeddings. No API keys, no cloud, no costs.
+ *
+ * Usage:
+ *   npx @nacho-labs/mcp-semantic-search
+ *   npx @nacho-labs/mcp-semantic-search --store /path/to/store.json
+ *   npx @nacho-labs/mcp-semantic-search --similarity 0.5
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;GAUG"}

package/dist/index.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+/**
+ * MCP Semantic Search Server
+ *
+ * Gives AI tools (Claude Code, Cursor, etc.) persistent semantic memory
+ * powered by local vector embeddings. No API keys, no cloud, no costs.
+ *
+ * Usage:
+ *   npx @nacho-labs/mcp-semantic-search
+ *   npx @nacho-labs/mcp-semantic-search --store /path/to/store.json
+ *   npx @nacho-labs/mcp-semantic-search --similarity 0.5
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { SemanticSearch } from '@nacho-labs/nachos-embeddings';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+// --- Configuration via CLI args and env vars ---
+function getConfig() {
+    const args = process.argv.slice(2);
+    function getArg(name, fallback) {
+        const idx = args.indexOf(`--${name}`);
+        if (idx !== -1 && idx + 1 < args.length) {
+            return args[idx + 1];
+        }
+        return fallback;
+    }
+    const storePath = resolve(process.env['MCP_SEMANTIC_STORE'] ??
+        getArg('store', '.semantic-store.json'));
+    const minSimilarity = parseFloat(process.env['MCP_SEMANTIC_SIMILARITY'] ??
+        getArg('similarity', '0.6'));
+    const model = process.env['MCP_SEMANTIC_MODEL'] ??
+        getArg('model', 'Xenova/all-MiniLM-L6-v2');
+    const cacheDir = process.env['MCP_SEMANTIC_CACHE_DIR'] ??
+        getArg('cache-dir', '.cache/transformers');
+    return { storePath, minSimilarity, model, cacheDir };
+}
+const config = getConfig();
+// --- Initialize search engine ---
+const search = new SemanticSearch({
+    minSimilarity: config.minSimilarity,
+    model: config.model,
+    cacheDir: config.cacheDir,
+});
+try {
+    await search.init();
+}
+catch (err) {
+    console.error('Failed to load embedding model.', 'An internet connection is required on first run to download the model (~25MB).', err);
+    process.exit(1);
+}
+// Load persisted index
+if (existsSync(config.storePath)) {
+    try {
+        const raw = await readFile(config.storePath, 'utf-8');
+        const data = JSON.parse(raw);
+        if (Array.isArray(data)) {
+            search.import(data);
+        }
+    }
+    catch (err) {
+        console.error(`Warning: Failed to load store from ${config.storePath}:`, err);
+    }
+}
+async function persist() {
+    const dir = dirname(config.storePath);
+    if (!existsSync(dir)) {
+        await mkdir(dir, { recursive: true });
+    }
+    await writeFile(config.storePath, JSON.stringify(search.export()));
+}
+// --- MCP Server ---
+const server = new McpServer({
+    name: 'mcp-semantic-search',
+    version: '0.1.0',
+}, {
+    capabilities: {
+        logging: {},
+    },
+});
+// Tool: Semantic search
+server.registerTool('semantic_search', {
+    title: 'Semantic Search',
+    description: 'Search indexed documents by meaning. Finds relevant content even when the wording differs from the query. Use this to recall past decisions, find related code patterns, or look up previously indexed context.',
+    inputSchema: z.object({
+        query: z.string().describe('Natural language search query'),
+        limit: z
+            .number()
+            .optional()
+            .default(5)
+            .describe('Maximum number of results to return'),
+    }),
+}, async ({ query, limit }) => {
+    const results = await search.search(query, { limit });
+    if (results.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'No relevant results found.' }],
+        };
+    }
+    const formatted = results
+        .map((r, i) => `${i + 1}. [${(r.similarity * 100).toFixed(0)}% match] ${r.text}` +
+        (r.metadata && Object.keys(r.metadata).length > 0
+            ? `\n   metadata: ${JSON.stringify(r.metadata)}`
+            : ''))
+        .join('\n\n');
+    return {
+        content: [
+            { type: 'text', text: `Found ${results.length} result(s):\n\n${formatted}` },
+        ],
+    };
+});
+// Tool: Index a document
+server.registerTool('semantic_index', {
+    title: 'Index Document',
+    description: 'Add a document to the semantic search index for later recall. Use this to remember decisions, patterns, file summaries, conventions, debugging insights, or any context worth recalling later. Documents persist across sessions.',
+    inputSchema: z.object({
+        id: z
+            .string()
+            .describe('Unique document ID. Use descriptive IDs like "adr-012", "auth-pattern", "deploy-steps"'),
+        text: z.string().describe('The text content to index and make searchable'),
+        metadata: z
+            .record(z.string())
+            .optional()
+            .describe('Optional key-value metadata (e.g. {"kind": "decision", "date": "2026-02-22"})'),
+    }),
+}, async ({ id, text, metadata }) => {
+    await search.addDocument({ id, text, metadata });
+    await persist();
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Indexed "${id}" (${search.size()} total documents in store)`,
+            },
+        ],
+    };
+});
+// Tool: Batch index multiple documents
+server.registerTool('semantic_index_batch', {
+    title: 'Batch Index Documents',
+    description: 'Add multiple documents to the index at once. More efficient than indexing one at a time.',
+    inputSchema: z.object({
+        documents: z.array(z.object({
+            id: z.string().describe('Unique document ID'),
+            text: z.string().describe('Text content to index'),
+            metadata: z
+                .record(z.string())
+                .optional()
+                .describe('Optional key-value metadata'),
+        })).describe('Array of documents to index'),
+    }),
+}, async ({ documents }) => {
+    await search.addDocuments(documents);
+    await persist();
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Indexed ${documents.length} documents (${search.size()} total in store)`,
+            },
+        ],
+    };
+});
+// Tool: Remove a document
+server.registerTool('semantic_remove', {
+    title: 'Remove Document',
+    description: 'Remove a document from the semantic search index by its ID.',
+    inputSchema: z.object({
+        id: z.string().describe('Document ID to remove'),
+    }),
+}, async ({ id }) => {
+    const removed = search.remove(id);
+    if (removed)
+        await persist();
+    return {
+        content: [
+            {
+                type: 'text',
+                text: removed
+                    ? `Removed "${id}" (${search.size()} documents remaining)`
+                    : `Document "${id}" not found in index`,
+            },
+        ],
+    };
+});
+// Tool: Get index stats
+server.registerTool('semantic_stats', {
+    title: 'Index Stats',
+    description: 'Get information about the semantic search index: document count and storage location.',
+    inputSchema: z.object({}),
+}, async () => ({
+    content: [
+        {
+            type: 'text',
+            text: [
+                `Documents indexed: ${search.size()}`,
+                `Store location: ${config.storePath}`,
+                `Model: ${config.model}`,
+                `Min similarity: ${config.minSimilarity}`,
+            ].join('\n'),
+        },
+    ],
+}));
+// Tool: Clear all documents
+server.registerTool('semantic_clear', {
+    title: 'Clear Index',
+    description: 'Remove ALL documents from the semantic search index. This is irreversible.',
+    inputSchema: z.object({
+        confirm: z
+            .boolean()
+            .describe('Must be true to confirm clearing all documents'),
+    }),
+}, async ({ confirm }) => {
+    if (!confirm) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Clear cancelled. Set confirm: true to clear all documents.',
+                },
+            ],
+        };
+    }
+    const count = search.size();
+    search.clear();
+    await persist();
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Cleared ${count} documents from the index.`,
+            },
+        ],
+    };
+});
+// --- Start server ---
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@nacho-labs/mcp-semantic-search",
+  "version": "0.1.0",
+  "description": "MCP server for local semantic search — give Claude Code, Cursor, and other AI tools persistent memory powered by nachos-embeddings",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "mcp-semantic-search": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "server.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "prepublishOnly": "npm run build",
+    "version:patch": "npm version patch",
+    "version:minor": "npm version minor",
+    "version:major": "npm version major",
+    "publish:npm": "npm publish --access public",
+    "release:patch": "npm run version:patch && npm run publish:npm",
+    "release:minor": "npm run version:minor && npm run publish:npm",
+    "release:major": "npm run version:major && npm run publish:npm"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "semantic-search",
+    "embeddings",
+    "vector-search",
+    "claude",
+    "claude-code",
+    "ai-memory",
+    "local",
+    "privacy"
+  ],
+  "author": "Nate Richardson <hello@naterichardson.com> (https://naterichardson.com)",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nacho-labs-llc/mcp-semantic-search.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@nacho-labs/nachos-embeddings": "^0.1.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/server.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.nacho-labs-llc/mcp-semantic-search",
+  "description": "Local semantic search for AI coding tools. Index decisions, patterns, and context — recall them by meaning, not keywords. Powered by nachos-embeddings (Transformers.js). No API keys, no cloud, no costs.",
+  "title": "Semantic Search MCP Server",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/nacho-labs-llc/mcp-semantic-search",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@nacho-labs/mcp-semantic-search",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "MCP_SEMANTIC_STORE",
+          "description": "Path to the JSON file where the index is persisted. Defaults to .semantic-store.json in the working directory.",
+          "isRequired": false,
+          "isSecret": false,
+          "format": "string"
+        },
+        {
+          "name": "MCP_SEMANTIC_SIMILARITY",
+          "description": "Minimum similarity threshold (0-1). Defaults to 0.6.",
+          "isRequired": false,
+          "isSecret": false,
+          "format": "string"
+        },
+        {
+          "name": "MCP_SEMANTIC_MODEL",
+          "description": "Embedding model to use. Defaults to Xenova/all-MiniLM-L6-v2.",
+          "isRequired": false,
+          "isSecret": false,
+          "format": "string"
+        }
+      ]
+    }
+  ]
+}