Semdex

A local MCP server that gives AI coding assistants structured, queryable intelligence about a codebase.

Overview

Semdex (semantic + index) is a local MCP server that parses codebases into semantic chunks (functions, classes, interfaces), indexes them in SQLite with vector embeddings, and exposes MCP tools for LLM agents to query.

Think of it as an LSP, but for AI — instead of "go to definition" for humans, it's "find all relevant code" for an LLM.

Why Semdex?

• Context windows are limited. LLMs can't fit an entire codebase in context. Semdex finds exactly the relevant code and feeds only that to the model.
• Structure-aware, not grep. Traditional search matches text; Semdex understands code structure — functions, classes, methods, interfaces — and their relationships.
• Runs locally. No cloud dependencies, no API keys, no data leaving your machine. Works offline.
• Editor-agnostic. Speaks MCP, the standard protocol for AI tool integration. Works with any MCP-compatible client.

Status

⚠️ Early Development — This project is in the design and planning phase. No source code has been written yet. See CONTRIBUTING.md if you'd like to help build it.

Technology Stack

Layer	Choice	Constraint
Runtime	Node.js 22 LTS	Do NOT use APIs that require 23+
Language	TypeScript 5.x	Strict mode, no any without justification
CLI	Commander.js	One entry point: src/cli.ts → sdx binary
AST	Tree-sitter WASM	NOT native bindings. Language.load() from .wasm files
DB	better-sqlite3 + sqlite-vec	sqliteVec.load(db) — NOT node:sqlite (23.5+)
Hashing	hash-wasm	xxhash3() for content hashing
Embedding	Transformers.js v3.x	Xenova/all-MiniLM-L6-v2, q8 quantized, max 256 tokens input
Watcher	Chokidar	awaitWriteFinish: true, ignore node_modules
Telemetry	OpenTelemetry JS	Custom FileSpanExporter, manual instrumentation only
MCP SDK	@modelcontextprotocol/sdk	v1.29.0 (@release-1.29.0). Do NOT use v2 alpha
Testing	Vitest	In-memory SQLite for DB tests, no external deps

Architecture

src/
├── cli.ts              # Commander.js entry point
├── server.ts            # McpServer + tool registration
├── indexer/
│   ├── parser.ts        # Tree-sitter WASM → AST
│   ├── chunker.ts       # AST → canonical semantic nodes
│   ├── hasher.ts        # XXH3 content hashing
│   └── embedder.ts      # Transformers.js pipeline
├── db/
│   ├── connection.ts    # better-sqlite3 + sqlite-vec
│   ├── schema.ts        # Migration framework (PRAGMA user_version)
│   └── queries.ts       # Typed SQL query builders
├── tools/
│   ├── symbol.ts        # symbol.find, symbol.callers
│   ├── search.ts        # search.semantic, search.lexical
│   ├── repo.ts          # repo.manifest, repo.architecture
│   └── index.ts         # index.status, code.read
└── telemetry/
    ├── tracer.ts        # OpenTelemetry setup
    └── file-exporter.ts # Custom FileSpanExporter (~50 lines)

Getting Started

📝 Coming soon. Setup instructions will be added once initial source code is written.

Planned workflow:

sdx init               # Initialize index in current repo
sdx index --dry-run    # Preview what would be indexed
sdx serve              # Start MCP server (stdio transport)

Key Commands

npm run build          # tsc
npm run dev            # tsx src/cli.ts
npm test               # vitest
npm run lint           # eslint src/
npm run typecheck      # tsc --noEmit

sdx init               # Initialize index in current repo
sdx index --dry-run    # Preview what would be indexed
sdx serve              # Start MCP server (stdio transport)
sdx bench              # Run benchmarks
sdx bench --sla        # Check against SLA targets

Design Principles

1. Never fail silently. Every degraded mode must log a warning and produce useful results.
2. Lexical fallback beats an error. If embeddings fail, FTS5 is better than nothing.
3. Partial index beats no index. One broken file should never block the whole repo.
4. Content-addressable everything. Never recompute what hasn't changed.
5. Explicit over implicit. Schema migrations, model switches — all opt-in, never automatic.
6. Local only. No cloud, no telemetry phoning home, no API keys required.

Key Constraints

• all-MiniLM-L6-v2 max input: 256 tokens. Chunks longer than this must be split for embedding.
• sqlite-vec max dimensions: 8192. We use 384 — well within limits.
• Node 22 LTS only. No node:sqlite (requires 23.5+). Use better-sqlite3.
• WASM grammars only. No native Tree-sitter bindings — portable across macOS/Linux/Windows.
• MCP SDK v1.29.0 only. v2 is alpha. Migration is post-MVP.

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup, code conventions, and the pull request process.

Before contributing, please read our Code of Conduct and Security Policy.

License

MIT © 2026 Raghav Wahi