# Semdex

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

[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Node Version](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](package.json)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

## 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](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:

```bash
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

```bash
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](CONTRIBUTING.md) for development setup, code conventions, and the pull request process.

Before contributing, please read our [Code of Conduct](CODE_OF_CONDUCT.md) and [Security Policy](SECURITY.md).

## License

[MIT](LICENSE) © 2026 Raghav Wahi