yacodebase-mcp 0.1.0__tar.gz

yacodebase_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+      - name: Run tests
+        run: uv run pytest -v

yacodebase_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing (OIDC)
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

yacodebase_mcp-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/

yacodebase_mcp-0.1.0/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

yacodebase_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,77 @@
+# codebase-mcp — dev guide
+
+## Setup
+
+```bash
+uv sync
+```
+
+All commands use `.venv/bin/` prefix or `uv run`.
+
+## Run tests
+
+```bash
+.venv/bin/pytest
+.venv/bin/pytest -v
+.venv/bin/pytest tests/test_ast_chunker.py -v   # specific module
+```
+
+## Lint / format
+
+```bash
+.venv/bin/ruff check src tests
+.venv/bin/ruff format src tests
+```
+
+Line length: 100. Rules: E, F, I (pycodestyle, pyflakes, isort).
+
+## Project structure
+
+```
+src/codebase_mcp/
+  cli.py          # Click CLI: index, reindex, list, remove, serve, config *
+  server.py       # FastMCP server — exposes search_codebase + list_indexed_repos
+  indexer.py      # File walking, chunking, embedding, Qdrant upsert
+  ast_chunker.py  # tree-sitter AST chunking (function/method boundaries)
+  searcher.py     # Query embedding + Qdrant search + result formatting
+  store.py        # Qdrant client, config.json r/w, repo metadata
+  settings.py     # settings.json r/w (embedding model, vector size, api_key, api_base)
+tests/
+  test_ast_chunker.py
+  test_cli.py
+  test_indexer.py
+  test_integration.py
+  test_searcher.py
+  test_settings.py
+  test_store.py
+```
+
+## Key design decisions
+
+**AST chunking → line fallback**: `indexer.chunk_file` tries `ast_chunker.chunk_file_ast` first. If the language is unsupported or tree-sitter fails, falls back to 100-line sliding window (20-line overlap). This ensures semantic boundaries for supported languages without breaking on unknown file types.
+
+**In-process Qdrant**: No external service needed. `store.get_client()` returns a `QdrantClient` pointing at `~/.codebase-mcp/qdrant/`. One collection per repo, named by `repo_id` (hash of abs path).
+
+**OpenAI-compatible embeddings**: `indexer` and `searcher` both instantiate `openai.OpenAI(api_key=..., base_url=...)` from settings. Any OpenAI-compatible provider works by setting `api_base`.
+
+**Vector size mismatch detection**: `searcher.search` reads actual vector dim from Qdrant and skips repos where it doesn't match current model's `vector_size`. Emits a warning prompting reindex.
+
+**MAX_CHUNK_CHARS = 16000**: Both `ast_chunker` and `indexer` truncate chunk text at 16k chars (~8192 tokens at 2 chars/token for dense code). Applied post-collection in `indexer.index_repo` as final safety.
+
+**Config precedence**: `settings.json` fields override env vars. `api_key=None` in settings → falls back to `OPENAI_API_KEY` env var (handled by OpenAI SDK). `api_base=None` → uses OpenAI default.
+
+## Adding a new language
+
+1. Add tree-sitter grammar to `pyproject.toml` dependencies.
+2. Add entry to `ast_chunker.EXT_TO_LANG` mapping extension → language name.
+3. Add entry to `ast_chunker.SEMANTIC_NODES` mapping language → relevant node type set.
+4. Add parser instantiation branch in `ast_chunker._get_parser`.
+5. Add extension to `indexer.INDEXED_EXTENSIONS`.
+
+## Data dir
+
+`~/.codebase-mcp/` — created on first use by `store._data_dir()`.
+
+- `config.json` — repo registry: `{abs_path: {repo_id, chunk_count, last_indexed}}`
+- `settings.json` — persistent settings (only non-null, non-default values written)
+- `qdrant/` — Qdrant on-disk storage

yacodebase_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 gzamboni
+
+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.

