v0.1.4

sciogen v0.1.4

Released 2026-07-08

MCP tools now fail open with actionable results

Agents were quietly abandoning the sciogen MCP tools — falling back to grep/read, or looping endlessly when a symbol wasn't found. The root cause was that the query tools failed closed: an empty index looked identical to a genuine miss, and a miss returned a bare error the agent had no way to act on.

This release makes every query tool fail open — it always returns a structured result that tells the agent what happened and what to do next.

Highlights

• "Not indexed" is now a distinct, recoverable state. A new NotIndexedError is raised when the graph is empty (index_version == 0), so an unindexed project no longer masquerades as a symbol miss. The MCP layer surfaces it with a clear next step: index the codebase first.

• Every miss comes with suggestions. SymbolNotFound now carries a .suggestions list, populated on both symbol and file lookups. Suggestions are computed with a SQL LIKE narrow followed by a difflib similarity rank over the already-indexed symbols/files tables — so a near-miss on a name gets the agent straight to the right symbol instead of a dead end.

• Structured MCP results. A new _safe wrapper on the 7 query tools converts NotIndexedError and SymbolNotFound into structured dicts containing a next step and suggestions, rather than raising raw exceptions across the protocol boundary. index_codebase is intentionally left unwrapped.

Changes

Area	What changed
sciogen/query/engine.py	New NotIndexedError, guarded in _cached. SymbolNotFound gains .suggestions, populated on every miss.
sciogen/stores/meta.py	New suggest_symbol_ids() / suggest_files() — LIKE narrow + difflib rank over indexed tables.
sciogen/mcp/server.py	New _safe wrapper maps errors to structured dicts with next + suggestions across the 7 query tools.
Tests	Suggestions + not-indexed guard coverage in tests/test_pipeline_and_query.py; new tests/test_mcp_server.py for _safe mapping. 57 tests pass.

Known follow-ups

These are tracked but not part of this release:

• index_codebase(path) with a non-empty path builds a second SciogenGraph that can lock-clash with the long-lived server singleton on the same KuzuDB directory. A future change should reuse the singleton when the path resolves to the server root.
• The tools only appear in an agent's tool list if the MCP server is registered — confirm sciogen setup-agent registration per project.

---

No changes to the indexing pipeline, graph schema, or query semantics. This is a reliability and ergonomics release for the MCP interface.