bgts-context-engine 0.2.0__tar.gz → 0.2.1__tar.gz

bgts_context_engine-0.2.1/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.1] - 2026-09-11
+
+### Added
+
+- Indexing over MCP: `index_repo` and `reindex_repo`, plus the read-only `get_index_job` and
+  `list_index_jobs`. Both write tools take a local working tree and enqueue a job rather than
+  indexing inline, because a full index outlives any agent's tool-call timeout. They are gated
+  behind `BCE_MCP_ALLOW_WRITE` (default off) and are neither advertised nor dispatchable while
+  it is off. With it on, the MCP process also runs job workers, so queued indexing progresses
+  without a separate `bce serve`; the pool claims `index` and `reindex` only, so a clone that
+  REST enqueued is not run inside an editor-spawned process. Cloning a remote repository is
+  deliberately not exposed over MCP: it carries its own credentials and stays on REST and the CLI.
+- `JobWorkerPool(job_types=...)` and `claim_next_job(job_types=...)` restrict a pool to a subset
+  of the queue.
+- `bce --env-file PATH` and `BCE_ENV_FILE` load configuration from an explicit `.env`. Editors
+  spawn `bce serve-mcp` from their own working directory, so a bare `.env` was never found and the
+  MCP server silently ran on defaults — no Voyage key, no database password. `serve` and
+  `serve-mcp` accept the option after the command name as well as before it, because that is how
+  an MCP config or a service definition is written.
+
+### Changed
+
+- The MCP catalog is now eight read-only tools instead of fourteen. Removed `semantic_search`,
+  `find_similar_code`, `find_implementers`, `get_type_hierarchy`, `get_dependencies`,
+  `suggest_change_sites`, `select_repos` and `assemble_context`: an agent picks worse when
+  handed a dozen overlapping retrieval tools, and `hybrid_search` and `get_context_for_task`
+  already cover what they did. All of them remain available over REST.
+- The optional `mcp` extra is now `mcp>=1.0,<2`. SDK 2.x dropped `Server.list_tools` /
+  `Server.call_tool`, so `bce serve-mcp` failed on a default `pip install` of 2.x.
+
+### Fixed
+
+- The first search on an MCP server no longer hangs. Building the embedding encoder imports
+  numpy, and loading that extension lazily from inside a tool call stalled for over three
+  minutes on Windows while the same import costs seconds at process start, so the encoder is
+  now built during startup. Tool dispatch also moved off the event loop onto a worker thread,
+  since its database and HTTP calls are synchronous.
+- The MCP server configures logging, against stderr because stdout carries the protocol. Its job
+  worker's failures previously fell through to Python's last-resort handler and surfaced in editor
+  logs as bare tracebacks; they are now the same JSON lines the API server emits, and they reach
+  the log file too. `setup_logging(stream=...)` makes the console destination overridable.
+
+## [0.2.0] - 2026-09-10
+
+### Changed
+
+- Both READMEs now reference images, videos and sibling documents by absolute URL. PyPI
+  renders the long description outside the repository, so relative paths resolved to
+  nothing there: the banner was a broken image and every documentation link a dead one.
+- Selecting `BCE_EMBEDDING_PROVIDER=voyage` without its API key no longer falls back to the
+  hashing encoder. Both that case and a missing `voyageai` package now raise
+  `EncoderConfigError`, which the CLI reports as a single line and the REST API as `503`.
+  A substituted encoder is not detectable by nearest-neighbour search, so it returned bad
+  anchors instead of an error. An unrecognised provider name is rejected the same way.
+- Removed `Settings.voyage_ready`, whose "ready" no longer matched how the encoder is
+  chosen.
+
+## [0.1.0] - 2026-09-08
+
+First public release.
+
+### Added
+
+- Deterministic retrieval pipeline: anchor discovery, graph expansion, scoring, narrowing
+  and context assembly, with coverage and confidence reporting.
+- Code graph over PostgreSQL with Apache AGE and pgvector in a single database. Layer-3
+  results are filtered per user against the `scopes` table, resolved from the
+  `X-BCE-User` header.
+- Tree-sitter indexing for Python, JavaScript and TypeScript, with optional grammars for
+  Java, C# and Go. Incremental re-indexing driven by `git diff`.
+- Layer 1, 2 and 3 tool surfaces exposed over both REST and MCP.
+- Web interface at `/ui`: a graph explorer and a player that replays each pipeline stage
+  for a given task. Ships inside the wheel; English by default with a Turkish catalog.
+- `bce` command line interface: `migrate`, `index`, `index-remote`, `reindex`, `bench`,
+  `resolve-symbol`, `find-references`, `languages`, `serve` and `serve-mcp`.
+- Benchmark harness reporting latency, recall, precision and determinism.
+- Docker Compose deployment with PostgreSQL, Apache AGE and pgvector preconfigured.
+- `server.json` manifest describing the stdio server for the official MCP registry.
+
+[Unreleased]: https://github.com/bgts-ai-org/bgts-context-engine/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/bgts-ai-org/bgts-context-engine/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/bgts-ai-org/bgts-context-engine/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/bgts-ai-org/bgts-context-engine/releases/tag/v0.1.0