yacodebase_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: yacodebase-mcp
+Version: 0.1.0
+Summary: CLI + MCP server that indexes local codebases into Qdrant using OpenAI-compatible embeddings, then exposes semantic search to Claude Code and other MCP clients
+Project-URL: Homepage, https://github.com/gzamboni/codebase-mcp
+Project-URL: Repository, https://github.com/gzamboni/codebase-mcp
+Project-URL: Issues, https://github.com/gzamboni/codebase-mcp/issues
+Author-email: gzamboni <gzamboni@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: claude,codebase,embeddings,mcp,qdrant,semantic-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: openai>=1.0
+Requires-Dist: qdrant-client>=1.9
+Requires-Dist: rich>=13.0
+Requires-Dist: tree-sitter-go>=0.23
+Requires-Dist: tree-sitter-hcl>=0.23
+Requires-Dist: tree-sitter-java>=0.23
+Requires-Dist: tree-sitter-javascript>=0.23
+Requires-Dist: tree-sitter-python>=0.23
+Requires-Dist: tree-sitter-rust>=0.23
+Requires-Dist: tree-sitter-typescript>=0.23
+Requires-Dist: tree-sitter>=0.23
+Description-Content-Type: text/markdown
+
+# codebase-mcp
+
+Vector search MCP server for codebases. Index repos locally with AST-aware chunking; let Claude (or any MCP client) search them via semantic similarity.
+
+## How it works
+
+1. **Index** — walks repo files, chunks them using tree-sitter AST (function/method boundaries) with line-based fallback, embeds via OpenAI-compatible API, stores in in-process Qdrant.
+2. **Serve** — exposes two MCP tools (`search_codebase`, `list_indexed_repos`) over stdio.
+3. **Search** — embeds the query, retrieves top-8 chunks across all indexed repos (or a specific one), returns ranked results with file path and line numbers.
+
+## Install
+
+```bash
+uv tool install /path/to/codebase-mcp
+```
+
+Or for development:
+
+```bash
+uv sync
+```
+
+## CLI
+
+```bash
+# Index a repo (fails if already indexed)
+codebase-mcp index ~/Code/myproject
+
+# Re-index after changes (replaces existing index)
+codebase-mcp reindex ~/Code/myproject
+
+# List indexed repos with chunk counts
+codebase-mcp list
+
+# Remove a repo from the index
+codebase-mcp remove ~/Code/myproject
+
+# Start MCP server (stdio, used by Claude Code)
+codebase-mcp serve
+```
+
+### Config commands
+
+```bash
+# Show current settings
+codebase-mcp config list
+
+# Set embedding model (known models auto-resolve vector size)
+codebase-mcp config set embedding-model text-embedding-3-large
+codebase-mcp config set embedding-model my-custom-model --vector-size 768
+
+# Set API credentials
+codebase-mcp config set api-key sk-...
+codebase-mcp config set api-base https://my-provider.com/v1
+
+# Revert a setting to default / env var fallback
+codebase-mcp config unset embedding-model
+codebase-mcp config unset api-key
+codebase-mcp config unset api-base
+```
+
+**Known models** (vector size auto-detected):
+
+| Model | Vector size |
+|---|---|
+| `text-embedding-3-small` | 1536 |
+| `text-embedding-3-large` | 3072 |
+| `text-embedding-ada-002` | 1536 |
+
+Default: `text-embedding-3-small`.
+
+## Claude Code config
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "codebase-search": {
+      "command": "codebase-mcp",
+      "args": ["serve"],
+      "env": { "OPENAI_API_KEY": "sk-..." }
+    }
+  }
+}
+```
+
+API key can also be set via `codebase-mcp config set api-key sk-...` (persisted in `~/.codebase-mcp/settings.json`), which takes precedence over the env var.
+
+## MCP tools
+
+### `search_codebase`
+
+Search indexed repos for relevant code and docs.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `query` | string | Natural language description of what to find |
+| `repo_path` | string (optional) | Absolute path to a specific repo; omit to search all |
+
+Returns top-8 results ranked by similarity, each with file path, line range, score, and code block.
+
+### `list_indexed_repos`
+
+List all indexed repos with chunk count and last indexed timestamp. No parameters.
+
+## Supported languages (AST chunking)
+
+| Language | Extensions | Chunk boundary |
+|---|---|---|
+| Python | `.py` | `function_definition`, `decorated_definition` |
+| TypeScript | `.ts` | `function_declaration`, `method_definition`, `arrow_function` |
+| TSX | `.tsx` | same as TypeScript |
+| JavaScript | `.js`, `.jsx` | `function_declaration`, `method_definition`, `arrow_function` |
+| Go | `.go` | `function_declaration`, `method_declaration` |
+| Rust | `.rs` | `function_item` |
+| Java | `.java` | `method_declaration`, `constructor_declaration` |
+| HCL/Terraform | `.tf` | `block` |
+
+Files without AST support (`.md`, `.yaml`, `.toml`, `.json`, `.rb`, `.cpp`, `.c`, `.h`) fall back to 100-line sliding window with 20-line overlap.
+
+## Data storage
+
+All data lives in `~/.codebase-mcp/`:
+
+```
+~/.codebase-mcp/
+  config.json      # indexed repo metadata (paths, repo_ids, chunk counts, timestamps)
+  settings.json    # embedding model, vector size, api_key, api_base
+  qdrant/          # Qdrant in-process storage (one collection per repo)
+```
+
+Each repo gets a stable `repo_id` derived from its absolute path (used as Qdrant collection name). Reindexing replaces the collection in-place.
+
+## OpenAI-compatible providers
+
+Set `api-base` to use any OpenAI-compatible embedding API (e.g. Ollama, vLLM, Azure):
+
+```bash
+codebase-mcp config set api-base http://localhost:11434/v1
+codebase-mcp config set api-key ollama
+codebase-mcp config set embedding-model nomic-embed-text --vector-size 768
+```
+
+After changing the model, reindex all repos (vector dimensions must match).

yacodebase_mcp-0.1.0/README.md

@@ -0,0 +1,145 @@
+# codebase-mcp
+
+Vector search MCP server for codebases. Index repos locally with AST-aware chunking; let Claude (or any MCP client) search them via semantic similarity.
+
+## How it works
+
+1. **Index** — walks repo files, chunks them using tree-sitter AST (function/method boundaries) with line-based fallback, embeds via OpenAI-compatible API, stores in in-process Qdrant.
+2. **Serve** — exposes two MCP tools (`search_codebase`, `list_indexed_repos`) over stdio.
+3. **Search** — embeds the query, retrieves top-8 chunks across all indexed repos (or a specific one), returns ranked results with file path and line numbers.
+
+## Install
+
+```bash
+uv tool install /path/to/codebase-mcp
+```
+
+Or for development:
+
+```bash
+uv sync
+```
+
+## CLI
+
+```bash
+# Index a repo (fails if already indexed)
+codebase-mcp index ~/Code/myproject
+
+# Re-index after changes (replaces existing index)
+codebase-mcp reindex ~/Code/myproject
+
+# List indexed repos with chunk counts
+codebase-mcp list
+
+# Remove a repo from the index
+codebase-mcp remove ~/Code/myproject
+
+# Start MCP server (stdio, used by Claude Code)
+codebase-mcp serve
+```
+
+### Config commands
+
+```bash
+# Show current settings
+codebase-mcp config list
+
+# Set embedding model (known models auto-resolve vector size)
+codebase-mcp config set embedding-model text-embedding-3-large
+codebase-mcp config set embedding-model my-custom-model --vector-size 768
+
+# Set API credentials
+codebase-mcp config set api-key sk-...
+codebase-mcp config set api-base https://my-provider.com/v1
+
+# Revert a setting to default / env var fallback
+codebase-mcp config unset embedding-model
+codebase-mcp config unset api-key
+codebase-mcp config unset api-base
+```
+
+**Known models** (vector size auto-detected):
+
+| Model | Vector size |
+|---|---|
+| `text-embedding-3-small` | 1536 |
+| `text-embedding-3-large` | 3072 |
+| `text-embedding-ada-002` | 1536 |
+
+Default: `text-embedding-3-small`.
+
+## Claude Code config
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "codebase-search": {
+      "command": "codebase-mcp",
+      "args": ["serve"],
+      "env": { "OPENAI_API_KEY": "sk-..." }
+    }
+  }
+}
+```
+
+API key can also be set via `codebase-mcp config set api-key sk-...` (persisted in `~/.codebase-mcp/settings.json`), which takes precedence over the env var.
+
+## MCP tools
+
+### `search_codebase`
+
+Search indexed repos for relevant code and docs.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `query` | string | Natural language description of what to find |
+| `repo_path` | string (optional) | Absolute path to a specific repo; omit to search all |
+
+Returns top-8 results ranked by similarity, each with file path, line range, score, and code block.
+
+### `list_indexed_repos`
+
+List all indexed repos with chunk count and last indexed timestamp. No parameters.
+
+## Supported languages (AST chunking)
+
+| Language | Extensions | Chunk boundary |
+|---|---|---|
+| Python | `.py` | `function_definition`, `decorated_definition` |
+| TypeScript | `.ts` | `function_declaration`, `method_definition`, `arrow_function` |
+| TSX | `.tsx` | same as TypeScript |
+| JavaScript | `.js`, `.jsx` | `function_declaration`, `method_definition`, `arrow_function` |
+| Go | `.go` | `function_declaration`, `method_declaration` |
+| Rust | `.rs` | `function_item` |
+| Java | `.java` | `method_declaration`, `constructor_declaration` |
+| HCL/Terraform | `.tf` | `block` |
+
+Files without AST support (`.md`, `.yaml`, `.toml`, `.json`, `.rb`, `.cpp`, `.c`, `.h`) fall back to 100-line sliding window with 20-line overlap.
+
+## Data storage
+
+All data lives in `~/.codebase-mcp/`:
+
+```
+~/.codebase-mcp/
+  config.json      # indexed repo metadata (paths, repo_ids, chunk counts, timestamps)
+  settings.json    # embedding model, vector size, api_key, api_base
+  qdrant/          # Qdrant in-process storage (one collection per repo)
+```
+
+Each repo gets a stable `repo_id` derived from its absolute path (used as Qdrant collection name). Reindexing replaces the collection in-place.
+
+## OpenAI-compatible providers
+
+Set `api-base` to use any OpenAI-compatible embedding API (e.g. Ollama, vLLM, Azure):
+
+```bash
+codebase-mcp config set api-base http://localhost:11434/v1
+codebase-mcp config set api-key ollama
+codebase-mcp config set embedding-model nomic-embed-text --vector-size 768
+```
+
+After changing the model, reindex all repos (vector dimensions must match).