Metadata-Version: 2.4
Name: cocoindex-code
Version: 0.1.0
Summary: MCP server for indexing and querying codebases using CocoIndex
Project-URL: Homepage, https://github.com/cocoindex-io/cocoindex-code
Project-URL: Repository, https://github.com/cocoindex-io/cocoindex-code
Project-URL: Issues, https://github.com/cocoindex-io/cocoindex-code/issues
License-Expression: MIT
Keywords: cocoindex,codebase,indexing,mcp,vector-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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: cocoindex==1.0.0a10
Requires-Dist: mcp>=1.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: sqlite-vec>=0.1.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: prek>=0.1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# CocoIndex Code

An MCP (Model Context Protocol) server for indexing and querying codebases using [CocoIndex](https://cocoindex.io).

## Features

- **Semantic Code Search**: Find relevant code using natural language queries
- **Incremental Indexing**: Only re-indexes changed files for fast updates
- **Multi-Language Support**: Python, JavaScript/TypeScript, Rust, Go
- **Vector Embeddings**: Uses sentence-transformers for semantic similarity
- **SQLite Storage**: Portable, no external database required

## Installation

```bash
pip install cocoindex-code
```

Or with uv:

```bash
uv pip install cocoindex-code
```

## Usage with Claude Code

Add to your Claude Code MCP configuration (`.claude/mcp_config.json`):

```json
{
  "mcpServers": {
    "cocoindex-code": {
      "command": "cocoindex-code",
      "env": {
        "COCOINDEX_CODE_ROOT_PATH": "/path/to/your/codebase"
      }
    }
  }
}
```

Or without explicit path (auto-discovers from current directory):

```json
{
  "mcpServers": {
    "cocoindex-code": {
      "command": "cocoindex-code"
    }
  }
}
```

## Configuration

Environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `COCOINDEX_CODE_ROOT_PATH` | Root path of the codebase | Auto-discovered (see below) |
| `COCOINDEX_CODE_EMBEDDING_MODEL` | Embedding model to use | `sentence-transformers/all-MiniLM-L6-v2` |

### Root Path Discovery

If `COCOINDEX_CODE_ROOT_PATH` is not set, the codebase root is discovered by:

1. Finding the nearest parent directory containing `.cocoindex_code/`
2. Finding the nearest parent directory containing `.git/`
3. Falling back to the current working directory

## MCP Tools

### `query`

Search the codebase using semantic similarity.

```
query(
    query: str,               # Natural language query or code snippet
    limit: int = 10,          # Maximum results (1-100)
    offset: int = 0,          # Pagination offset
    refresh_index: bool = True  # Refresh index before querying
)
```

The `refresh_index` parameter controls whether the index is refreshed before searching:

- `True` (default): Refreshes the index to include any recent changes
- `False`: Skip refresh for faster consecutive queries

Returns matching code chunks with:

- File path
- Language
- Code content
- Line numbers (start/end)
- Similarity score

## Index Storage

The index is stored in `.cocoindex_code/` under your codebase root:

```
your-project/
├── .cocoindex_code/
│   ├── target_sqlite.db  # Vector index (SQLite + sqlite-vec)
│   └── cocoindex.db/     # CocoIndex state
├── src/
│   └── ...
```

Add `.cocoindex_code/` to your `.gitignore`.

## Supported File Types

- **Python**: `.py`, `.pyi`
- **JavaScript**: `.js`, `.jsx`, `.mjs`, `.cjs`
- **TypeScript**: `.ts`, `.tsx`
- **Rust**: `.rs`
- **Go**: `.go`

Common generated directories are automatically excluded:

- `__pycache__/`
- `node_modules/`
- `target/`
- `dist/`
- `build/`
- `.git/`

## Development

### Local Testing with Claude Code

To test locally without installing the package, use the Claude Code CLI:

```bash
claude mcp add cocoindex-code \
  -- uv run --project /path/to/cocoindex-code cocoindex-code
```

Or add to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "cocoindex-code": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/cocoindex-code", "cocoindex-code"]
    }
  }
}
```

### Running Tests

```bash
# Install dev dependencies
uv sync --group dev

# Run tests
uv run pytest tests/ -v

# Run pre-commit hooks
uv run pre-commit run --all-files
```

## License

MIT
