Metadata-Version: 2.5
Name: seraph-mcp
Version: 0.1.5
Summary: Query-adaptive, evolution-aware code retrieval
License: MIT License
        
        Copyright (c) 2026 Prethiv Sriman D, Akshith Rajesh, Akhilan VTM, Sanjeev TS — Team floppydisk
        
        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
Requires-Python: <3.13,>=3.12
Requires-Dist: bm25s>=0.2.6
Requires-Dist: mcp<2,>=1.2
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic>=2.7
Requires-Dist: pystemmer>=2.2
Requires-Dist: pyyaml>=6.0
Requires-Dist: scikit-learn>=1.5
Requires-Dist: tree-sitter-go>=0.23
Requires-Dist: tree-sitter-javascript>=0.23
Requires-Dist: tree-sitter-python>=0.23
Requires-Dist: tree-sitter-typescript>=0.23
Requires-Dist: tree-sitter>=0.23
Provides-Extra: api
Requires-Dist: google-genai>=1.20; extra == 'api'
Requires-Dist: openai>=1.40; extra == 'api'
Provides-Extra: cpu
Requires-Dist: einops>=0.8; extra == 'cpu'
Requires-Dist: faiss-cpu>=1.8; extra == 'cpu'
Requires-Dist: sentence-transformers<6,>=3.4; extra == 'cpu'
Requires-Dist: torch>=2.4; extra == 'cpu'
Requires-Dist: transformers<5,>=4.51; extra == 'cpu'
Provides-Extra: gemma2
Requires-Dist: einops>=0.8; extra == 'gemma2'
Requires-Dist: faiss-cpu>=1.8; extra == 'gemma2'
Requires-Dist: sentence-transformers<7,>=6.1; extra == 'gemma2'
Requires-Dist: torch>=2.4; extra == 'gemma2'
Requires-Dist: transformers<6,>=5.19; extra == 'gemma2'
Provides-Extra: gpu
Requires-Dist: einops>=0.8; extra == 'gpu'
Requires-Dist: faiss-cpu>=1.8; extra == 'gpu'
Requires-Dist: sentence-transformers<6,>=3.4; extra == 'gpu'
Requires-Dist: torch>=2.4; extra == 'gpu'
Requires-Dist: transformers<5,>=4.51; extra == 'gpu'
Provides-Extra: llm
Requires-Dist: openai>=1.40; extra == 'llm'
Description-Content-Type: text/markdown

# Seraph

Local code search and Git-aware code intelligence for coding agents. Seraph indexes a local Git checkout into a SQLite database and exposes repository maps, search, symbol, dependency, history, and version comparison tools over MCP.

## Install from a checkout

Requires Python 3.12 and Git. With `uv`:

```sh
uv tool install --from . seraph-mcp
```

For development directly from this directory:

```sh
uv sync
uv run seraph-mcp
```

Install the published package from PyPI:

```sh
python -m pip install seraph-mcp
```

## Agent setup

Register a local **stdio MCP server** in your agent with command `seraph-mcp` and no arguments, then reload the MCP connection. Use your agent's own MCP setup UI or command because configuration differs by host. On every Seraph tool call, pass `repo` as the absolute path to the local Git checkout you want searched. Use the active workspace path for that project, or a different repository path when the question is about another checkout.

Seraph runs on the user's machine. Each tool accepts `repo`, the absolute path to the local Git checkout to search. The agent should pass the active workspace path on every call; if asked about another checkout, pass that checkout's path. The index is stored at `<repo>/.seraph/index.sqlite` and ignored by Git.

## MCP tools

- `search_code`: retrieve relevant code from the selected checkout.
- `search_at_version`: retrieve code from a commit, branch, or tag.
- `search_history`: search indexed Git versions.
- `find_symbol`: locate a function, class, or method.
- `find_dependencies`: walk call, import, and inheritance relationships.
- `get_repo_map`: get a compact file-to-symbol overview; expand a subtree with `path_prefix` or increase `max_files` and `max_chars`.
- `compare_versions`: compare symbols, dependencies, and commits.
- `index_repository`: explicitly index a Git version; searches index automatically when needed.

The default retrieval setup is local and needs no API key. Benchmark/evaluation code and submission assets are intentionally excluded from this slim distribution.

### Optional local semantic search

The default install uses BM25 and does **not** install Torch or download a model.

For BGE-Code-v1 or GTE-ModernBERT, opt in to the Transformers 4 extra:

```sh
python -m pip install 'seraph-mcp[cpu]'  # CPU / Apple Silicon
# or, on an NVIDIA CUDA machine:
python -m pip install 'seraph-mcp[gpu]'
```

Seraph downloads BGE-Code-v1 (about 6 GB) from Hugging Face the first time semantic search needs it. Hugging Face caches the files, so the same user account reuses that model across repositories. Each teammate only downloads their own local cache if they opt in.

EmbeddingGemma-2 needs Transformers 5, so use its separate extra instead of `cpu` or `gpu`:

```sh
python -m pip install 'seraph-mcp[gemma2]'
```

Choose `embeddinggemma-2` in Seraph's model configuration. The selected model weights download on first use and are then cached locally.

## CLI

```sh
seraph --repo /path/to/repo index
seraph --repo /path/to/repo search "where is request authentication checked?"
seraph --repo /path/to/repo symbol authenticate_request
seraph --repo /path/to/repo deps authenticate_request
seraph --repo /path/to/repo compare <old-commit> <new-commit>
```

## License

Released under the MIT License.
