代码库语义搜索系统

npm install -g @teknologika/mcp-codebase-search

npm install @teknologika/mcp-codebase-search

npx mcp-codebase-ingest --path ./my-project --name my-project
npx mcp-codebase-search
npx mcp-codebase-manager

mcp-codebase-ingest --path ./my-project --name my-project

Ingesting codebase: my-project
Path: /Users/dev/projects/my-project

Scanning directory...
Parsing files...
Generating embeddings...
Storing chunks...

✓ Ingestion completed successfully!

  Total files scanned: 256
  Supported files: 253
  Chunks created: 2,022
  Duration: 29.7s

Languages detected:
  typescript: 1,800 chunks (200 files)
  javascript: 150 chunks (40 files)
  markdown: 72 chunks (13 files)

{
  "mcpServers": {
    "codebase-search": {
      "command": "mcp-codebase-search",
      "args": []
    }
  }
}

# AGENTS.md — Codebase Dedupe Protocol

## Goal
Prevent duplicate implementations and "wrong file" edits by making **codebase-search** the *only valid source* for claims about what already exists in this repo during this session.

## Tools you MUST use for codebase discovery
- `list_codebases`
- `search_codebases`
- `get_codebase_stats`
- `get_chunk_content`
- `get_file_content`
- `get_adjacent_chunks`
- `list_files`
- `update_codebase_scan`

After updates run `update_codebase_scan` to refresh the index.

## Hard rule: No creation without a Dedupe Ticket
Before adding a new file, module, class, function, or helper, produce a Dedupe Ticket:

**Dedupe Ticket**
- Intent signature: `<one sentence describing what you are about to add>`
- Queries: `<2–4 searches you will run>`
- Top matches: `<up to 5 file paths returned by the tool>`
- Decision: `reuse | extend | new`
- Rationale: `<why>`

## Graceful degradation
If the MCP server is unavailable: state **DEGRADED MODE** and stop before making changes.

mcp-codebase-manager

mcp-codebase-ingest --path <directory> --name <codebase-name>

# Index a local project
mcp-codebase-ingest --path ~/projects/my-app --name my-app

# Index with custom config
mcp-codebase-ingest --path ./backend --name backend-api --config ./custom-config.json

# Index without gitignore filtering
mcp-codebase-ingest --path ./my-project --name my-project --no-gitignore

# Re-index an existing codebase (old data is automatically replaced)
mcp-codebase-ingest --path ~/projects/my-app --name my-app

mcp-codebase-search

{
  "codebases": [
    {
      "name": "my-project",
      "path": "/path/to/project",
      "chunkCount": 2022,
      "fileCount": 253,
      "lastIngested": "2026-03-21T06:18:24Z",
      "lastModified": "2026-03-21T06:18:24Z",
      "lastScanAge": 57,
      "lastRescanChangedAt": "2026-03-21T06:18:24Z",
      "lastRescanFilesChanged": 4,
      "lastRescanFilesAdded": 1,
      "lastRescanFilesModified": 2,
      "lastRescanFilesDeleted": 1,
      "lastRescanChangedFilePaths": ["src/a.ts", "src/b.ts"],
      "languages": ["typescript", "javascript", "markdown"],
      "status": "active"
    }
  ]
}

{
  "query": "authentication function",
  "codebaseName": "my-project",
  "language": "typescript",
  "maxResults": 10,
  "includeContent": false,
  "topContentResults": 3
}

{
  "results": [
    {
      "filePath": "src/auth/authenticate.ts",
      "startLine": 15,
      "endLine": 45,
      "language": "typescript",
      "chunkType": "function",
      "similarityScore": 0.92
    }
  ],
  "totalResults": 1,
  "queryTime": 45,
  "staleWarning": "Index is 47 minutes old. Call update_codebase_scan('my-project') to refresh."
}

{
  "codebaseName": "my-project",
  "filePath": "src/auth/authenticate.ts",
  "startLine": 15,
  "endLine": 45
}

{
  "codebaseName": "my-project",
  "filePath": "src/auth/authenticate.ts",
  "startLine": 15,
  "endLine": 45,
  "language": "typescript",
  "chunkType": "function",
  "content": "export async function authenticate(...) { ... }",
  "lineNumberDrift": 0
}

