bgts-context-engine 0.2.3__tar.gz → 0.2.5__tar.gz

{bgts_context_engine-0.2.3 → bgts_context_engine-0.2.5}/CHANGELOG.md

@@ -7,6 +7,80 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.2.5] - 2026-09-24
+
+### Changed
+
+- The English and Turkish READMEs link to the project website
+  ([bgts-ai-org.github.io/bce-microsite](https://bgts-ai-org.github.io/bce-microsite/))
+  from the top navigation.
+
+## [0.2.4] - 2026-09-22
+
+This release turns the agent benchmark (a Cursor CLI agent on 14 tasks against a
+React/TypeScript codebase, plain vs. with the engine) into product behaviour. The MCP server alone made a Cursor agent *worse*: it asked the graph late (after
+a round of grep) or eight times per task, and the answer it got back had no file or line.
+With one advertised tool, a rule that says "call it first and treat `file:line` as a
+verified location", the answer handed over before the first turn, and a shorter context
+budget, the same agent on the same 14 tasks, model and machine used 20 % fewer tokens,
+produced 46 % less grep/glob output and 13 % fewer model turns, passed 73/73 checks against
+72/73, and changed 23 % fewer lines. Everything below is what that took.
+
+### Added
+
+- `bce cursor-init [--project DIR] [--repo-id ID]... [--env-file PATH] [--bce-command X]`:
+  writes a project's `.cursor/mcp.json` (merged into an existing one; other servers are
+  kept) with the absolute path of the running `bce`, `serve-mcp --env-file …` and
+  `PYTHONUTF8=1`, plus the `alwaysApply` rule `.cursor/rules/bgts-context-engine.mdc`. The
+  rule ships in the wheel as a template, so every install gets the same instruction: call
+  `get_context_for_task` first with the full task text, open the returned `file:line`
+  entries directly instead of grepping for them, treat the list as places to inspect rather
+  than files to edit, never repeat a call with the same text. Idempotent.
+- `bce claude-init …[--no-hook]`: the Claude Code counterpart — `.mcp.json` (merged), a
+  section in `CLAUDE.md` between `<!-- bgts-context-engine:begin/end -->` markers (the rest
+  of the file is kept), and by default a `UserPromptSubmit` hook in `.claude/settings.json`
+  (other hooks kept) that runs `bce precontext` before every prompt. Cursor gets no hook: its
+  `beforeSubmitPrompt` event can only allow or block a prompt, so there the rule carries the
+  instruction and the agent makes the one call itself.
+- `bce precontext [--task TEXT] [--repo-id ID]...`: the compact "Code context for this
+  task" block an agent prompt carries — a file list in rank order, then one line per symbol
+  (`path:line kind name distance`) with a snippet of at most 12 lines where the snippet says
+  more than the name; about 5 k characters at the default budget. Without `--task` it is the
+  Claude Code hook: reads the hook JSON on stdin, skips prompts under 20 characters and slash
+  commands, prints `hookSpecificOutput.additionalContext` capped at Claude Code's
+  10 000-character limit, and fails open (an unreachable database is a prompt without
+  context, never a blocked prompt). `bce.integrations.precontext.render_context_markdown`
+  is the renderer, for other hosts.
+- `BCE_MCP_TOOLS`: comma-separated names the MCP server advertises (default: all read
+  tools). Agents fetch a tool's schema before first use and chain small calls when many
+  tools are on offer; the benchmark ran with `get_context_for_task` alone. Unknown names
+  fail at startup, and a tool not advertised cannot be dispatched either.
+- `BCE_EMBEDDING_QUERY_TIMEOUT` (10 s, two attempts): the wait for embedding a single
+  *query* at search time, separate from the indexing timeout (600 s). When it expires,
+  `get_context_for_task` and `suggest_change_sites` answer from lexical and structural
+  anchors alone — visible as lower `coverage.confidence` — instead of failing after having
+  waited past an agent's MCP timeout (Cursor: 60 s). Motivated by a RunPod TCP proxy that
+  stalled connects for 19–67 s during the benchmark.
+- Context items carry `name`, `kind`, `file_id` and `line` next to `symbol_id`. Without
+  them an agent had to search the tree for the file behind every symbol id (the module path
+  does not say `.ts` vs `.tsx`, nor the line) — one tool call, one model turn, per item.
+
+### Changed
+
+- **Defaults: `max_candidates` 8 → 20, `max_tokens` 4000 → 1500**, on every surface (CLI
+  `bce context`, REST, MCP schema defaults, and the `bce.core.defaults` module they all
+  read). K=20 is where recall@K flattened in the PR replay for both fitted profiles and
+  what the agent benchmark ran with. The budget is shorter because an agent re-sends the
+  context on every turn: at 1500 it travelled as ~1.3 k tokens per turn and still halved
+  the agent's search output; 4000 travelled as ~4 k per turn for no further gain. Callers
+  wanting longer snippets pass `max_tokens` per request; the assembler still degrades items
+  to reference level rather than dropping them.
+- `.env.example` shows `voyage-code-4` (the model the voyage profile was fitted on) as the
+  Voyage example and documents `BCE_EMBEDDING_QUERY_TIMEOUT` and `BCE_MCP_TOOLS`. The code
+  default stays `voyage-code-3` so indexes built with it keep matching.
+- `server.json` describes the catalog as eight read-only tools plus two write tools rather
+  than "14 tools".
+
 ## [0.2.3] - 2026-09-21
 
 ### Added
@@ -304,7 +378,9 @@ First public release.
 - 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.3...HEAD
+[Unreleased]: https://github.com/bgts-ai-org/bgts-context-engine/compare/v0.2.5...HEAD
+[0.2.5]: https://github.com/bgts-ai-org/bgts-context-engine/compare/v0.2.4...v0.2.5
+[0.2.4]: https://github.com/bgts-ai-org/bgts-context-engine/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/bgts-ai-org/bgts-context-engine/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/bgts-ai-org/bgts-context-engine/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/bgts-ai-org/bgts-context-engine/compare/v0.2.0...v0.2.1

{bgts_context_engine-0.2.3 → bgts_context_engine-0.2.5}/MANIFEST.in

@@ -4,6 +4,7 @@ include README.tr.md
 include CHANGELOG.md
 recursive-include src/bce/core/i18n/catalogs *.json
 recursive-include src/bce/storage/relational/migrations *.sql
+recursive-include src/bce/integrations/templates *.mdc *.md
 
 # Compiled frontend, vendored by scripts/build_ui.py before a release build.
 recursive-include src/bce/api/rest/static *

{bgts_context_engine-0.2.3/src/bgts_context_engine.egg-info → bgts_context_engine-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bgts-context-engine
-Version: 0.2.3
+Version: 0.2.5
 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
@@ -69,7 +69,7 @@ that actually answer it — ranked, budgeted, and reproducible.
 [![MCP](https://img.shields.io/badge/MCP-compatible-000000.svg)](docs/mcp.md)
 [![Stars](https://img.shields.io/github/stars/bgts-ai-org/bgts-context-engine?style=flat&logo=github)](https://github.com/bgts-ai-org/bgts-context-engine/stargazers)
 
-[Quick start](#quick-start) · [Use it from your agent](#use-it-from-your-agent) · [How it works](#how-it-works) · [Supported models](#supported-models) · [Documentation](#documentation) · [Türkçe](README.tr.md)
+[Quick start](#quick-start) · [Use it from your agent](#use-it-from-your-agent) · [How it works](#how-it-works) · [Supported models](#supported-models) · [Documentation](#documentation) · [Website](https://bgts-ai-org.github.io/bce-microsite/) · [Türkçe](README.tr.md)
 
 </div>
 
@@ -150,9 +150,28 @@ Every MCP client uses the same stdio command plus the database in the environmen
 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.
 
+**One command per editor.** Run it in the project the agent works on (the repository you
+indexed), pointing at the engine's `.env`:
+
+```bash
+bce --env-file /path/to/engine/.env cursor-init --repo-id my-service   # Cursor
+bce --env-file /path/to/engine/.env claude-init --repo-id my-service   # Claude Code
+```
+
+`cursor-init` writes `.cursor/mcp.json` (merged into an existing one) and the rule
+`.cursor/rules/bgts-context-engine.mdc`, which tells the agent to call
+`get_context_for_task` *first*, treat its `file:line` entries as verified locations instead
+of grepping for them, and not to edit a file just because it was listed. `claude-init`
+writes `.mcp.json`, a marked section in `CLAUDE.md`, and a `UserPromptSubmit` hook
+(`bce precontext`) that runs the graph once per prompt and hands the agent the answer
+before its first turn — the flow the agent benchmark measured (−20 % tokens, half the search
+output, same or better checks; 14 tasks on a React/TypeScript codebase, same model and machine).
+Cursor's prompt hook cannot add context, so there the rule does that job. `--no-hook`,
+`--repo-id` (repeatable) and `--bce-command` adjust the files; both commands are safe to rerun.
+
 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).
+Setup detail: [docs/mcp.md](docs/mcp.md). The manual equivalents:
 
 **Cursor** — user config `~/.cursor/mcp.json` (applies to every project), or a project
 `.cursor/mcp.json` that stays local (the directory is gitignored):
@@ -217,12 +236,14 @@ Not a list of file paths. A ranked pack, with the reasoning attached:
   },
   "context": {
     "items": [
-      { "symbol_id": "...refresh_session#88c2", "detail_level": "full",
+      { "symbol_id": "...refresh_session#88c2", "name": "refresh_session", "kind": "function",
+        "file_id": "my-service:src/auth/session.py", "line": 41, "detail_level": "full",
         "graph_distance": 0, "score": 11.42, "tokens": 214, "content": "def refresh_session(...)" },
-      { "symbol_id": "...SESSION_TTL#4b0d",     "detail_level": "signature",
+      { "symbol_id": "...SESSION_TTL#4b0d", "name": "SESSION_TTL", "kind": "constant",
+        "file_id": "my-service:src/auth/config.py", "line": 12, "detail_level": "signature",
         "graph_distance": 2, "score": 6.10,  "tokens": 31,  "content": "SESSION_TTL: int" }
     ],
-    "used_tokens": 2913, "budget": 4000, "included": 8, "skipped": 0
+    "used_tokens": 1388, "budget": 1500, "included": 20, "skipped": 0
   },
   "coverage": {
     "anchor_source_count": 3, "connected_component_ratio": 0.875,
@@ -243,8 +264,10 @@ could not corroborate it — the moment for an agent to ask a follow-up question
 editing. `commit_mismatch` means the index is behind your working tree.
 
 **`detail_level`** falls off with graph distance: the symbol you are changing arrives in
-full, its neighbours as signatures, the outer ring as `name @ file:line`. That is how eight
-genuinely relevant symbols fit in 4000 tokens.
+full, its neighbours as signatures, the outer ring as `name @ file:line`. That is how twenty
+genuinely relevant symbols fit in 1500 tokens — short enough for an agent to carry on every
+turn. Every item also names its `file_id` and `line`, so the agent opens the file instead of
+searching for the symbol.
 
 ## How it works
 

{bgts_context_engine-0.2.3 → bgts_context_engine-0.2.5}/README.md

@@ -16,7 +16,7 @@ that actually answer it — ranked, budgeted, and reproducible.
 [![MCP](https://img.shields.io/badge/MCP-compatible-000000.svg)](docs/mcp.md)
 [![Stars](https://img.shields.io/github/stars/bgts-ai-org/bgts-context-engine?style=flat&logo=github)](https://github.com/bgts-ai-org/bgts-context-engine/stargazers)
 
-[Quick start](#quick-start) · [Use it from your agent](#use-it-from-your-agent) · [How it works](#how-it-works) · [Supported models](#supported-models) · [Documentation](#documentation) · [Türkçe](README.tr.md)
+[Quick start](#quick-start) · [Use it from your agent](#use-it-from-your-agent) · [How it works](#how-it-works) · [Supported models](#supported-models) · [Documentation](#documentation) · [Website](https://bgts-ai-org.github.io/bce-microsite/) · [Türkçe](README.tr.md)
 
 </div>
 
@@ -97,9 +97,28 @@ Every MCP client uses the same stdio command plus the database in the environmen
 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.
 
+**One command per editor.** Run it in the project the agent works on (the repository you
+indexed), pointing at the engine's `.env`:
+
+```bash
+bce --env-file /path/to/engine/.env cursor-init --repo-id my-service   # Cursor
+bce --env-file /path/to/engine/.env claude-init --repo-id my-service   # Claude Code
+```
+
+`cursor-init` writes `.cursor/mcp.json` (merged into an existing one) and the rule
+`.cursor/rules/bgts-context-engine.mdc`, which tells the agent to call
+`get_context_for_task` *first*, treat its `file:line` entries as verified locations instead
+of grepping for them, and not to edit a file just because it was listed. `claude-init`
+writes `.mcp.json`, a marked section in `CLAUDE.md`, and a `UserPromptSubmit` hook
+(`bce precontext`) that runs the graph once per prompt and hands the agent the answer
+before its first turn — the flow the agent benchmark measured (−20 % tokens, half the search
+output, same or better checks; 14 tasks on a React/TypeScript codebase, same model and machine).
+Cursor's prompt hook cannot add context, so there the rule does that job. `--no-hook`,
+`--repo-id` (repeatable) and `--bce-command` adjust the files; both commands are safe to rerun.
+
 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).
+Setup detail: [docs/mcp.md](docs/mcp.md). The manual equivalents:
 
 **Cursor** — user config `~/.cursor/mcp.json` (applies to every project), or a project
 `.cursor/mcp.json` that stays local (the directory is gitignored):
@@ -164,12 +183,14 @@ Not a list of file paths. A ranked pack, with the reasoning attached:
   },
   "context": {
     "items": [
-      { "symbol_id": "...refresh_session#88c2", "detail_level": "full",
+      { "symbol_id": "...refresh_session#88c2", "name": "refresh_session", "kind": "function",
+        "file_id": "my-service:src/auth/session.py", "line": 41, "detail_level": "full",
         "graph_distance": 0, "score": 11.42, "tokens": 214, "content": "def refresh_session(...)" },
-      { "symbol_id": "...SESSION_TTL#4b0d",     "detail_level": "signature",
+      { "symbol_id": "...SESSION_TTL#4b0d", "name": "SESSION_TTL", "kind": "constant",
+        "file_id": "my-service:src/auth/config.py", "line": 12, "detail_level": "signature",
         "graph_distance": 2, "score": 6.10,  "tokens": 31,  "content": "SESSION_TTL: int" }
     ],
-    "used_tokens": 2913, "budget": 4000, "included": 8, "skipped": 0
+    "used_tokens": 1388, "budget": 1500, "included": 20, "skipped": 0
   },
   "coverage": {
     "anchor_source_count": 3, "connected_component_ratio": 0.875,
@@ -190,8 +211,10 @@ could not corroborate it — the moment for an agent to ask a follow-up question
 editing. `commit_mismatch` means the index is behind your working tree.
 
 **`detail_level`** falls off with graph distance: the symbol you are changing arrives in
-full, its neighbours as signatures, the outer ring as `name @ file:line`. That is how eight
-genuinely relevant symbols fit in 4000 tokens.
+full, its neighbours as signatures, the outer ring as `name @ file:line`. That is how twenty
+genuinely relevant symbols fit in 1500 tokens — short enough for an agent to carry on every
+turn. Every item also names its `file_id` and `line`, so the agent opens the file instead of
+searching for the symbol.
 
 ## How it works
 

{bgts_context_engine-0.2.3 → bgts_context_engine-0.2.5}/README.tr.md

@@ -14,7 +14,7 @@ veren sekiz sembolü sıralanmış, bütçelenmiş ve yeniden üretilebilir şek
 [![MCP](https://img.shields.io/badge/MCP-uyumlu-000000.svg)](docs/mcp.md)
 [![Yıldızlar](https://img.shields.io/github/stars/bgts-ai-org/bgts-context-engine?style=flat&logo=github)](https://github.com/bgts-ai-org/bgts-context-engine/stargazers)
 
-[Hızlı başlangıç](#hızlı-başlangıç) · [Ajanınızdan kullanma](#ajanınızdan-kullanma) · [Nasıl çalışır](#nasıl-çalışır) · [Desteklenen modeller](#desteklenen-modeller) · [Dokümantasyon](#dokümantasyon) · [English](README.md)
+[Hızlı başlangıç](#hızlı-başlangıç) · [Ajanınızdan kullanma](#ajanınızdan-kullanma) · [Nasıl çalışır](#nasıl-çalışır) · [Desteklenen modeller](#desteklenen-modeller) · [Dokümantasyon](#dokümantasyon) · [Site](https://bgts-ai-org.github.io/bce-microsite/) · [English](README.md)
 
 </div>
 
@@ -97,9 +97,31 @@ Her MCP istemcisi aynı stdio komutunu ve ortamındaki veritabanı bağlantısı
 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.
 
+**Editör başına tek komut.** Ajanın çalıştığı projede (indekslediğiniz depoda), motorun
+`.env` dosyasını göstererek çalıştırın:
+
+```bash
+bce --env-file /path/to/engine/.env cursor-init --repo-id my-service   # Cursor
+bce --env-file /path/to/engine/.env claude-init --repo-id my-service   # Claude Code
+```
+
+`cursor-init`, `.cursor/mcp.json` dosyasını (varsa üzerine birleştirerek) ve
+`.cursor/rules/bgts-context-engine.mdc` kuralını yazar. Kural ajana şunları söyler:
+`get_context_for_task` aracını *ilk iş olarak* çağır, döndürdüğü `dosya:satır`
+girdilerini doğrulanmış konum say ve onları grep ile arama, listelendi diye bir dosyayı
+düzenleme. `claude-init` ise `.mcp.json`, `CLAUDE.md` içinde işaretli bir bölüm ve
+`bce precontext` komutunu çalıştıran bir `UserPromptSubmit` kancası yazar: kanca her
+istemde grafı bir kez sorgular ve yanıtı ajana ilk turundan önce verir. Ajan
+benchmark'ında ölçülen akış budur (−%20 token, yarıya inen arama çıktısı, eşit veya daha
+iyi kontroller; React/TypeScript bir kod tabanında 14 görev, aynı model ve makine).
+Cursor'ın istem kancası bağlam ekleyemediği için orada bu işi kural yapar. `--no-hook`,
+`--repo-id` (tekrarlanabilir) ve `--bce-command` dosyaları ayarlar; iki komut da tekrar
+çalıştırılmaya uygundur.
+
 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).
+Elle yapmanın karşılıkları:
 
 **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):
@@ -165,12 +187,14 @@ Dosya yolu listesi değil. Gerekçesi ekli, sıralanmış bir paket:
   },
   "context": {
     "items": [
-      { "symbol_id": "...refresh_session#88c2", "detail_level": "full",
+      { "symbol_id": "...refresh_session#88c2", "name": "refresh_session", "kind": "function",
+        "file_id": "my-service:src/auth/session.py", "line": 41, "detail_level": "full",
         "graph_distance": 0, "score": 11.42, "tokens": 214, "content": "def refresh_session(...)" },
-      { "symbol_id": "...SESSION_TTL#4b0d",     "detail_level": "signature",
+      { "symbol_id": "...SESSION_TTL#4b0d", "name": "SESSION_TTL", "kind": "constant",
+        "file_id": "my-service:src/auth/config.py", "line": 12, "detail_level": "signature",
         "graph_distance": 2, "score": 6.10,  "tokens": 31,  "content": "SESSION_TTL: int" }
     ],
-    "used_tokens": 2913, "budget": 4000, "included": 8, "skipped": 0
+    "used_tokens": 1388, "budget": 1500, "included": 20, "skipped": 0
   },
   "coverage": {
     "anchor_source_count": 3, "connected_component_ratio": 0.875,
@@ -192,7 +216,8 @@ gereken an. `commit_mismatch` ise indeksin çalışma ağacınızın gerisinde k
 
 **`detail_level`** graf mesafesiyle azalır: değiştirdiğiniz sembol tam gövdesiyle,
 komşuları imza olarak, dış halka `name @ dosya:satır` biçiminde gelir. Gerçekten ilgili
-sekiz sembolün 4000 token'a sığması bu sayede olur.
+yirmi sembolün 1500 token'a sığması bu sayede olur — bir ajanın her turda taşıyabileceği
+kadar kısa. Her öge `file_id` ve `line` da taşır; ajan sembolü aramak yerine dosyayı açar.
 
 ## Nasıl çalışır
 

{bgts_context_engine-0.2.3 → bgts_context_engine-0.2.5}/pyproject.toml

@@ -106,6 +106,7 @@ include = ["bce*"]
 bce = [
     "core/i18n/catalogs/*.json",
     "storage/relational/migrations/*.sql",
+    "integrations/templates/*",
     # Compiled frontend served at /ui; vendored by scripts/build_ui.py before a release build.
     "api/rest/static/**/*",
 ]

{bgts_context_engine-0.2.3 → bgts_context_engine-0.2.5}/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.3"
+__version__ = "0.2.5"

{bgts_context_engine-0.2.3 → bgts_context_engine-0.2.5}/src/bce/api/mcp/server.py

@@ -44,8 +44,9 @@ def build_server(name: str = "bgts-context-engine") -> Any:
     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)
+    settings = get_settings()
+    allow_write = settings.mcp_allow_write
+    specs = available_tool_specs(allow_write=allow_write, allowlist=settings.mcp_tool_allowlist)
     server = Server(name)
 
     @server.list_tools()
@@ -56,6 +57,8 @@ def build_server(name: str = "bgts-context-engine") -> Any:
         ]
 
     def _dispatch_blocking(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+        if name not in specs:
+            raise KeyError(f"tool '{name}' is not advertised by this server (BCE_MCP_TOOLS)")
         with connection() as conn:
             try:
                 result = dispatch_tool(conn, name, arguments, allow_write=allow_write)

{bgts_context_engine-0.2.3 → bgts_context_engine-0.2.5}/src/bce/api/mcp/tools.py

@@ -26,6 +26,7 @@ from typing import Any
 import psycopg
 
 from bce.core.auth.scope import Principal, ScopeFilter
+from bce.core.defaults import DEFAULT_MAX_CANDIDATES, DEFAULT_MAX_TOKENS
 from bce.core.i18n import get_translator
 from bce.jobs.store import enqueue_job, get_job, list_jobs
 from bce.storage.graph.client import GraphClient
@@ -57,10 +58,21 @@ TOOL_SPECS: dict[str, dict[str, Any]] = {
         ),
         "schema": _schema(
             {
-                "task_text": _STR,
+                "task_text": {
+                    **_STR,
+                    "description": "The task in prose; pass the full request text, once.",
+                },
                 "task_id": _STR,
-                "max_tokens": _INT,
-                "max_candidates": _INT,
+                "max_tokens": {
+                    **_INT,
+                    "default": DEFAULT_MAX_TOKENS,
+                    "description": "Token budget of the assembled context.",
+                },
+                "max_candidates": {
+                    **_INT,
+                    "default": DEFAULT_MAX_CANDIDATES,
+                    "description": "How many symbols to return (K).",
+                },
                 "commit": _STR,
                 "repo_ids": _STR_LIST,
                 "explicit_symbols": _STR_LIST,
@@ -137,11 +149,24 @@ TOOL_SPECS: dict[str, dict[str, Any]] = {
 }
 
 
-def available_tool_specs(*, allow_write: bool) -> dict[str, dict[str, Any]]:
-    """The catalog to advertise: write tools are hidden unless ``allow_write`` is set."""
-    if allow_write:
-        return dict(TOOL_SPECS)
-    return {name: spec for name, spec in TOOL_SPECS.items() if name not in WRITE_TOOLS}
+def available_tool_specs(
+    *, allow_write: bool, allowlist: frozenset[str] | None = None
+) -> dict[str, dict[str, Any]]:
+    """The catalog to advertise: write tools are hidden unless ``allow_write`` is set, and an
+    ``allowlist`` (``BCE_MCP_TOOLS``) narrows it further. Unknown names in the allowlist raise, so a
+    typo does not silently publish nothing."""
+    if allowlist is not None:
+        unknown = sorted(allowlist - set(TOOL_SPECS))
+        if unknown:
+            raise ValueError(
+                f"BCE_MCP_TOOLS names unknown tools {unknown}; known: {sorted(TOOL_SPECS)}"
+            )
+    specs = {
+        name: spec
+        for name, spec in TOOL_SPECS.items()
+        if (allow_write or name not in WRITE_TOOLS) and (allowlist is None or name in allowlist)
+    }
+    return specs
 
 
 def dispatch_tool(

{bgts_context_engine-0.2.3 → bgts_context_engine-0.2.5}/src/bce/api/rest/schemas.py

@@ -11,6 +11,8 @@ from typing import Any
 
 from pydantic import BaseModel, Field
 
+from bce.core.defaults import DEFAULT_MAX_CANDIDATES, DEFAULT_MAX_TOKENS
+
 
 class IndexRequest(BaseModel):
     repo_path: str = Field(..., description="Path to a local repository to index.")
@@ -64,9 +66,11 @@ class ContextForTaskRequest(BaseModel):
     task_id: str | None = Field(
         default=None, description="Optional Jira task id (audit + history)."
     )
-    max_tokens: int = Field(default=4000, ge=1, le=200000, description="Token budget for assembly.")
+    max_tokens: int = Field(
+        default=DEFAULT_MAX_TOKENS, ge=1, le=200000, description="Token budget for assembly."
+    )
     max_candidates: int = Field(
-        default=8, ge=1, le=100, description="Narrow to at most N candidates."
+        default=DEFAULT_MAX_CANDIDATES, ge=1, le=100, description="Narrow to at most N candidates."
     )
     commit: str | None = Field(default=None, description="Pinned commit sha (stage 0).")
     repo_ids: list[str] | None = Field(
@@ -108,7 +112,7 @@ class AssembleContextRequest(BaseModel):
     symbol_ids: list[str] = Field(
         ..., description="Symbols to deduplicate and fit into the budget."
     )
-    max_tokens: int = Field(default=4000, ge=1, le=200000)
+    max_tokens: int = Field(default=DEFAULT_MAX_TOKENS, ge=1, le=200000)
 
 
 class ToolResponse(BaseModel):

{bgts_context_engine-0.2.3 → bgts_context_engine-0.2.5}/src/bce/cli.py

@@ -9,10 +9,16 @@ Commands:
 - ``bench-prs``        PR replay ablation: Voyage alone vs Voyage + BCE (``prepare`` / ``run``)
 - ``resolve-symbol``   Layer-1: resolve a symbol by name
 - ``find-references``  Layer-1: find references to a symbol_id
+- ``context``          Layer-3: assemble the context package for a task
+- ``precontext``       the compact context block an agent prompt carries (also a Claude Code hook)
+- ``cursor-init``      write .cursor/mcp.json + the agent rule into a project
+- ``claude-init``      write .mcp.json, a CLAUDE.md section and the pre-context hook into a project
 - ``languages``        list supported languages/extensions (no database needed)
 - ``serve``            run the REST API (FastAPI/uvicorn)
+- ``serve-mcp``        run the MCP server over stdio
 
-Read/write commands need a running PostgreSQL (Apache AGE + pgvector); ``languages`` does not.
+Read/write commands need a running PostgreSQL (Apache AGE + pgvector); ``languages``,
+``cursor-init`` and ``claude-init`` do not.
 """
 
 from __future__ import annotations
@@ -23,6 +29,8 @@ from pathlib import Path
 
 import typer
 
+from bce.core.defaults import DEFAULT_MAX_CANDIDATES, DEFAULT_MAX_TOKENS
+
 app = typer.Typer(add_completion=False, help="BGTS Context Engine CLI")
 
 
@@ -382,9 +390,11 @@ def find_references_cmd(
 @app.command()
 def context(
     task: str = typer.Option(..., "--task", help="Task title + description text"),
-    max_tokens: int = typer.Option(4000, "--max-tokens", help="Token budget for assembly"),
+    max_tokens: int = typer.Option(
+        DEFAULT_MAX_TOKENS, "--max-tokens", help="Token budget for assembly"
+    ),
     max_candidates: int = typer.Option(
-        8, "--max-candidates", help="Narrow to at most N candidates"
+        DEFAULT_MAX_CANDIDATES, "--max-candidates", help="Narrow to at most N candidates (K)"
     ),
     commit: str | None = typer.Option(None, "--commit", help="Pinned commit sha (stage 0)"),
     locale: str | None = typer.Option(None, "--locale", help="Message locale (en/tr)"),
@@ -412,6 +422,123 @@ def context(
     _echo_json(result["payload"])
 
 
+@app.command()
+def precontext(
+    task: str | None = typer.Option(
+        None,
+        "--task",
+        help="Task text. Omit it to read a Claude Code UserPromptSubmit hook payload from stdin.",
+    ),
+    repo_id: list[str] = typer.Option(
+        [], "--repo-id", help="Restrict to these repository ids (repeatable)"
+    ),
+    max_candidates: int = typer.Option(DEFAULT_MAX_CANDIDATES, "--max-candidates", help="K"),
+    max_tokens: int = typer.Option(DEFAULT_MAX_TOKENS, "--max-tokens", help="Token budget"),
+) -> None:
+    """The compact "Code context for this task" block an agent starts with (markdown).
+
+    With ``--task`` it prints the block. Without it, it acts as a Claude Code ``UserPromptSubmit``
+    hook: reads the hook JSON on stdin and prints the ``additionalContext`` response, or nothing
+    when the prompt is not a task. It never fails the prompt: errors go to stderr, exit code 0.
+    """
+    from bce.integrations.precontext import claude_hook_response, precontext_for_task
+
+    if task is not None:
+        pre = precontext_for_task(
+            task, repo_ids=repo_id or None, max_candidates=max_candidates, max_tokens=max_tokens
+        )
+        typer.echo(pre["text"], nl=False)
+        return
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+    except json.JSONDecodeError as exc:
+        typer.echo(f"bce precontext: stdin is not JSON ({exc})", err=True)
+        return
+    response = claude_hook_response(payload, repo_ids=repo_id or None)
+    if response is not None:
+        typer.echo(json.dumps(response, ensure_ascii=False))
+
+
+def _agent_init_common(
+    project: Path, repo_id: list[str], env_file: Path | None, bce_command: str | None
+) -> tuple[Path, list[str], str, Path | None]:
+    from bce.integrations.agents import resolve_bce_command, resolve_env_file
+
+    project = project.resolve()
+    if not project.is_dir():
+        raise typer.BadParameter(f"not a directory: {project}", param_hint="--project")
+    repo_ids = [r.strip() for r in repo_id if r.strip()] or [project.name]
+    try:
+        resolved_env = resolve_env_file(env_file, project)
+    except FileNotFoundError as exc:
+        raise typer.BadParameter(str(exc), param_hint="--env-file") from None
+    return project, repo_ids, resolve_bce_command(bce_command), resolved_env
+
+
+def _report_setup(result, env_file: Path | None) -> None:
+    for p in result.written:
+        typer.echo(f"wrote {p}")
+    if env_file is None:
+        typer.secho(
+            "No .env found: the MCP server will read BCE_* from the editor's environment. Pass "
+            "--env-file PATH (or run `bce --env-file PATH ...`) to point it at your engine "
+            "configuration.",
+            err=True,
+            fg=typer.colors.YELLOW,
+        )
+    for n in result.notes:
+        typer.echo(f"- {n}")
+
+
+_INIT_PROJECT_HELP = "Project directory to configure (default: current directory)"
+_INIT_REPO_HELP = "Repository id as indexed in the engine (repeatable; default: the directory name)"
+_INIT_ENV_HELP = "The engine .env the MCP server loads (default: --env-file/BCE_ENV_FILE, then <project>/.env, then ./.env)"
+_INIT_CMD_HELP = "Executable the editor spawns (default: this bce)"
+
+
+@app.command(name="cursor-init")
+def cursor_init(
+    project: Path = typer.Option(Path("."), "--project", help=_INIT_PROJECT_HELP),
+    repo_id: list[str] = typer.Option([], "--repo-id", help=_INIT_REPO_HELP),
+    env_file: Path | None = typer.Option(None, "--env-file", help=_INIT_ENV_HELP),
+    bce_command: str | None = typer.Option(None, "--bce-command", help=_INIT_CMD_HELP),
+) -> None:
+    """Connect a project to the engine for Cursor: .cursor/mcp.json + the agent rule.
+
+    Merges into an existing mcp.json (other servers are kept) and is safe to rerun.
+    """
+    from bce.integrations.agents import setup_cursor
+
+    project, repo_ids, cmd, env = _agent_init_common(project, repo_id, env_file, bce_command)
+    _report_setup(setup_cursor(project, repo_ids=repo_ids, bce_cmd=cmd, env_file=env), env)
+
+
+@app.command(name="claude-init")
+def claude_init(
+    project: Path = typer.Option(Path("."), "--project", help=_INIT_PROJECT_HELP),
+    repo_id: list[str] = typer.Option([], "--repo-id", help=_INIT_REPO_HELP),
+    env_file: Path | None = typer.Option(None, "--env-file", help=_INIT_ENV_HELP),
+    bce_command: str | None = typer.Option(None, "--bce-command", help=_INIT_CMD_HELP),
+    hook: bool = typer.Option(
+        True,
+        "--hook/--no-hook",
+        help="Install the UserPromptSubmit hook that adds the graph's answer to every prompt",
+    ),
+) -> None:
+    """Connect a project to the engine for Claude Code: .mcp.json, a CLAUDE.md section and, by
+    default, the pre-computed context hook in .claude/settings.json.
+
+    Merges into existing files (other servers, hooks and CLAUDE.md content are kept) and is safe
+    to rerun.
+    """
+    from bce.integrations.agents import setup_claude
+
+    project, repo_ids, cmd, env = _agent_init_common(project, repo_id, env_file, bce_command)
+    _report_setup(
+        setup_claude(project, repo_ids=repo_ids, bce_cmd=cmd, env_file=env, hook=hook), env
+    )
+
+
 @app.command()
 def bench(
     cases: Path = typer.Option(..., "--cases", help="Path to a JSON file of benchmark cases"),

{bgts_context_engine-0.2.3 → bgts_context_engine-0.2.5}/src/bce/config.py

@@ -100,6 +100,11 @@ class Settings(BaseSettings):
     )
     # Seconds to wait for one embedding request (a local model on a laptop can need minutes).
     embedding_timeout: float = 600.0
+    # Seconds to wait when embedding a single *query* at search time (openai provider). Queries are
+    # one short text, so a healthy server answers in well under a second; a longer wait only means
+    # the network stalled. Kept short so a tool call returns (possibly without its semantic anchor)
+    # before an agent's own MCP timeout (Cursor: 60 s) kills it. Each query gets two attempts.
+    embedding_query_timeout: float = 10.0
 
     # --- Retrieval profile (engine constants that depend on the embedding model) ---
     # "auto" (default) picks the profile fitted for ``embedding_model`` - "voyage" for voyage-*,
@@ -128,6 +133,15 @@ class Settings(BaseSettings):
     # only read-only tools and runs no job workers. Turning it on also starts a worker pool inside
     # the MCP process, so queued indexing runs without a separate ``bce serve``.
     mcp_allow_write: bool = False
+    # Which tools the MCP server advertises (comma-separated names; empty = all). Agents fetch a
+    # tool's schema before using it and tend to chain small calls when many tools are on offer, so a
+    # narrow catalog (e.g. "get_context_for_task,find_references") costs fewer model turns.
+    mcp_tools: str = ""
+
+    @property
+    def mcp_tool_allowlist(self) -> frozenset[str] | None:
+        names = frozenset(n.strip() for n in self.mcp_tools.split(",") if n.strip())
+        return names or None
 
     @property
     def dsn(self) -> str: