codeseek 0.1.0__tar.gz

codeseek-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+
+# codeseek index databases
+*.codeseek.db
+.codeseek.db
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini

codeseek-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## v0.1.0
+
+### Features
+- index a directory of source files into a local SQLite vector store
+- semantic search over the index from the CLI
+- run as an MCP server (stdio) exposing a `search_code` tool to any MCP client
+- provider-agnostic embeddings: OpenAI, or a local server via `--base-url`
+- pluggable document sources, so the same engine can index more than code
+- zero runtime dependencies (standard library only)
+
+Initial release.

codeseek-0.1.0/LICENSE

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

codeseek-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: codeseek
+Version: 0.1.0
+Summary: Semantic code search for your repo, as a CLI and an MCP server. Bring any OpenAI-compatible embedding model. Zero dependencies.
+Project-URL: Homepage, https://github.com/Sev7nOfNine/codeseek
+Project-URL: Repository, https://github.com/Sev7nOfNine/codeseek
+Project-URL: Issues, https://github.com/Sev7nOfNine/codeseek/issues
+Author: Seven Of Nine
+License: MIT
+License-File: LICENSE
+Keywords: cli,code-search,developer-tools,embeddings,llm,mcp,model-context-protocol,rag,semantic-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# codeseek
+
+[![PyPI](https://img.shields.io/pypi/v/codeseek.svg)](https://pypi.org/project/codeseek/)
+[![CI](https://github.com/Sev7nOfNine/codeseek/actions/workflows/ci.yml/badge.svg)](https://github.com/Sev7nOfNine/codeseek/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/codeseek.svg)](https://pypi.org/project/codeseek/)
+
+**Semantic search over your codebase — as a CLI and an MCP server. Zero dependencies.**
+
+`codeseek` indexes a repository into a local vector store and lets you search it
+by meaning, not just by string match. Use it from the terminal, or run it as an
+[MCP](https://modelcontextprotocol.io) server so an AI coding assistant or editor
+can ask your codebase questions directly.
+
+It brings no embedding model of its own: point it at the OpenAI API, or at any
+OpenAI-compatible endpoint such as a local `llama.cpp` server, so private code
+can be embedded without leaving your machine. Storage is plain SQLite; search is
+brute-force cosine. The whole thing is the Python standard library and nothing
+else.
+
+## Install
+
+```bash
+pip install codeseek
+# or:
+pipx install codeseek
+```
+
+Requires Python 3.8+.
+
+## Quick start
+
+```bash
+export OPENAI_API_KEY=sk-...
+
+# 1. Index the current repository
+codeseek index .
+
+# 2. Search it
+codeseek search "where do we validate the auth token?"
+codeseek search "retry with backoff" -k 3
+```
+
+Results come back as markdown, each with a file path, line range, and similarity
+score:
+
+```markdown
+### src/auth/token.py:40-70  (score 0.812)
+​```
+def verify_token(raw: str) -> Claims:
+    ...
+​```
+```
+
+### Use a local or alternative provider
+
+```bash
+codeseek index . --base-url http://localhost:8080/v1 --model nomic-embed-text
+```
+
+## As an MCP server
+
+`codeseek serve` speaks MCP over stdio and exposes one tool, `search_code`.
+
+After indexing a repo, register it with your MCP client. A typical `mcpServers`
+configuration looks like this:
+
+```json
+{
+  "mcpServers": {
+    "codeseek": {
+      "command": "codeseek",
+      "args": ["serve", "--db", "/path/to/your/repo/.codeseek.db"],
+      "env": { "OPENAI_API_KEY": "sk-..." }
+    }
+  }
+}
+```
+
+The assistant can then call `search_code` to pull relevant code into its context
+on demand, instead of you pasting files by hand.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `codeseek index [PATH]` | Index a directory (default `.`) into `--db`. |
+| `codeseek search QUERY` | Search the index; `-k` sets result count. |
+| `codeseek serve` | Run the MCP server over stdio. |
+
+Shared options: `--db`, `--model`, `--base-url`, `--api-key` (each with an
+environment-variable default).
+
+## How it works
+
+1. **Source** — files are walked and read (sensible code/text extensions, common
+   build and vendor directories skipped).
+2. **Chunking** — each file is split into overlapping line windows.
+3. **Embedding** — chunks are embedded in batches via your provider.
+4. **Storage** — vectors land in a local SQLite database.
+5. **Search** — your query is embedded and compared against every chunk by cosine
+   similarity; the top matches are returned.
+
+The document source is pluggable: the engine only consumes `Document` objects, so
+the same indexing and search machinery can be pointed at things other than code.
+
+## Privacy note
+
+Indexing sends file contents to whichever embeddings provider you configure. For
+private code, prefer a self-hosted model via `--base-url`.
+
+## Scope
+
+Search is a linear scan, which is plenty fast for a single repository (a few
+thousand chunks). Indexing very large monorepos would want a real approximate
+vector index — a natural next step, not today's goal.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+python -m pytest
+```
+
+All tests run offline; the embedding and HTTP layers accept injectable fakes.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

codeseek-0.1.0/README.md

@@ -0,0 +1,129 @@
+# codeseek
+
+[![PyPI](https://img.shields.io/pypi/v/codeseek.svg)](https://pypi.org/project/codeseek/)
+[![CI](https://github.com/Sev7nOfNine/codeseek/actions/workflows/ci.yml/badge.svg)](https://github.com/Sev7nOfNine/codeseek/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/codeseek.svg)](https://pypi.org/project/codeseek/)
+
+**Semantic search over your codebase — as a CLI and an MCP server. Zero dependencies.**
+
+`codeseek` indexes a repository into a local vector store and lets you search it
+by meaning, not just by string match. Use it from the terminal, or run it as an
+[MCP](https://modelcontextprotocol.io) server so an AI coding assistant or editor
+can ask your codebase questions directly.
+
+It brings no embedding model of its own: point it at the OpenAI API, or at any
+OpenAI-compatible endpoint such as a local `llama.cpp` server, so private code
+can be embedded without leaving your machine. Storage is plain SQLite; search is
+brute-force cosine. The whole thing is the Python standard library and nothing
+else.
+
+## Install
+
+```bash
+pip install codeseek
+# or:
+pipx install codeseek
+```
+
+Requires Python 3.8+.
+
+## Quick start
+
+```bash
+export OPENAI_API_KEY=sk-...
+
+# 1. Index the current repository
+codeseek index .
+
+# 2. Search it
+codeseek search "where do we validate the auth token?"
+codeseek search "retry with backoff" -k 3
+```
+
+Results come back as markdown, each with a file path, line range, and similarity
+score:
+
+```markdown
+### src/auth/token.py:40-70  (score 0.812)
+​```
+def verify_token(raw: str) -> Claims:
+    ...
+​```
+```
+
+### Use a local or alternative provider
+
+```bash
+codeseek index . --base-url http://localhost:8080/v1 --model nomic-embed-text
+```
+
+## As an MCP server
+
+`codeseek serve` speaks MCP over stdio and exposes one tool, `search_code`.
+
+After indexing a repo, register it with your MCP client. A typical `mcpServers`
+configuration looks like this:
+
+```json
+{
+  "mcpServers": {
+    "codeseek": {
+      "command": "codeseek",
+      "args": ["serve", "--db", "/path/to/your/repo/.codeseek.db"],
+      "env": { "OPENAI_API_KEY": "sk-..." }
+    }
+  }
+}
+```
+
+The assistant can then call `search_code` to pull relevant code into its context
+on demand, instead of you pasting files by hand.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `codeseek index [PATH]` | Index a directory (default `.`) into `--db`. |
+| `codeseek search QUERY` | Search the index; `-k` sets result count. |
+| `codeseek serve` | Run the MCP server over stdio. |
+
+Shared options: `--db`, `--model`, `--base-url`, `--api-key` (each with an
+environment-variable default).
+
+## How it works
+
+1. **Source** — files are walked and read (sensible code/text extensions, common
+   build and vendor directories skipped).
+2. **Chunking** — each file is split into overlapping line windows.
+3. **Embedding** — chunks are embedded in batches via your provider.
+4. **Storage** — vectors land in a local SQLite database.
+5. **Search** — your query is embedded and compared against every chunk by cosine
+   similarity; the top matches are returned.
+
+The document source is pluggable: the engine only consumes `Document` objects, so
+the same indexing and search machinery can be pointed at things other than code.
+
+## Privacy note
+
+Indexing sends file contents to whichever embeddings provider you configure. For
+private code, prefer a self-hosted model via `--base-url`.
+
+## Scope
+
+Search is a linear scan, which is plenty fast for a single repository (a few
+thousand chunks). Indexing very large monorepos would want a real approximate
+vector index — a natural next step, not today's goal.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+python -m pytest
+```
+
+All tests run offline; the embedding and HTTP layers accept injectable fakes.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

codeseek-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codeseek"
+version = "0.1.0"
+description = "Semantic code search for your repo, as a CLI and an MCP server. Bring any OpenAI-compatible embedding model. Zero dependencies."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Seven Of Nine" }]
+keywords = [
+    "semantic-search",
+    "code-search",
+    "embeddings",
+    "rag",
+    "mcp",
+    "model-context-protocol",
+    "llm",
+    "developer-tools",
+    "cli",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Utilities",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/Sev7nOfNine/codeseek"
+Repository = "https://github.com/Sev7nOfNine/codeseek"
+Issues = "https://github.com/Sev7nOfNine/codeseek/issues"
+
+[project.scripts]
+codeseek = "codeseek.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codeseek"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/codeseek", "README.md", "LICENSE", "CHANGELOG.md", "tests"]

codeseek-0.1.0/src/codeseek/__init__.py

@@ -0,0 +1,5 @@
+"""codeseek — semantic code search as a CLI and an MCP server."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

codeseek-0.1.0/src/codeseek/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codeseek-0.1.0/src/codeseek/chunking.py

@@ -0,0 +1,34 @@
+"""Split text into overlapping line windows for embedding."""
+
+from __future__ import annotations
+
+from typing import List, Tuple
+
+# (start_line, end_line, text), with 1-based inclusive line numbers.
+Chunk = Tuple[int, int, str]
+
+
+def chunk_text(text: str, *, max_lines: int = 60, overlap: int = 10) -> List[Chunk]:
+    """Break ``text`` into overlapping windows of at most ``max_lines`` lines."""
+    if max_lines <= 0:
+        raise ValueError("max_lines must be positive")
+    if overlap >= max_lines:
+        overlap = max_lines // 2
+
+    lines = text.splitlines()
+    if not lines:
+        return []
+
+    step = max_lines - overlap
+    chunks: List[Chunk] = []
+    n = len(lines)
+    i = 0
+    while i < n:
+        window = lines[i : i + max_lines]
+        start = i + 1
+        end = min(i + max_lines, n)
+        chunks.append((start, end, "\n".join(window)))
+        if i + max_lines >= n:
+            break
+        i += step
+    return chunks

codeseek-0.1.0/src/codeseek/cli.py

@@ -0,0 +1,152 @@
+"""Command-line interface for codeseek."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from typing import Callable, List, Optional
+
+from . import __version__
+from .embeddings import EmbeddingError, embed
+from .index import build_index
+from .search import format_results, search_index
+from .sources import FileSource
+from .store import VectorStore
+
+DEFAULT_DB = ".codeseek.db"
+DEFAULT_MODEL = "text-embedding-3-small"
+
+Embedder = Callable[[List[str]], List[List[float]]]
+
+
+def _add_provider_args(sub: argparse.ArgumentParser) -> None:
+    sub.add_argument(
+        "--model",
+        default=os.environ.get("CODESEEK_MODEL", DEFAULT_MODEL),
+        metavar="NAME",
+        help="embedding model (default: {0}, or $CODESEEK_MODEL).".format(DEFAULT_MODEL),
+    )
+    sub.add_argument(
+        "--base-url",
+        default=os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1"),
+        metavar="URL",
+        help="OpenAI-compatible base URL (default: $OPENAI_BASE_URL or OpenAI).",
+    )
+    sub.add_argument(
+        "--api-key",
+        default=os.environ.get("OPENAI_API_KEY"),
+        metavar="KEY",
+        help="embeddings API key (default: $OPENAI_API_KEY).",
+    )
+    sub.add_argument(
+        "--db",
+        default=DEFAULT_DB,
+        metavar="FILE",
+        help="index database path (default: {0}).".format(DEFAULT_DB),
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="codeseek",
+        description="Semantic code search as a CLI and an MCP server.",
+    )
+    parser.add_argument(
+        "--version", action="version", version="%(prog)s {0}".format(__version__)
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_index = sub.add_parser("index", help="index a directory of code.")
+    p_index.add_argument(
+        "path", nargs="?", default=".", help="directory to index (default: .)."
+    )
+    p_index.add_argument(
+        "--max-lines", type=int, default=60, help="lines per chunk (default: 60)."
+    )
+    p_index.add_argument(
+        "--overlap", type=int, default=10, help="overlapping lines (default: 10)."
+    )
+    _add_provider_args(p_index)
+
+    p_search = sub.add_parser("search", help="search the index.")
+    p_search.add_argument("query", help="what to look for.")
+    p_search.add_argument(
+        "-k", type=int, default=5, help="number of results (default: 5)."
+    )
+    _add_provider_args(p_search)
+
+    p_serve = sub.add_parser("serve", help="run the MCP server over stdio.")
+    _add_provider_args(p_serve)
+
+    return parser
+
+
+def _make_embedder(args: argparse.Namespace) -> Embedder:
+    def embedder(texts: List[str]) -> List[List[float]]:
+        return embed(
+            texts, model=args.model, api_key=args.api_key, base_url=args.base_url
+        )
+
+    return embedder
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if not args.api_key:
+        parser.exit(2, "codeseek: no API key (set $OPENAI_API_KEY or --api-key)\n")
+
+    embedder = _make_embedder(args)
+
+    if args.command == "index":
+        source = FileSource(args.path)
+        store = VectorStore(args.db)
+        try:
+            count = build_index(
+                source,
+                store,
+                embedder,
+                max_lines=args.max_lines,
+                overlap=args.overlap,
+                progress=lambda doc_id: sys.stderr.write(
+                    "  indexed {0}\n".format(doc_id)
+                ),
+            )
+        except EmbeddingError as exc:
+            parser.exit(1, "codeseek: {0}\n".format(exc))
+        finally:
+            store.close()
+        sys.stderr.write("codeseek: indexed {0} chunks into {1}\n".format(count, args.db))
+        return 0
+
+    if args.command == "search":
+        store = VectorStore(args.db)
+        try:
+            results = search_index(store, embedder, args.query, k=args.k)
+        except EmbeddingError as exc:
+            parser.exit(1, "codeseek: {0}\n".format(exc))
+        finally:
+            store.close()
+        sys.stdout.write(format_results(results) + "\n")
+        return 0
+
+    if args.command == "serve":
+        from .mcp_server import MCPServer
+
+        store = VectorStore(args.db)
+
+        def search_fn(query: str, k: int):
+            return search_index(store, embedder, query, k=k)
+
+        MCPServer(search_fn, server_version=__version__).serve()
+        store.close()
+        return 0
+
+    parser.error("unknown command")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codeseek-0.1.0/src/codeseek/embeddings.py

@@ -0,0 +1,65 @@
+"""Embeddings client for OpenAI-compatible APIs, using only the stdlib.
+
+Works with the OpenAI platform, or any compatible ``/embeddings`` endpoint such
+as a local llama.cpp server, so private code can be embedded without leaving the
+machine.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Callable, Dict, List, Optional
+
+Opener = Callable[..., Any]
+
+
+class EmbeddingError(RuntimeError):
+    """Raised when the embeddings request fails or returns an unexpected shape."""
+
+
+def parse_embeddings(data: Dict[str, Any]) -> List[List[float]]:
+    """Pull the list of embedding vectors out of an embeddings response."""
+    try:
+        items = data["data"]
+        return [item["embedding"] for item in items]
+    except (KeyError, TypeError):
+        raise EmbeddingError(
+            "unexpected embeddings response: {0}".format(json.dumps(data)[:300])
+        )
+
+
+def embed(
+    texts: List[str],
+    *,
+    model: str,
+    api_key: str,
+    base_url: str = "https://api.openai.com/v1",
+    timeout: int = 120,
+    opener: Optional[Opener] = None,
+) -> List[List[float]]:
+    """Embed a batch of texts and return one vector per input."""
+    if not texts:
+        return []
+
+    url = base_url.rstrip("/") + "/embeddings"
+    payload = json.dumps({"model": model, "input": texts}).encode("utf-8")
+
+    req = urllib.request.Request(url, data=payload, method="POST")
+    req.add_header("Content-Type", "application/json")
+    req.add_header("Authorization", "Bearer " + api_key)
+
+    do_open = opener or urllib.request.urlopen
+    try:
+        with do_open(req, timeout=timeout) as resp:
+            raw = resp.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", "replace")
+        raise EmbeddingError(
+            "embeddings request failed (HTTP {0}): {1}".format(exc.code, body[:500])
+        )
+    except urllib.error.URLError as exc:
+        raise EmbeddingError("embeddings request failed: {0}".format(exc.reason))
+
+    return parse_embeddings(json.loads(raw))

codeseek-0.1.0/src/codeseek/index.py

@@ -0,0 +1,71 @@
+"""Build a search index: source -> chunks -> embeddings -> store."""
+
+from __future__ import annotations
+
+from typing import Callable, List, Optional
+
+from .chunking import chunk_text
+from .sources import Document
+from .store import VectorStore
+
+# An embedder turns a batch of texts into a batch of vectors.
+Embedder = Callable[[List[str]], List[List[float]]]
+# Anything iterable of Documents (FileSource, or a future notes source).
+Source = "object with a documents() iterator"
+
+
+def build_index(
+    source,
+    store: VectorStore,
+    embedder: Embedder,
+    *,
+    batch_size: int = 64,
+    max_lines: int = 60,
+    overlap: int = 10,
+    progress: Optional[Callable[[str], None]] = None,
+) -> int:
+    """Index every document from ``source`` into ``store``. Returns chunk count."""
+    store.clear()
+
+    pending_rows: List[dict] = []
+    pending_text: List[str] = []
+    total = 0
+
+    def flush() -> None:
+        nonlocal total
+        if not pending_text:
+            return
+        vectors = embedder(pending_text)
+        rows = []
+        for row, vec in zip(pending_rows, vectors):
+            enriched = dict(row)
+            enriched["embedding"] = vec
+            rows.append(enriched)
+        store.add(rows)
+        total += len(rows)
+        pending_rows.clear()
+        pending_text.clear()
+
+    for doc in source.documents():  # type: Document
+        path = doc.metadata.get("path", doc.id)
+        for start, end, text in chunk_text(
+            doc.text, max_lines=max_lines, overlap=overlap
+        ):
+            pending_rows.append(
+                {
+                    "id": "{0}:{1}-{2}".format(doc.id, start, end),
+                    "doc_id": doc.id,
+                    "path": path,
+                    "start_line": start,
+                    "end_line": end,
+                    "text": text,
+                }
+            )
+            pending_text.append(text)
+            if len(pending_text) >= batch_size:
+                flush()
+        if progress is not None:
+            progress(doc.id)
+
+    flush()
+    return total

codeseek-0.1.0/src/codeseek/mcp_server.py

@@ -0,0 +1,128 @@
+"""A minimal Model Context Protocol (MCP) server over stdio.
+
+Implements just enough of the protocol — ``initialize``, ``tools/list`` and
+``tools/call`` exchanged as newline-delimited JSON-RPC 2.0 — to expose a single
+``search_code`` tool to any MCP client, with no third-party dependencies.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Callable, Dict, List, Optional
+
+from .search import format_results
+from .store import ScoredChunk
+
+PROTOCOL_VERSION = "2024-11-05"
+
+SEARCH_TOOL: Dict[str, Any] = {
+    "name": "search_code",
+    "description": (
+        "Semantic search over the indexed codebase. Returns the most relevant "
+        "code chunks with their file path and line range."
+    ),
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "A natural-language or code query.",
+            },
+            "k": {
+                "type": "integer",
+                "description": "How many results to return (default 5).",
+            },
+        },
+        "required": ["query"],
+    },
+}
+
+# A search function takes (query, k) and returns scored chunks.
+SearchFn = Callable[[str, int], List[ScoredChunk]]
+
+
+class MCPServer:
+    """Dispatch MCP JSON-RPC requests to a search backend."""
+
+    def __init__(
+        self,
+        search_fn: SearchFn,
+        *,
+        server_name: str = "codeseek",
+        server_version: str = "0.1.0",
+    ) -> None:
+        self.search_fn = search_fn
+        self.server_name = server_name
+        self.server_version = server_version
+
+    def _error(self, req_id: Any, code: int, message: str) -> Dict[str, Any]:
+        return {
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "error": {"code": code, "message": message},
+        }
+
+    def handle(self, request: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """Handle one request. Returns a response, or None for notifications."""
+        method = request.get("method")
+        req_id = request.get("id")
+
+        if method == "initialize":
+            result: Dict[str, Any] = {
+                "protocolVersion": PROTOCOL_VERSION,
+                "capabilities": {"tools": {}},
+                "serverInfo": {
+                    "name": self.server_name,
+                    "version": self.server_version,
+                },
+            }
+        elif method == "tools/list":
+            result = {"tools": [SEARCH_TOOL]}
+        elif method == "tools/call":
+            params = request.get("params") or {}
+            if params.get("name") != "search_code":
+                return self._error(
+                    req_id, -32602, "unknown tool: {0}".format(params.get("name"))
+                )
+            args = params.get("arguments") or {}
+            query = args.get("query", "")
+            try:
+                k = int(args.get("k", 5) or 5)
+            except (TypeError, ValueError):
+                k = 5
+            try:
+                results = self.search_fn(query, k)
+                result = {"content": [{"type": "text", "text": format_results(results)}]}
+            except Exception as exc:  # surface errors to the client, do not crash
+                return {
+                    "jsonrpc": "2.0",
+                    "id": req_id,
+                    "result": {
+                        "content": [{"type": "text", "text": "error: {0}".format(exc)}],
+                        "isError": True,
+                    },
+                }
+        elif method and method.startswith("notifications/"):
+            return None
+        else:
+            return self._error(req_id, -32601, "method not found: {0}".format(method))
+
+        return {"jsonrpc": "2.0", "id": req_id, "result": result}
+
+    def serve(self, stdin: Any = None, stdout: Any = None) -> None:
+        """Read newline-delimited JSON-RPC from stdin, write responses to stdout."""
+        stdin = stdin if stdin is not None else sys.stdin
+        stdout = stdout if stdout is not None else sys.stdout
+        for line in stdin:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                request = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            response = self.handle(request)
+            if response is not None:
+                stdout.write(json.dumps(response) + "\n")
+                stdout.flush()

codeseek-0.1.0/src/codeseek/search.py

@@ -0,0 +1,33 @@
+"""Query the index: embed the query, return the most similar chunks."""
+
+from __future__ import annotations
+
+from typing import Callable, List
+
+from .store import ScoredChunk, VectorStore
+
+Embedder = Callable[[List[str]], List[List[float]]]
+
+
+def search_index(
+    store: VectorStore, embedder: Embedder, query: str, k: int = 5
+) -> List[ScoredChunk]:
+    """Return the top ``k`` chunks most similar to ``query``."""
+    if not query.strip():
+        return []
+    query_vec = embedder([query])[0]
+    return store.search(query_vec, k)
+
+
+def format_results(results: List[ScoredChunk]) -> str:
+    """Render scored chunks as readable markdown."""
+    if not results:
+        return "No matches."
+    parts = []
+    for score, row in results:
+        parts.append(
+            "### {0}:{1}-{2}  (score {3:.3f})\n```\n{4}\n```".format(
+                row["path"], row["start_line"], row["end_line"], score, row["text"]
+            )
+        )
+    return "\n\n".join(parts)

codeseek-0.1.0/src/codeseek/sources.py

@@ -0,0 +1,78 @@
+"""Document sources for indexing.
+
+A *source* is anything that yields :class:`Document` objects. The rest of
+codeseek (chunking, embedding, storage, search) never cares where documents come
+from, so a new source — code files, markdown notes, a wiki export — is all it
+takes to point the same engine at different data.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Dict, Iterable, Iterator, Optional, Set
+
+
+@dataclass
+class Document:
+    """A unit of text to index."""
+
+    id: str
+    text: str
+    metadata: Dict[str, str] = field(default_factory=dict)
+
+
+# A pragmatic default set of source-code and text extensions.
+DEFAULT_EXTENSIONS: Set[str] = {
+    ".py", ".pyi", ".js", ".jsx", ".ts", ".tsx", ".go", ".rs", ".java", ".kt",
+    ".c", ".h", ".cc", ".cpp", ".hpp", ".cs", ".rb", ".php", ".swift", ".scala",
+    ".sh", ".bash", ".ps1", ".lua", ".r", ".jl", ".sql", ".html", ".css", ".scss",
+    ".md", ".rst", ".txt", ".toml", ".yaml", ".yml", ".json", ".ini", ".cfg",
+}
+
+DEFAULT_EXCLUDES: Set[str] = {
+    ".git", ".hg", ".svn", "__pycache__", "node_modules", ".venv", "venv",
+    "dist", "build", ".mypy_cache", ".pytest_cache", ".ruff_cache", ".idea",
+    ".tox", "target", "vendor",
+}
+
+# Skip files larger than this; they are usually generated or binary.
+MAX_FILE_BYTES = 400_000
+
+
+class FileSource:
+    """Yield documents from source files under a directory tree."""
+
+    def __init__(
+        self,
+        root: str,
+        *,
+        extensions: Optional[Iterable[str]] = None,
+        exclude_dirs: Optional[Iterable[str]] = None,
+        max_file_bytes: int = MAX_FILE_BYTES,
+    ) -> None:
+        self.root = root
+        self.extensions = set(extensions) if extensions else set(DEFAULT_EXTENSIONS)
+        self.exclude_dirs = set(exclude_dirs) if exclude_dirs else set(DEFAULT_EXCLUDES)
+        self.max_file_bytes = max_file_bytes
+
+    def documents(self) -> Iterator[Document]:
+        for dirpath, dirnames, filenames in os.walk(self.root):
+            # Prune excluded directories in place so os.walk does not descend.
+            dirnames[:] = [d for d in dirnames if d not in self.exclude_dirs]
+            for name in filenames:
+                ext = os.path.splitext(name)[1].lower()
+                if ext not in self.extensions:
+                    continue
+                full = os.path.join(dirpath, name)
+                try:
+                    if os.path.getsize(full) > self.max_file_bytes:
+                        continue
+                    with open(full, "r", encoding="utf-8") as handle:
+                        text = handle.read()
+                except (OSError, UnicodeDecodeError):
+                    continue
+                if not text.strip():
+                    continue
+                rel = os.path.relpath(full, self.root).replace(os.sep, "/")
+                yield Document(id=rel, text=text, metadata={"path": rel})

codeseek-0.1.0/src/codeseek/store.py

@@ -0,0 +1,103 @@
+"""A small SQLite-backed vector store with brute-force cosine search.
+
+Brute force is intentional: for a single repository (a few thousand chunks) a
+linear scan in Python is fast enough and keeps the dependency count at zero. For
+much larger corpora a real vector index would be the next step.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import sqlite3
+from typing import Dict, List, Optional, Sequence, Tuple
+
+ScoredChunk = Tuple[float, Dict[str, object]]
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS chunks (
+    id         TEXT PRIMARY KEY,
+    doc_id     TEXT,
+    path       TEXT,
+    start_line INTEGER,
+    end_line   INTEGER,
+    text       TEXT,
+    embedding  TEXT
+)
+"""
+
+
+def cosine(a: Sequence[float], b: Sequence[float]) -> float:
+    """Cosine similarity between two equal-length vectors."""
+    if len(a) != len(b):
+        raise ValueError("vectors have different lengths")
+    dot = sum(x * y for x, y in zip(a, b))
+    norm_a = math.sqrt(sum(x * x for x in a))
+    norm_b = math.sqrt(sum(y * y for y in b))
+    if norm_a == 0.0 or norm_b == 0.0:
+        return 0.0
+    return dot / (norm_a * norm_b)
+
+
+class VectorStore:
+    """Persisted store of embedded text chunks."""
+
+    def __init__(self, path: str = ":memory:") -> None:
+        self.conn = sqlite3.connect(path)
+        self.conn.execute(_SCHEMA)
+        self.conn.commit()
+
+    def clear(self) -> None:
+        self.conn.execute("DELETE FROM chunks")
+        self.conn.commit()
+
+    def add(self, rows: List[Dict[str, object]]) -> None:
+        """Insert (or replace) chunk rows. Each row carries an ``embedding`` list."""
+        self.conn.executemany(
+            "INSERT OR REPLACE INTO chunks "
+            "(id, doc_id, path, start_line, end_line, text, embedding) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?)",
+            [
+                (
+                    r["id"],
+                    r["doc_id"],
+                    r["path"],
+                    r["start_line"],
+                    r["end_line"],
+                    r["text"],
+                    json.dumps(r["embedding"]),
+                )
+                for r in rows
+            ],
+        )
+        self.conn.commit()
+
+    def count(self) -> int:
+        return int(self.conn.execute("SELECT COUNT(*) FROM chunks").fetchone()[0])
+
+    def search(self, query_vec: Sequence[float], k: int = 5) -> List[ScoredChunk]:
+        cur = self.conn.execute(
+            "SELECT id, doc_id, path, start_line, end_line, text, embedding FROM chunks"
+        )
+        scored: List[ScoredChunk] = []
+        for row in cur:
+            embedding = json.loads(row[6])
+            score = cosine(query_vec, embedding)
+            scored.append(
+                (
+                    score,
+                    {
+                        "id": row[0],
+                        "doc_id": row[1],
+                        "path": row[2],
+                        "start_line": row[3],
+                        "end_line": row[4],
+                        "text": row[5],
+                    },
+                )
+            )
+        scored.sort(key=lambda item: item[0], reverse=True)
+        return scored[:k]
+
+    def close(self) -> None:
+        self.conn.close()

codeseek-0.1.0/tests/test_codeseek.py

@@ -0,0 +1,211 @@
+"""Offline tests for codeseek. No network, no real embeddings."""
+
+import json
+import os
+import tempfile
+
+import pytest
+
+from codeseek import embeddings
+from codeseek.chunking import chunk_text
+from codeseek.cli import build_parser
+from codeseek.index import build_index
+from codeseek.mcp_server import MCPServer
+from codeseek.search import format_results, search_index
+from codeseek.sources import Document, FileSource
+from codeseek.store import VectorStore, cosine
+
+
+# --- chunking -----------------------------------------------------------------
+
+
+def test_chunk_short_text_single_chunk():
+    chunks = chunk_text("a\nb\nc", max_lines=60, overlap=10)
+    assert len(chunks) == 1
+    assert chunks[0] == (1, 3, "a\nb\nc")
+
+
+def test_chunk_overlap_and_windows():
+    text = "\n".join(str(i) for i in range(1, 26))  # 25 lines
+    chunks = chunk_text(text, max_lines=10, overlap=2)
+    assert chunks[0][0] == 1 and chunks[0][1] == 10
+    # step = 8, so second window starts at line 9
+    assert chunks[1][0] == 9
+    assert chunks[-1][1] == 25  # last window reaches the end
+
+
+def test_chunk_empty():
+    assert chunk_text("", max_lines=10) == []
+
+
+# --- embeddings parsing -------------------------------------------------------
+
+
+def test_parse_embeddings_ok():
+    data = {"data": [{"embedding": [0.1, 0.2]}, {"embedding": [0.3, 0.4]}]}
+    assert embeddings.parse_embeddings(data) == [[0.1, 0.2], [0.3, 0.4]]
+
+
+def test_parse_embeddings_bad():
+    with pytest.raises(embeddings.EmbeddingError):
+        embeddings.parse_embeddings({"oops": 1})
+
+
+def test_embed_empty_returns_empty():
+    assert embeddings.embed([], model="m", api_key="k") == []
+
+
+# --- store --------------------------------------------------------------------
+
+
+def test_cosine_basics():
+    assert cosine([1, 0], [1, 0]) == pytest.approx(1.0)
+    assert cosine([1, 0], [0, 1]) == pytest.approx(0.0)
+    assert cosine([0, 0], [1, 1]) == 0.0
+
+
+def test_store_add_and_search():
+    store = VectorStore(":memory:")
+    store.add(
+        [
+            {"id": "a:1-1", "doc_id": "a", "path": "a.py", "start_line": 1,
+             "end_line": 1, "text": "alpha", "embedding": [1.0, 0.0]},
+            {"id": "b:1-1", "doc_id": "b", "path": "b.py", "start_line": 1,
+             "end_line": 1, "text": "beta", "embedding": [0.0, 1.0]},
+        ]
+    )
+    assert store.count() == 2
+    results = store.search([0.9, 0.1], k=1)
+    assert len(results) == 1
+    assert results[0][1]["path"] == "a.py"
+    store.close()
+
+
+# --- sources ------------------------------------------------------------------
+
+
+def test_file_source_walks_and_filters():
+    with tempfile.TemporaryDirectory() as root:
+        with open(os.path.join(root, "keep.py"), "w", encoding="utf-8") as f:
+            f.write("print('hi')\n")
+        with open(os.path.join(root, "skip.bin"), "w", encoding="utf-8") as f:
+            f.write("nope\n")
+        os.makedirs(os.path.join(root, "node_modules"))
+        with open(os.path.join(root, "node_modules", "x.py"), "w", encoding="utf-8") as f:
+            f.write("should be excluded\n")
+
+        docs = list(FileSource(root).documents())
+        ids = {d.id for d in docs}
+        assert "keep.py" in ids
+        assert "skip.bin" not in ids
+        assert "node_modules/x.py" not in ids
+
+
+# --- index (with a fake embedder) --------------------------------------------
+
+
+class _FakeSource:
+    def documents(self):
+        yield Document(id="f.py", text="line1\nline2\nline3", metadata={"path": "f.py"})
+
+
+def _fake_embedder(texts):
+    # deterministic vector: [len, number of lines]
+    return [[float(len(t)), float(t.count("\n") + 1)] for t in texts]
+
+
+def test_build_index_counts_chunks():
+    store = VectorStore(":memory:")
+    count = build_index(_FakeSource(), store, _fake_embedder, max_lines=2, overlap=0)
+    assert count == store.count()
+    assert count >= 2  # 3 lines, 2 per chunk -> at least 2 chunks
+    store.close()
+
+
+def test_search_index_roundtrip():
+    store = VectorStore(":memory:")
+    build_index(_FakeSource(), store, _fake_embedder, max_lines=2, overlap=0)
+    results = search_index(store, _fake_embedder, "line1\nline2", k=1)
+    assert len(results) == 1
+    assert "f.py" in results[0][1]["path"]
+    store.close()
+
+
+def test_search_empty_query():
+    store = VectorStore(":memory:")
+    assert search_index(store, _fake_embedder, "   ", k=3) == []
+    store.close()
+
+
+def test_format_results_empty():
+    assert format_results([]) == "No matches."
+
+
+# --- mcp server ---------------------------------------------------------------
+
+
+def _server():
+    def search_fn(query, k):
+        return [(0.99, {"path": "x.py", "start_line": 1, "end_line": 2, "text": "code"})]
+
+    return MCPServer(search_fn)
+
+
+def test_mcp_initialize():
+    resp = _server().handle({"jsonrpc": "2.0", "id": 1, "method": "initialize"})
+    assert resp["result"]["protocolVersion"]
+    assert resp["result"]["serverInfo"]["name"] == "codeseek"
+
+
+def test_mcp_tools_list():
+    resp = _server().handle({"jsonrpc": "2.0", "id": 2, "method": "tools/list"})
+    names = [t["name"] for t in resp["result"]["tools"]]
+    assert names == ["search_code"]
+
+
+def test_mcp_tools_call():
+    resp = _server().handle(
+        {
+            "jsonrpc": "2.0",
+            "id": 3,
+            "method": "tools/call",
+            "params": {"name": "search_code", "arguments": {"query": "code", "k": 1}},
+        }
+    )
+    assert "x.py" in resp["result"]["content"][0]["text"]
+
+
+def test_mcp_unknown_tool():
+    resp = _server().handle(
+        {"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "nope"}}
+    )
+    assert resp["error"]["code"] == -32602
+
+
+def test_mcp_notification_returns_none():
+    assert _server().handle({"jsonrpc": "2.0", "method": "notifications/initialized"}) is None
+
+
+def test_mcp_unknown_method():
+    resp = _server().handle({"jsonrpc": "2.0", "id": 5, "method": "bogus"})
+    assert resp["error"]["code"] == -32601
+
+
+# --- cli parser ---------------------------------------------------------------
+
+
+def test_parser_requires_subcommand():
+    with pytest.raises(SystemExit):
+        build_parser().parse_args([])
+
+
+def test_parser_index_defaults():
+    args = build_parser().parse_args(["index", "src"])
+    assert args.command == "index"
+    assert args.path == "src"
+
+
+def test_parser_search():
+    args = build_parser().parse_args(["search", "how does auth work", "-k", "3"])
+    assert args.command == "search"
+    assert args.k == 3