{
  "codebaseName": "my-project",
  "filePath": "src/auth/authenticate.ts"
}

{
  "codebaseName": "my-project",
  "filePath": "src/auth/authenticate.ts",
  "language": "typescript",
  "content": "// full file content...",
  "chunkCount": 8,
  "totalLines": 245
}

{
  "codebaseName": "my-project",
  "filePath": "src/auth/authenticate.ts",
  "startLine": 15,
  "endLine": 45,
  "before": 1,
  "after": 1
}

{
  "before": [
    {
      "startLine": 1,
      "endLine": 14,
      "chunkType": "function",
      "content": "..."
    }
  ],
  "reference": {
    "startLine": 15,
    "endLine": 45,
    "chunkType": "method"
  },
  "after": [
    {
      "startLine": 46,
      "endLine": 60,
      "chunkType": "method",
      "content": "..."
    }
  ]
}

{
  "codebaseName": "my-project"
}

{
  "files": [
    {
      "filePath": "src/auth/authenticate.ts",
      "language": "typescript",
      "chunkCount": 8,
      "lastIngestion": "2026-03-21T06:18:24Z",
      "sizeBytes": 4521,
      "isTestFile": false,
      "isLibraryFile": false,
      "fileHash": "a1b2c3d4..."
    }
  ],
  "codebaseName": "my-project",
  "totalFiles": 253
}

{
  "name": "my-project"
}

{
  "name": "my-project",
  "path": "/path/to/project",
  "chunkCount": 2022,
  "fileCount": 253,
  "lastIngestion": "2026-03-21T06:18:24Z",
  "languages": [
    { "language": "typescript", "fileCount": 200, "chunkCount": 1800 }
  ],
  "chunkTypes": [
    { "type": "function", "count": 800 },
    { "type": "method", "count": 1022 }
  ],
  "sizeBytes": 1250000
}

{
  "name": "my-project",
  "verbose": false
}

{
  "name": "my-project",
  "filesScanned": 253,
  "filesAdded": 2,
  "filesModified": 5,
  "filesDeleted": 1,
  "filesUnchanged": 245,
  "filesIndexed": 250,
  "filesDropped": 3,
  "chunksAdded": 18,
  "chunksDeleted": 12,
  "durationMs": 644,
  "cacheCleared": true,
  "message": "Successfully refreshed codebase 'my-project': 2 added, 5 modified, 1 deleted, 245 unchanged, 250 indexed"
}

{
  "url": "http://localhost:8008",
  "message": "Opening codebase manager at http://localhost:8008",
  "serverStarted": true
}

mcp-codebase-manager

{
  "lancedb": {
    "persistPath": "~/.codebase-memory/lancedb"
  },
  "embedding": {
    "modelName": "Xenova/all-MiniLM-L6-v2",
    "cachePath": "~/.codebase-memory/models"
  },
  "server": {
    "port": 8008,
    "host": "localhost",
    "sessionSecret": "change-me-in-production"
  },
  "mcp": {
    "transport": "stdio"
  },
  "ingestion": {
    "batchSize": 100,
    "maxFileSize": 1048576,
    "maxChunkTokens": 512,
    "chunkOverlapTokens": 50,
    "storeFullFiles": true
  },
  "search": {
    "defaultMaxResults": 50,
    "cacheTimeoutSeconds": 60
  },
  "logging": {
    "level": "info"
  },
  "schemaVersion": "1.0.0"
}

{
  "mcpServers": {
    "codebase-search": {
      "command": "mcp-codebase-search",
      "args": []
    }
  }
}

{
  "mcpServers": {
    "codebase-search": {
      "command": "mcp-codebase-search",
      "args": [],
      "env": {
        "CONFIG_PATH": "~/.codebase-memory/config.json",
        "LOG_LEVEL": "info"
      }
    }
  }
}

┌─────────────────────────────────────────────────────────────┐
│                     Entry Points                             │
├──────────────┬──────────────────┬──────────────────────────┤
│  MCP Server  │  Ingestion CLI   │     Manager UI           │
│  (stdio)     │  (command-line)  │  (Fastify + Handlebars)  │
└──────┬───────┴────────┬─────────┴──────────┬───────────────┘
       │                │                    │