{bgts_context_engine-0.2.0/src/bgts_context_engine.egg-info → bgts_context_engine-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bgts-context-engine
-Version: 0.2.0
+Version: 0.2.1
 Summary: Deterministic code-graph context engine for AI coding agents - PostgreSQL, Apache AGE and pgvector, over MCP and REST
 Author: Oğuz Öztürk, Enes İyidil
 Maintainer: BGTS
@@ -42,7 +42,7 @@ Requires-Dist: pytest-cov>=5.0; extra == "dev"
 Requires-Dist: ruff>=0.4; extra == "dev"
 Requires-Dist: httpx>=0.27; extra == "dev"
 Provides-Extra: mcp
-Requires-Dist: mcp>=1.0; extra == "mcp"
+Requires-Dist: mcp<2,>=1.0; extra == "mcp"
 Provides-Extra: embed
 Requires-Dist: voyageai>=0.3; extra == "embed"
 Provides-Extra: langs
@@ -132,16 +132,30 @@ Then serve it:
 
 ```bash
 bce serve        # REST at :8000/docs, web UI at :8000/ui/
-bce serve-mcp    # MCP over stdio, for agents
+bce serve-mcp    # MCP over stdio, for agents (install the [mcp] extra; see below)
 ```
 
 ## Use it from your agent
 
-The MCP surface is behind the `mcp` extra: `pip install "bgts-context-engine[mcp]"`. It
-speaks stdio, so every MCP client configures it the same way — `bce serve-mcp`, plus the
-database connection in the environment.
+The MCP surface is behind the `mcp` extra (Python MCP SDK 1.x: `mcp>=1.0,<2`). Install it
+so `bce` is on the **user PATH**, not only inside a project `.venv`. Cursor and VS Code
+spawn `bce serve-mcp` themselves and do not activate the venv:
 
-**Cursor** — `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project:
+```bash
+pip install "bgts-context-engine[mcp]"
+bce --version   # must work in a new terminal, with no venv activated
+```
+
+Every MCP client uses the same stdio command plus the database in the environment. Do not
+leave `bce serve-mcp` running in a terminal for the editor: stdout is the protocol, so the
+process stays silent, and the IDE starts its own copy.
+
+After you add or change the MCP config, **restart Cursor or VS Code** (or Command Palette
+→ “Developer: Reload Window”). The server should then show as enabled with eight tools (ten with indexing enabled).
+Setup detail: [docs/mcp.md](docs/mcp.md).
+
+**Cursor** — user config `~/.cursor/mcp.json` (applies to every project), or a project
+`.cursor/mcp.json` that stays local (the directory is gitignored):
 
 ```json
 {
@@ -155,31 +169,41 @@ database connection in the environment.
 }
 ```
 
-**Claude Code** — one command:
-
-```bash
-claude mcp add bgts-context-engine --env BCE_DB_HOST=localhost -- bce serve-mcp
-```
-
-**VS Code** — `.vscode/mcp.json`:
+**VS Code** — user MCP settings, or a project `.vscode/mcp.json` (also gitignored):
 
 ```json
 {
   "servers": {
-    "bgts-context-engine": { "type": "stdio", "command": "bce", "args": ["serve-mcp"] }
+    "bgts-context-engine": {
+      "type": "stdio",
+      "command": "bce",
+      "args": ["serve-mcp"],
+      "env": { "BCE_DB_HOST": "localhost", "BCE_DB_NAME": "bce" }
+    }
   }
 }
 ```
 
+**Claude Code** — one command:
+
+```bash
+claude mcp add bgts-context-engine --env BCE_DB_HOST=localhost -- bce serve-mcp
+```
+
 **Claude Desktop** — same block as Cursor, in `claude_desktop_config.json`.
 
-Without a global install, `uvx --from "bgts-context-engine[mcp]" bce serve-mcp` works as the
-`command` anywhere above.
+If `command: "bce"` stays disconnected, the editor cannot see `bce` on PATH. Install as
+above, or skip a permanent install with `uvx`:
+
+```json
+"command": "uvx",
+"args": ["--from", "bgts-context-engine[mcp]", "bce", "serve-mcp"]
+```
 
 Then ask your agent something that needs the repository rather than the file you have open:
 *"what breaks if I change the session TTL?"* The agent calls `get_context_for_task`, and the
-fourteen tools in [docs/mcp.md](docs/mcp.md) let it drill from there — exact callers, type
-hierarchy, route handlers — without guessing at file names.
+other tools in [docs/mcp.md](docs/mcp.md) let it drill from there — exact callers, the blast
+radius of a change, the symbol behind a name — without guessing at file names.
 
 ## What comes back
 
@@ -265,7 +289,7 @@ The full formula, every weight, and the confidence thresholds are in
   moves and reformatting, so history and embeddings stay valid.
 - **One database.** Apache AGE and pgvector in the same PostgreSQL, so one query joins a
   graph traversal, a vector search and a SQL filter — and one `pg_dump` backs up the index.
-- **MCP and REST from one implementation.** Fourteen tools over stdio, the same functions
+- **MCP and REST from one implementation.** A focused tool set over stdio, the same functions
   over HTTP. Nothing to drift.
 - **A UI that explains itself.** `/ui` ships in the wheel and replays a real retrieval call
   stage by stage: anchors lighting up, expansion spreading, candidates scored and cut.
@@ -337,7 +361,7 @@ actually ask for reorders this list.
 | [Architecture](docs/architecture.md) | the deterministic line, the three layers, indexing |
 | [Retrieval](docs/retrieval.md) | anchors, expansion, every scoring weight, confidence |
 | [Data model](docs/data-model.md) | node labels, edge types, tables, symbol identity |
-| [MCP and API](docs/mcp.md) | all 14 tools, every endpoint, the CLI |
+| [MCP and API](docs/mcp.md) | every tool and endpoint, MCP configuration, the CLI |
 | [Languages](docs/languages.md) | what each parser extracts, and how to add one |
 | [Deployment](docs/deployment.md) | configuration reference, jobs, backup, benchmarking |
 | [Web interface](web/README.md) | developing the frontend |
@@ -368,6 +392,3 @@ rather than in an issue.
 ## License
 
 [MIT](LICENSE) © BGTS.
-
-Built by [Oğuz Öztürk](https://github.com/oztrkoguz) and
-[Enes İyidil](https://github.com/enesiyidil).

{bgts_context_engine-0.2.0 → bgts_context_engine-0.2.1}/README.md

@@ -79,16 +79,30 @@ Then serve it:
 
 ```bash
 bce serve        # REST at :8000/docs, web UI at :8000/ui/
-bce serve-mcp    # MCP over stdio, for agents
+bce serve-mcp    # MCP over stdio, for agents (install the [mcp] extra; see below)
 ```
 
 ## Use it from your agent
 
-The MCP surface is behind the `mcp` extra: `pip install "bgts-context-engine[mcp]"`. It
-speaks stdio, so every MCP client configures it the same way — `bce serve-mcp`, plus the
-database connection in the environment.
+The MCP surface is behind the `mcp` extra (Python MCP SDK 1.x: `mcp>=1.0,<2`). Install it
+so `bce` is on the **user PATH**, not only inside a project `.venv`. Cursor and VS Code
+spawn `bce serve-mcp` themselves and do not activate the venv:
 
-**Cursor** — `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project:
+```bash
+pip install "bgts-context-engine[mcp]"
+bce --version   # must work in a new terminal, with no venv activated
+```
+
+Every MCP client uses the same stdio command plus the database in the environment. Do not
+leave `bce serve-mcp` running in a terminal for the editor: stdout is the protocol, so the
+process stays silent, and the IDE starts its own copy.
+
+After you add or change the MCP config, **restart Cursor or VS Code** (or Command Palette
+→ “Developer: Reload Window”). The server should then show as enabled with eight tools (ten with indexing enabled).
+Setup detail: [docs/mcp.md](docs/mcp.md).
+
+**Cursor** — user config `~/.cursor/mcp.json` (applies to every project), or a project
+`.cursor/mcp.json` that stays local (the directory is gitignored):
 
 ```json
 {
@@ -102,31 +116,41 @@ database connection in the environment.
 }
 ```
 
-**Claude Code** — one command:
-
-```bash
-claude mcp add bgts-context-engine --env BCE_DB_HOST=localhost -- bce serve-mcp
-```
-
-**VS Code** — `.vscode/mcp.json`:
+**VS Code** — user MCP settings, or a project `.vscode/mcp.json` (also gitignored):
 
 ```json
 {
   "servers": {
-    "bgts-context-engine": { "type": "stdio", "command": "bce", "args": ["serve-mcp"] }
+    "bgts-context-engine": {
+      "type": "stdio",
+      "command": "bce",
+      "args": ["serve-mcp"],
+      "env": { "BCE_DB_HOST": "localhost", "BCE_DB_NAME": "bce" }
+    }
   }
 }
 ```
 
+**Claude Code** — one command:
+
+```bash
+claude mcp add bgts-context-engine --env BCE_DB_HOST=localhost -- bce serve-mcp
+```
+
 **Claude Desktop** — same block as Cursor, in `claude_desktop_config.json`.
 
-Without a global install, `uvx --from "bgts-context-engine[mcp]" bce serve-mcp` works as the
-`command` anywhere above.
+If `command: "bce"` stays disconnected, the editor cannot see `bce` on PATH. Install as
+above, or skip a permanent install with `uvx`:
+
+```json
+"command": "uvx",
+"args": ["--from", "bgts-context-engine[mcp]", "bce", "serve-mcp"]
+```
 
 Then ask your agent something that needs the repository rather than the file you have open:
 *"what breaks if I change the session TTL?"* The agent calls `get_context_for_task`, and the
-fourteen tools in [docs/mcp.md](docs/mcp.md) let it drill from there — exact callers, type
-hierarchy, route handlers — without guessing at file names.
+other tools in [docs/mcp.md](docs/mcp.md) let it drill from there — exact callers, the blast
+radius of a change, the symbol behind a name — without guessing at file names.
 
 ## What comes back
 
@@ -212,7 +236,7 @@ The full formula, every weight, and the confidence thresholds are in
   moves and reformatting, so history and embeddings stay valid.
 - **One database.** Apache AGE and pgvector in the same PostgreSQL, so one query joins a
   graph traversal, a vector search and a SQL filter — and one `pg_dump` backs up the index.
-- **MCP and REST from one implementation.** Fourteen tools over stdio, the same functions
+- **MCP and REST from one implementation.** A focused tool set over stdio, the same functions
   over HTTP. Nothing to drift.
 - **A UI that explains itself.** `/ui` ships in the wheel and replays a real retrieval call
   stage by stage: anchors lighting up, expansion spreading, candidates scored and cut.
@@ -284,7 +308,7 @@ actually ask for reorders this list.
 | [Architecture](docs/architecture.md) | the deterministic line, the three layers, indexing |
 | [Retrieval](docs/retrieval.md) | anchors, expansion, every scoring weight, confidence |
 | [Data model](docs/data-model.md) | node labels, edge types, tables, symbol identity |
-| [MCP and API](docs/mcp.md) | all 14 tools, every endpoint, the CLI |
+| [MCP and API](docs/mcp.md) | every tool and endpoint, MCP configuration, the CLI |
 | [Languages](docs/languages.md) | what each parser extracts, and how to add one |
 | [Deployment](docs/deployment.md) | configuration reference, jobs, backup, benchmarking |
 | [Web interface](web/README.md) | developing the frontend |
@@ -315,6 +339,3 @@ rather than in an issue.
 ## License
 
 [MIT](LICENSE) © BGTS.
-
-Built by [Oğuz Öztürk](https://github.com/oztrkoguz) and
-[Enes İyidil](https://github.com/enesiyidil).

{bgts_context_engine-0.2.0 → bgts_context_engine-0.2.1}/README.tr.md

@@ -79,16 +79,30 @@ Ardından servis edin:
 
 ```bash
 bce serve        # :8000/docs adresinde REST, :8000/ui/ adresinde web arayüzü
-bce serve-mcp    # ajanlar için stdio üzerinden MCP
+bce serve-mcp    # ajanlar için stdio üzerinden MCP ([mcp] eki gerekir; aşağıya bakın)
 ```
 
 ## Ajanınızdan kullanma
 
-MCP yüzeyi `mcp` ekinin arkasındadır: `pip install "bgts-context-engine[mcp]"`. stdio
-konuştuğu için her MCP istemcisi aynı şekilde yapılandırılır — `bce serve-mcp` ve ortamda
-veritabanı bağlantısı.
+MCP yüzeyi `mcp` ekinin arkasındadır (Python MCP SDK 1.x: `mcp>=1.0,<2`). `bce` komutunu
+yalnızca proje `.venv` içine değil, **kullanıcı PATH'ine** kurun. Cursor ve VS Code
+`bce serve-mcp` sürecini kendileri başlatır; sanal ortamı etkinleştirmezler:
 
-**Cursor** — proje içinde `.cursor/mcp.json`, ya da tüm projeler için `~/.cursor/mcp.json`:
+```bash
+pip install "bgts-context-engine[mcp]"
+bce --version   # venv kapalı, yeni bir terminalde çalışmalı
+```
+
+Her MCP istemcisi aynı stdio komutunu ve ortamındaki veritabanı bağlantısını kullanır.
+Editör için terminalde `bce serve-mcp` açık bırakmayın: stdout protokoldür, bu yüzden
+süreç sessiz kalır; IDE kendi kopyasını başlatır.
+
+MCP yapılandırmasını ekledikten veya değiştirdikten sonra **Cursor veya VS Code'u
+yeniden başlatın** (veya Komut Paleti → “Developer: Reload Window”). Sunucu sekiz araçla
+(indeksleme açıkken on araçla) etkin görünmelidir. Ayrıntı: [docs/mcp.md](docs/mcp.md).
+
+**Cursor** — her proje için kullanıcı yapılandırması `~/.cursor/mcp.json`, ya da yerelde
+kalan bir proje `.cursor/mcp.json` (dizin gitignore'dadır):
 
 ```json
 {
@@ -102,31 +116,42 @@ veritabanı bağlantısı.
 }
 ```
 
-**Claude Code** — tek komut:
-
-```bash
-claude mcp add bgts-context-engine --env BCE_DB_HOST=localhost -- bce serve-mcp
-```
-
-**VS Code** — `.vscode/mcp.json`:
+**VS Code** — kullanıcı MCP ayarları, ya da proje `.vscode/mcp.json` (o da gitignore'dadır):
 
 ```json
 {
   "servers": {
-    "bgts-context-engine": { "type": "stdio", "command": "bce", "args": ["serve-mcp"] }
+    "bgts-context-engine": {
+      "type": "stdio",
+      "command": "bce",
+      "args": ["serve-mcp"],
+      "env": { "BCE_DB_HOST": "localhost", "BCE_DB_NAME": "bce" }
+    }
   }
 }
 ```
 
+**Claude Code** — tek komut:
+
+```bash
+claude mcp add bgts-context-engine --env BCE_DB_HOST=localhost -- bce serve-mcp
+```
+
 **Claude Desktop** — `claude_desktop_config.json` içinde Cursor ile aynı blok.
 
-Global kurulum istemiyorsanız yukarıdaki her yerde `command` olarak
-`uvx --from "bgts-context-engine[mcp]" bce serve-mcp` kullanılabilir.
+`"command": "bce"` bağlı kalmazsa editör PATH'te `bce` görmüyordur. Yukarıdaki gibi
+kurun, ya da kalıcı kurulum olmadan `uvx` kullanın:
+
+```json
+"command": "uvx",
+"args": ["--from", "bgts-context-engine[mcp]", "bce", "serve-mcp"]
+```
 
 Sonra ajanınıza, açık olan dosyayı değil deponun tamamını gerektiren bir şey sorun:
 *"session TTL'i değiştirirsem ne bozulur?"* Ajan `get_context_for_task`'ı çağırır;
-[docs/mcp.md](docs/mcp.md) içindeki on dört araç ise oradan devam etmesini sağlar — kesin
-çağıranlar, tip hiyerarşisi, route handler'ları — dosya adlarını tahmin etmeden.
+[docs/mcp.md](docs/mcp.md) içindeki diğer araçlar ise oradan devam etmesini sağlar — kesin
+çağıranlar, bir değişikliğin etki alanı, bir adın arkasındaki sembol — dosya adlarını tahmin
+etmeden.
 
 ## Ne döner
 
@@ -214,8 +239,8 @@ Formülün tamamı, her ağırlık ve güven eşikleri
   Sembol kimlikleri dosya taşımalarından ve yeniden biçimlendirmeden sağ çıkar.
 - **Tek veritabanı.** Apache AGE ve pgvector aynı PostgreSQL içinde; tek sorgu bir graf
   gezinmesini, bir vektör aramasını ve bir SQL filtresini birleştirir.
-- **Tek gerçeklemeden MCP ve REST.** stdio üzerinden on dört araç, HTTP üzerinden aynı
-  fonksiyonlar. Aralarında kayma olacak bir şey yok.
+- **Tek gerçeklemeden MCP ve REST.** stdio üzerinden odaklı bir araç kümesi, HTTP üzerinden
+  aynı fonksiyonlar. Aralarında kayma olacak bir şey yok.
 - **Kendini açıklayan bir arayüz.** `/ui` wheel içinde gelir ve gerçek bir getirme çağrısını
   aşama aşama oynatır: çapaların yanması, genişlemenin yayılması, adayların skorlanıp
   kesilmesi.
@@ -290,7 +315,7 @@ Tümü İngilizcedir.
 | [Architecture](docs/architecture.md) | deterministik hat, üç katman, indeksleme |
 | [Retrieval](docs/retrieval.md) | çapalar, genişletme, her skorlama ağırlığı, güven |
 | [Data model](docs/data-model.md) | düğüm etiketleri, kenar tipleri, tablolar, sembol kimliği |
-| [MCP and API](docs/mcp.md) | 14 aracın tamamı, her uç nokta, CLI |
+| [MCP and API](docs/mcp.md) | her araç ve uç nokta, MCP yapılandırması, CLI |
 | [Languages](docs/languages.md) | her parser'ın çıkardıkları ve yeni dil ekleme |
 | [Deployment](docs/deployment.md) | yapılandırma referansı, işler, yedekleme, ölçüm |
 | [Web interface](web/README.md) | arayüz geliştirme |
@@ -324,6 +349,3 @@ issue olarak değil, özel kanaldan bildirin.
 ## Lisans
 
 [MIT](LICENSE) © BGTS.
-
-[Oğuz Öztürk](https://github.com/oztrkoguz) ve
-[Enes İyidil](https://github.com/enesiyidil) tarafından geliştirildi.

{bgts_context_engine-0.2.0 → bgts_context_engine-0.2.1}/pyproject.toml

@@ -69,8 +69,10 @@ dev = [
     "httpx>=0.27",
 ]
 # Agent-native MCP surface (spec section 7). Optional: the REST API works without it.
+# Pin below 2.x: the Python SDK 2.x removed Server.list_tools / Server.call_tool, which
+# bce serve-mcp still uses.
 mcp = [
-    "mcp>=1.0",
+    "mcp>=1.0,<2",
 ]
 # Voyage AI embeddings (Phase 2). Optional: the hashing fallback works without it.
 embed = [

{bgts_context_engine-0.2.0 → bgts_context_engine-0.2.1}/src/bce/__init__.py

@@ -5,4 +5,4 @@ specification for details. This package is the provider side of the deterministi
 contains no LLM and produces reproducible context packages.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"

bgts_context_engine-0.2.1/src/bce/api/mcp/server.py

@@ -0,0 +1,123 @@
+"""MCP server wiring (optional ``mcp`` SDK).
+
+Binds the SDK-independent tool catalog (:mod:`bce.api.mcp.tools`) to a real MCP server. The ``mcp``
+package is an optional dependency; importing this module without it raises a clear error only when
+you actually try to build/run the server, so the rest of the package (and tests) stay importable.
+
+Each tool call opens a fresh database connection (single DB: graph + vector, P5), dispatches to the
+core, and returns the deterministic envelope as JSON text content. Read tools roll back; the indexing
+tools enqueue a job and commit.
+
+Dispatch is synchronous (psycopg queries, and an HTTP call to the embedding provider), so it runs on a
+worker thread rather than on the event loop that drives the stdio transport.
+
+Indexing over MCP is opt-in via ``BCE_MCP_ALLOW_WRITE``. When it is on, this process also runs a job
+worker pool, so queued indexing progresses without a separate ``bce serve``; the queue claims rows
+with ``FOR UPDATE SKIP LOCKED``, so running both is safe. The pool claims only the job types the MCP
+tools can enqueue, leaving remote clones to the API server.
+
+Logging is configured against stderr. Without it the worker's failures fell back to Python's
+last-resort handler, which prints a bare traceback; with it they are the same JSON lines the API
+server emits, and they reach the log file too.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from typing import Any
+
+
+def build_server(name: str = "bgts-context-engine") -> Any:
+    """Construct an MCP ``Server`` exposing the BCE tool catalog. Requires the ``mcp`` package."""
+    try:
+        import anyio.to_thread  # installed with mcp
+        from mcp.server import Server
+        from mcp.types import TextContent, Tool
+    except ModuleNotFoundError as exc:  # pragma: no cover - depends on optional dep
+        raise RuntimeError(
+            "The 'mcp' package is required for the MCP server. Install it with: pip install mcp"
+        ) from exc
+
+    from bce.api.mcp.tools import WRITE_TOOLS, available_tool_specs, dispatch_tool
+    from bce.config import get_settings
+    from bce.storage.relational.db import connection
+
+    allow_write = get_settings().mcp_allow_write
+    specs = available_tool_specs(allow_write=allow_write)
+    server = Server(name)
+
+    @server.list_tools()
+    async def _list_tools() -> list[Tool]:  # pragma: no cover - requires SDK runtime
+        return [
+            Tool(name=tool, description=spec["description"], inputSchema=spec["schema"])
+            for tool, spec in specs.items()
+        ]
+
+    def _dispatch_blocking(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+        with connection() as conn:
+            try:
+                result = dispatch_tool(conn, name, arguments, allow_write=allow_write)
+                if name in WRITE_TOOLS:
+                    conn.commit()  # persist the queued job
+                else:
+                    conn.rollback()  # read-only tools never persist
+            except Exception:
+                conn.rollback()
+                raise
+        return result
+
+    @server.call_tool()
+    async def _call_tool(
+        name: str, arguments: dict[str, Any]
+    ) -> list[TextContent]:  # pragma: no cover
+        result = await anyio.to_thread.run_sync(_dispatch_blocking, name, arguments)
+        return [TextContent(type="text", text=json.dumps(result, ensure_ascii=False, default=str))]
+
+    return server
+
+
+def _warm_encoder() -> None:  # pragma: no cover - SDK runtime
+    """Build the embedding encoder once, before serving, so no tool call pays for it.
+
+    The Voyage SDK imports numpy, and loading that extension lazily from inside a tool call stalls
+    for minutes on Windows, where the same import costs seconds at process start. A provider that is
+    misconfigured is not fatal: only the search tools need an encoder, and they already raise a clear
+    error per call, so the graph tools stay usable.
+    """
+    from bce.indexing.embedder.encoder import build_default_encoder
+
+    try:
+        build_default_encoder()
+    except Exception as exc:
+        logging.getLogger("bce.api.mcp").warning(
+            "embedding encoder unavailable; search tools will fail", extra={"detail": str(exc)}
+        )
+
+
+async def run_stdio(name: str = "bgts-context-engine") -> None:  # pragma: no cover - SDK runtime
+    """Run the MCP server over stdio (the common agent transport)."""
+    from mcp.server.stdio import stdio_server
+
+    from bce.api.mcp.tools import MCP_JOB_TYPES
+    from bce.config import get_settings
+    from bce.core.logging import setup_logging
+
+    # stdout carries the protocol, so logs go to stderr, which editors surface as server logs.
+    setup_logging(stream=sys.stderr)
+
+    server = build_server(name)
+    _warm_encoder()
+    pool = None
+    if get_settings().mcp_allow_write:
+        from bce.jobs.worker import JobWorkerPool
+
+        pool = JobWorkerPool(job_types=MCP_JOB_TYPES)
+        pool.start()
+    try:
+        async with stdio_server() as (read, write):
+            await server.run(read, write, server.create_initialization_options())
+    finally:
+        if pool is not None:
+            pool.stop()