mcp-codebase-index 0.1.1__tar.gz

mcp_codebase_index-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+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: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src/ tests/
+
+      - name: Run tests
+        run: pytest tests/ -v

mcp_codebase_index-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish release assets
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload assets to release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release upload "${{ github.event.release.tag_name }}" dist/*
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*

mcp_codebase_index-0.1.1/.gitignore

@@ -0,0 +1,57 @@
+# ── Secrets & credentials ──────────────────────
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.crt
+*.p12
+*.pfx
+*.jks
+credentials.json
+service-account*.json
+*secret*
+!*secret*.py
+
+# ── Python ─────────────────────────────────────
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+*.so
+*.whl
+
+# ── Virtual environments ───────────────────────
+.venv/
+venv/
+env/
+ENV/
+
+# ── IDE & editor ───────────────────────────────
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# ── Testing & linting ─────────────────────────
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+
+# ── Claude Code local state ───────────────────
+.claude/
+
+# ── Misc ───────────────────────────────────────
+*.log
+*.bak
+*.tmp

mcp_codebase_index-0.1.1/LICENSE

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

mcp_codebase_index-0.1.1/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: mcp-codebase-index
+Version: 0.1.1
+Summary: Structural codebase indexer with MCP server for AI-assisted development
+Project-URL: Homepage, https://github.com/MikeRecognex/mcp-codebase-index
+Project-URL: Repository, https://github.com/MikeRecognex/mcp-codebase-index
+Author: Michael Doyle
+License: MIT License
+        
+        Copyright (c) 2026 Michael Doyle
+        
+        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.
+License-File: LICENSE
+Keywords: code-navigation,codebase,indexer,mcp,structural-analysis
+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
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# mcp-codebase-index
+
+A structural codebase indexer with an [MCP](https://modelcontextprotocol.io) server for AI-assisted development. Zero runtime dependencies — uses Python's `ast` module for Python analysis and regex for TypeScript/JS. Requires Python 3.11+.
+
+## What It Does
+
+Indexes codebases by parsing source files into structural metadata -- functions, classes, imports, dependency graphs, and cross-file call chains -- then exposes 17 query tools via the Model Context Protocol, enabling Claude Code and other MCP clients to navigate codebases efficiently without reading entire files.
+
+## Language Support
+
+| Language | Method | Extracts |
+|----------|--------|----------|
+| Python (`.py`) | AST parsing | Functions, classes, methods, imports, dependency graph |
+| TypeScript/JS (`.ts`, `.tsx`, `.js`, `.jsx`) | Regex-based | Functions, arrow functions, classes, interfaces, type aliases, imports |
+| Markdown/Text (`.md`, `.txt`, `.rst`) | Heading detection | Sections (# headings, underlines, numbered, ALL-CAPS) |
+| Other | Generic | Line counts only |
+
+## Installation
+
+```bash
+pip install "mcp-codebase-index[mcp]"
+```
+
+The `[mcp]` extra includes the MCP server dependency. Omit it if you only need the programmatic API.
+
+For development (from a local clone):
+
+```bash
+pip install -e ".[dev,mcp]"
+```
+
+## MCP Server
+
+### Running
+
+```bash
+# As a console script
+PROJECT_ROOT=/path/to/project mcp-codebase-index
+
+# As a Python module
+PROJECT_ROOT=/path/to/project python -m mcp_codebase_index.server
+```
+
+`PROJECT_ROOT` specifies which directory to index. Defaults to the current working directory.
+
+### Configuring with Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "codebase-index": {
+      "command": "mcp-codebase-index",
+      "env": {
+        "PROJECT_ROOT": "/path/to/project"
+      }
+    }
+  }
+}
+```
+
+Or using the Python module directly (useful if installed in a virtualenv):
+
+```json
+{
+  "mcpServers": {
+    "codebase-index": {
+      "command": "/path/to/.venv/bin/python3",
+      "args": ["-m", "mcp_codebase_index.server"],
+      "env": {
+        "PROJECT_ROOT": "/path/to/project"
+      }
+    }
+  }
+}
+```
+
+### Available Tools (17)
+
+| Tool | Description |
+|------|-------------|
+| `get_project_summary` | File count, packages, top classes/functions |
+| `list_files` | List indexed files with optional glob filter |
+| `get_structure_summary` | Structure of a file or the whole project |
+| `get_functions` | List functions with name, lines, params |
+| `get_classes` | List classes with name, lines, methods, bases |
+| `get_imports` | List imports with module, names, line |
+| `get_function_source` | Full source of a function/method |
+| `get_class_source` | Full source of a class |
+| `find_symbol` | Find where a symbol is defined (file, line, type) |
+| `get_dependencies` | What a symbol calls/uses |
+| `get_dependents` | What calls/uses a symbol |
+| `get_change_impact` | Direct + transitive dependents |
+| `get_call_chain` | Shortest dependency path (BFS) |
+| `get_file_dependencies` | Files imported by a given file |
+| `get_file_dependents` | Files that import from a given file |
+| `search_codebase` | Regex search across all files (max 100 results) |
+| `reindex` | Re-index the project after file changes (MCP server only) |
+
+## Programmatic Usage
+
+```python
+from mcp_codebase_index.project_indexer import ProjectIndexer
+from mcp_codebase_index.query_api import create_project_query_functions
+
+indexer = ProjectIndexer("/path/to/project", include_patterns=["**/*.py"])
+index = indexer.index()
+query_funcs = create_project_query_functions(index)
+
+# Use query functions
+print(query_funcs["get_project_summary"]())
+print(query_funcs["find_symbol"]("MyClass"))
+print(query_funcs["get_change_impact"]("some_function"))
+```
+
+## Development
+
+```bash
+pip install -e ".[dev,mcp]"
+pytest tests/ -v
+ruff check src/ tests/
+```
+
+## References
+
+The structural indexer was originally developed as part of the [RMLPlus](https://github.com/MikeRecognex/RMLPlus) project, an implementation of the [Recursive Language Models](https://arxiv.org/abs/2512.24601) framework.
+
+## License
+
+MIT

mcp_codebase_index-0.1.1/README.md

@@ -0,0 +1,131 @@
+# mcp-codebase-index
+
+A structural codebase indexer with an [MCP](https://modelcontextprotocol.io) server for AI-assisted development. Zero runtime dependencies — uses Python's `ast` module for Python analysis and regex for TypeScript/JS. Requires Python 3.11+.
+
+## What It Does
+
+Indexes codebases by parsing source files into structural metadata -- functions, classes, imports, dependency graphs, and cross-file call chains -- then exposes 17 query tools via the Model Context Protocol, enabling Claude Code and other MCP clients to navigate codebases efficiently without reading entire files.
+
+## Language Support
+
+| Language | Method | Extracts |
+|----------|--------|----------|
+| Python (`.py`) | AST parsing | Functions, classes, methods, imports, dependency graph |
+| TypeScript/JS (`.ts`, `.tsx`, `.js`, `.jsx`) | Regex-based | Functions, arrow functions, classes, interfaces, type aliases, imports |
+| Markdown/Text (`.md`, `.txt`, `.rst`) | Heading detection | Sections (# headings, underlines, numbered, ALL-CAPS) |
+| Other | Generic | Line counts only |
+
+## Installation
+
+```bash
+pip install "mcp-codebase-index[mcp]"
+```
+
+The `[mcp]` extra includes the MCP server dependency. Omit it if you only need the programmatic API.
+
+For development (from a local clone):
+
+```bash
+pip install -e ".[dev,mcp]"
+```
+
+## MCP Server
+
+### Running
+
+```bash
+# As a console script
+PROJECT_ROOT=/path/to/project mcp-codebase-index
+
+# As a Python module
+PROJECT_ROOT=/path/to/project python -m mcp_codebase_index.server
+```
+
+`PROJECT_ROOT` specifies which directory to index. Defaults to the current working directory.
+
+### Configuring with Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "codebase-index": {
+      "command": "mcp-codebase-index",
+      "env": {
+        "PROJECT_ROOT": "/path/to/project"
+      }
+    }
+  }
+}
+```
+
+Or using the Python module directly (useful if installed in a virtualenv):
+
+```json
+{
+  "mcpServers": {
+    "codebase-index": {
+      "command": "/path/to/.venv/bin/python3",
+      "args": ["-m", "mcp_codebase_index.server"],
+      "env": {
+        "PROJECT_ROOT": "/path/to/project"
+      }
+    }
+  }
+}
+```
+
+### Available Tools (17)
+
+| Tool | Description |
+|------|-------------|
+| `get_project_summary` | File count, packages, top classes/functions |
+| `list_files` | List indexed files with optional glob filter |
+| `get_structure_summary` | Structure of a file or the whole project |
+| `get_functions` | List functions with name, lines, params |
+| `get_classes` | List classes with name, lines, methods, bases |
+| `get_imports` | List imports with module, names, line |
+| `get_function_source` | Full source of a function/method |
+| `get_class_source` | Full source of a class |
+| `find_symbol` | Find where a symbol is defined (file, line, type) |
+| `get_dependencies` | What a symbol calls/uses |
+| `get_dependents` | What calls/uses a symbol |
+| `get_change_impact` | Direct + transitive dependents |
+| `get_call_chain` | Shortest dependency path (BFS) |
+| `get_file_dependencies` | Files imported by a given file |
+| `get_file_dependents` | Files that import from a given file |
+| `search_codebase` | Regex search across all files (max 100 results) |
+| `reindex` | Re-index the project after file changes (MCP server only) |
+
+## Programmatic Usage
+
+```python
+from mcp_codebase_index.project_indexer import ProjectIndexer
+from mcp_codebase_index.query_api import create_project_query_functions
+
+indexer = ProjectIndexer("/path/to/project", include_patterns=["**/*.py"])
+index = indexer.index()
+query_funcs = create_project_query_functions(index)
+
+# Use query functions
+print(query_funcs["get_project_summary"]())
+print(query_funcs["find_symbol"]("MyClass"))
+print(query_funcs["get_change_impact"]("some_function"))
+```
+
+## Development
+
+```bash
+pip install -e ".[dev,mcp]"
+pytest tests/ -v
+ruff check src/ tests/
+```
+
+## References
+
+The structural indexer was originally developed as part of the [RMLPlus](https://github.com/MikeRecognex/RMLPlus) project, an implementation of the [Recursive Language Models](https://arxiv.org/abs/2512.24601) framework.
+
+## License
+
+MIT

mcp_codebase_index-0.1.1/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-codebase-index"
+version = "0.1.1"
+description = "Structural codebase indexer with MCP server for AI-assisted development"
+requires-python = ">=3.11"
+readme = "README.md"
+license = {file = "LICENSE"}
+authors = [
+    {name = "Michael Doyle"},
+]
+keywords = ["mcp", "codebase", "indexer", "code-navigation", "structural-analysis"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.0"]
+dev = ["pytest>=8.0", "ruff>=0.5"]
+
+[project.scripts]
+mcp-codebase-index = "mcp_codebase_index.server:main_sync"
+
+[project.urls]
+Homepage = "https://github.com/MikeRecognex/mcp-codebase-index"
+Repository = "https://github.com/MikeRecognex/mcp-codebase-index"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_codebase_index"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+timeout = 30
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.mypy]
+python_version = "3.11"
+strict = true

mcp_codebase_index-0.1.1/src/mcp_codebase_index/__init__.py

@@ -0,0 +1,3 @@
+"""Structural codebase indexer with MCP server for AI-assisted development."""
+
+__version__ = "0.1.1"

mcp_codebase_index-0.1.1/src/mcp_codebase_index/annotator.py

@@ -0,0 +1,51 @@
+"""Dispatch layer that selects the appropriate annotator by file type."""
+
+from mcp_codebase_index.generic_annotator import annotate_generic
+from mcp_codebase_index.models import StructuralMetadata
+from mcp_codebase_index.python_annotator import annotate_python
+from mcp_codebase_index.text_annotator import annotate_text
+from mcp_codebase_index.typescript_annotator import annotate_typescript
+
+_EXTENSION_MAP: dict[str, str] = {
+    ".py": "python",
+    ".pyw": "python",
+    ".md": "text",
+    ".txt": "text",
+    ".rst": "text",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".js": "javascript",
+    ".jsx": "javascript",
+}
+
+
+def annotate(
+    text: str,
+    source_name: str = "<source>",
+    file_type: str | None = None,
+) -> StructuralMetadata:
+    """Annotate text with structural metadata.
+
+    Dispatch rules:
+    - file_type overrides extension-based detection
+    - .py -> python annotator
+    - .md, .txt, .rst -> text annotator
+    - .ts, .tsx -> typescript annotator
+    - .js, .jsx -> typescript annotator (close enough for regex-based parsing)
+    - Otherwise -> generic annotator (line-only)
+    """
+    if file_type is None:
+        # Detect from source_name extension
+        dot_idx = source_name.rfind(".")
+        if dot_idx >= 0:
+            ext = source_name[dot_idx:].lower()
+            file_type = _EXTENSION_MAP.get(ext)
+
+    if file_type == "python":
+        return annotate_python(text, source_name)
+    elif file_type == "text":
+        return annotate_text(text, source_name)
+    elif file_type in ("typescript", "javascript"):
+        return annotate_typescript(text, source_name)
+    else:
+        return annotate_generic(text, source_name)

mcp_codebase_index-0.1.1/src/mcp_codebase_index/generic_annotator.py

@@ -0,0 +1,21 @@
+"""Generic fallback annotator providing line-only metadata."""
+
+from mcp_codebase_index.models import StructuralMetadata
+
+
+def annotate_generic(text: str, source_name: str = "<source>") -> StructuralMetadata:
+    """Create minimal structural metadata with just line information."""
+    lines = text.splitlines()
+    offsets: list[int] = []
+    offset = 0
+    for line in lines:
+        offsets.append(offset)
+        offset += len(line) + 1  # +1 for newline
+
+    return StructuralMetadata(
+        source_name=source_name,
+        total_lines=len(lines),
+        total_chars=len(text),
+        lines=lines,
+        line_char_offsets=offsets,
+    )

mcp_codebase_index-0.1.1/src/mcp_codebase_index/models.py

@@ -0,0 +1,110 @@
+"""Structural metadata models for codebase indexing."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class LineRange:
+    """A range of lines (1-indexed, inclusive on both ends)."""
+
+    start: int
+    end: int
+
+
+@dataclass(frozen=True)
+class FunctionInfo:
+    """Metadata about a function or method."""
+
+    name: str
+    qualified_name: str  # e.g., "MyClass.my_method"
+    line_range: LineRange
+    parameters: list[str]
+    decorators: list[str]  # Decorator names (without @)
+    docstring: str | None
+    is_method: bool
+    parent_class: str | None  # None for top-level functions
+
+
+@dataclass(frozen=True)
+class ClassInfo:
+    """Metadata about a class."""
+
+    name: str
+    line_range: LineRange
+    base_classes: list[str]
+    methods: list[FunctionInfo]
+    decorators: list[str]
+    docstring: str | None
+
+
+@dataclass(frozen=True)
+class ImportInfo:
+    """Metadata about an import statement."""
+
+    module: str  # e.g., "os.path"
+    names: list[str]  # e.g., ["join", "exists"] for "from os.path import join, exists"
+    alias: str | None  # e.g., "np" for "import numpy as np"
+    line_number: int
+    is_from_import: bool  # True for "from X import Y", False for "import X"
+
+
+@dataclass(frozen=True)
+class SectionInfo:
+    """Metadata about a section in a text document."""
+
+    title: str
+    level: int  # Heading level (1 = top-level, 2 = subsection, etc.)
+    line_range: LineRange
+
+
+@dataclass
+class StructuralMetadata:
+    """Complete structural metadata for a single file or text document."""
+
+    # Source
+    source_name: str  # Filename or identifier
+    total_lines: int
+    total_chars: int
+
+    # Line data (always populated)
+    lines: list[str]  # All lines (0-indexed internally, but API uses 1-indexed)
+    line_char_offsets: list[int]  # Character offset of each line start
+
+    # Code structure (populated for code files)
+    functions: list[FunctionInfo] = field(default_factory=list)
+    classes: list[ClassInfo] = field(default_factory=list)
+    imports: list[ImportInfo] = field(default_factory=list)
+
+    # Text structure (populated for text/markdown files)
+    sections: list[SectionInfo] = field(default_factory=list)
+
+    # Dependency map (populated for code files)
+    # Maps each function/class name to the names it references
+    dependency_graph: dict[str, list[str]] = field(default_factory=dict)
+
+
+@dataclass
+class ProjectIndex:
+    """Structural index for an entire codebase."""
+
+    root_path: str
+    files: dict[str, StructuralMetadata] = field(default_factory=dict)
+
+    # Cross-file dependency graphs
+    global_dependency_graph: dict[str, set[str]] = field(default_factory=dict)
+    reverse_dependency_graph: dict[str, set[str]] = field(default_factory=dict)
+
+    # File-level import graph
+    import_graph: dict[str, set[str]] = field(default_factory=dict)
+    reverse_import_graph: dict[str, set[str]] = field(default_factory=dict)
+
+    # Global symbol table: symbol_name -> file_path where defined
+    symbol_table: dict[str, str] = field(default_factory=dict)
+
+    # Stats
+    total_files: int = 0
+    total_lines: int = 0
+    total_functions: int = 0
+    total_classes: int = 0
+    index_build_time_seconds: float = 0.0
+    index_memory_bytes: int = 0