┌──────▼────────────────▼────────────────────▼───────────────┐
│                   Core Services                             │
├─────────────┬──────────────┬──────────────┬────────────────┤
│  Codebase   │    Search    │  Ingestion   │   Embedding    │
│  Service    │   Service    │   Service    │    Service     │
└──────┬──────┴──────┬───────┴──────┬───────┴────────┬───────┘
       │             │              │                │
┌──────▼─────────────▼──────────────▼────────────────▼───────┐
│                   Storage & Parsing                         │
├──────────────┬──────────────────┬─────────────────────────┤
│   LanceDB    │  Tree-sitter     │  Hugging Face           │
│ (Vector DB)  │  (Code Parsing)  │  (Embeddings, local)    │
└──────────────┴──────────────────┴─────────────────────────┘

Source Code → File Scanner → Tree-sitter Parser → Semantic Chunks
                                                         ↓
                                                  Token Counter
                                                         ↓
                                              Split Oversized Chunks
                                                         ↓
                                                 File Classifier
                                                         ↓
LanceDB ← Embeddings ← Embedding Service ← Tagged Chunks

Query → Embedding Service → Vector
                              ↓
                         LanceDB Search (top N×10 candidates)
                              ↓
                         Name/Symbol Boost (re-rank)
                              ↓
                         Apply Filters → Trim to N → Response

{
  "id": "my-project_2026-03-21T06:18:24Z_0",
  "vector": [0.1, 0.2, "..."],
  "content": "export async function authenticate(...) { ... }",
  "filePath": "src/auth.ts",
  "startLine": 15,
  "endLine": 45,
  "language": "typescript",
  "chunkType": "function",
  "isTestFile": false,
  "isLibraryFile": false,
  "fileHash": "a1b2c3d4...",
  "fullFileContent": "// complete file content",
  "ingestionTimestamp": "2026-03-21T06:18:24Z",
  "_codebaseName": "my-project",
  "_path": "/path/to/project",
  "_lastIngestion": "2026-03-21T06:18:24Z"
}

npm install -g @teknologika/mcp-codebase-search
# or use npx
npx mcp-codebase-search

# Check permissions
ls -la ~/.codebase-memory/lancedb

# Reset LanceDB (WARNING: deletes all indexed data)
rm -rf ~/.codebase-memory/lancedb

# Re-ingest
mcp-codebase-ingest --path ./my-project --name my-project

# Check available disk space (~500MB needed)
df -h ~/.codebase-memory

# Clear model cache and retry
rm -rf ~/.codebase-memory/models
mcp-codebase-ingest --path ./my-project --name my-project

# Instead of: "validateEmailAddress"
# Try: "email validation function"

# Check what's using port 8008
lsof -i :8008

# Use a different port in config
# ~/.codebase-memory/config.json
{ "server": { "port": 8009 } }

git clone https://github.com/teknologika/mcp-codebase-search.git
cd mcp-codebase-search
npm install
npm run build

npm run build          # Compile TypeScript + copy UI assets
npm test               # Run all tests
npm run test:watch     # Watch mode
npm run test:coverage  # Coverage report
npm run lint           # ESLint
npm run lint:fix       # Auto-fix lint issues
npm run clean          # Remove build artifacts
npm run typecheck      # Type check without building

src/
├── bin/                    # Entry points (mcp-server, ingest, manager)
├── domains/                # Domain business logic
│   ├── codebase/           # Codebase CRUD and file operations
│   ├── search/             # Semantic search with caching
│   ├── ingestion/          # File scanning and indexing pipeline
│   ├── embedding/          # Local embedding generation
│   └── parsing/            # Tree-sitter + plaintext fallback parsers
├── infrastructure/         # External integrations
│   ├── lancedb/            # LanceDB client wrapper
│   ├── mcp/                # MCP server and tool schemas
│   └── fastify/            # Manager UI server and routes
├── shared/                 # Shared utilities
│   ├── config/             # Configuration management
│   ├── logging/            # Structured logging (Pino)
│   ├── types/              # Shared TypeScript types
│   └── utils/              # File hashing, token counting, classification
└── ui/                     # Web interface
    └── manager/
        ├── templates/      # Handlebars templates
        └── static/         # CSS and JavaScript