blq-cli 1.1.0__tar.gz → 1.2.0__tar.gz

{blq_cli-1.1.0 → blq_cli-1.2.0}/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## v1.2.0
+
+### Added — MCP tools publish the names of the keys they return (#47)
+
+fastmcp derives `outputSchema` from a tool's return annotation, so
+`dict[str, Any]` published `{"type": "object", "additionalProperties": true}`
+— an object with no key names. A programmatic caller had to guess them, and a
+wrong guess produces a program that validates, runs, and answers incorrectly.
+Measured across four local models driven through lackpy: **0/24 correct while
+17/24 called the right tool**, with `len()` on `events`' dict returning its key
+count rather than its event count.
+
+14 tools now return TypedDicts whose keys come from the implementations' own
+return statements. Declaring the shapes immediately caught three places where
+the code did not match a reasonable reading of it:
+
+- `output.streams` is a list of stream names, not a mapping
+- `query.rows` is positional value lists paired with `columns`, not per-row objects
+- `ci_generate.available` is the registered command names, not a boolean
+
+No data is dropped — keys a TypedDict does not declare still reach the client
+in `structuredContent`.
+
+**One behavioural note for Python callers:** with an `outputSchema` present,
+fastmcp's own client deserializes `.data` into a generated model rather than a
+dict, so `result.data["key"]` no longer works. Read `structured_content`, which
+is the JSON a real MCP client receives over the wire. Consumers speaking
+JSON-RPC (Claude Code, lackpy, any stdio client) are unaffected and strictly
+better off.
+
+
 ## v1.1.0
 
 Three fixes with one theme: blq reported success while losing the thing it was

{blq_cli-1.1.0 → blq_cli-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: blq-cli
-Version: 1.1.0
+Version: 1.2.0
 Summary: Build Log Query - capture and query build/test logs with DuckDB
 Project-URL: Homepage, https://blq-cli.readthedocs.io/
 Project-URL: Repository, https://github.com/teaguesterling/blq-cli

{blq_cli-1.1.0 → blq_cli-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "blq-cli"
-version = "1.1.0"
+version = "1.2.0"
 description = "Build Log Query - capture and query build/test logs with DuckDB"
 readme = "README.md"
 license = "MIT"

{blq_cli-1.1.0 → blq_cli-1.2.0}/src/blq/serve.py

@@ -34,7 +34,7 @@ import re as _re
 import shlex
 import subprocess
 import sys
-from typing import Any
+from typing import Any, TypedDict
 
 import pandas as pd  # type: ignore[import-untyped]
 from fastmcp import FastMCP
@@ -214,6 +214,129 @@ def _get_storage() -> BlqStorage:
     return BlqStorage.open()
 
 
+# ── Published result shapes ──────────────────────────────────────────
+#
+# fastmcp derives each tool's `outputSchema` from its return annotation. A bare
+# `dict[str, Any]` becomes {"type": "object", "additionalProperties": true} —
+# an object with no key names, which tells a programmatic caller nothing it can
+# write code against. Measured cost, from four local models driven against this
+# suite: 0/24 correct while 17/24 called the correct tool, because the models
+# picked the right tool and guessed the return shape wrong. `len()` on `events`'
+# dict returns its key count, not its event count.
+#
+# These TypedDicts exist to put the key names on the wire. Keys are taken from
+# the implementations' own `return {...}` statements. `total=False` throughout:
+# most of these tools return an `error` key on failure paths and omit it
+# otherwise, and several have distinct success shapes (`events` returns batch
+# keys under `run_ids`), so declaring everything required would publish a
+# contract the code does not keep.
+
+class EventsResult(TypedDict, total=False):
+    """`events` — single-run keys, plus the batch keys used with `run_ids`."""
+    events: list[dict[str, Any]]
+    total_count: int
+    runs: list[dict[str, Any]]
+    run_count: int
+    total_events: int
+
+
+class StatusResult(TypedDict, total=False):
+    sources: list[dict[str, Any]]
+
+
+class HistoryResult(TypedDict, total=False):
+    runs: list[dict[str, Any]]
+
+
+class QueryResult(TypedDict, total=False):
+    # Positional value lists paired with `columns`, not per-row objects.
+    rows: list[list[Any]]
+    columns: list[str]
+    row_count: int
+    error: str
+
+
+class InspectResult(TypedDict, total=False):
+    events: list[dict[str, Any]]
+    found: int
+    total: int
+    error: str
+
+
+class OutputResult(TypedDict, total=False):
+    # A LIST of stream names, not a mapping — declaring it as an object made
+    # fastmcp reject every call with "[] is not of type 'object'". Worth noting
+    # that the schema caught the wrong assumption immediately, which is most of
+    # the argument for declaring these at all.
+    streams: list[str]
+    ref: str
+    run_id: int
+    error: str
+
+
+class DiffResult(TypedDict, total=False):
+    new: list[dict[str, Any]]
+    fixed: list[dict[str, Any]]
+    summary: dict[str, Any]
+    error: str
+
+
+class CommandsResult(TypedDict, total=False):
+    commands: list[dict[str, Any]]
+    error: str
+
+
+class RunResult(TypedDict, total=False):
+    # Nullable, not merely optional: the failure paths return these keys set to
+    # None rather than omitting them, and `total=False` only makes a key
+    # absent-able.
+    run_ref: str | None
+    status: str | None
+    exit_code: int | None
+    summary: dict[str, Any]
+    results: list[dict[str, Any]]
+    commands_requested: int
+    commands_run: int
+    error: str
+
+
+class ExecResult(TypedDict, total=False):
+    run_ref: str | None
+    status: str | None
+    exit_code: int | None
+    summary: dict[str, Any]
+    errors: list[dict[str, Any]]
+    error: str
+
+
+class CiCheckResult(TypedDict, total=False):
+    status: str | None
+    mode: str | None
+    has_errors: bool
+    current_errors: int
+    current_run_id: int
+    error: str
+
+
+class CiGenerateResult(TypedDict, total=False):
+    # The names of the registered commands, not a yes/no — read from the
+    # implementation rather than inferred from the key name, which is how the
+    # first three drafts of these annotations got it wrong.
+    available: list[str]
+    count: int
+    scripts: list[dict[str, Any]]
+    shell: str | None
+    error: str
+
+
+class CommandMutationResult(TypedDict, total=False):
+    """Shared by `register_command` / `unregister_command`."""
+    success: bool
+    message: str
+    existing_name: str
+    error: str
+
+
 def _get_suppressed_list(include_suppressed: bool = False) -> list[str] | None:
     """Get list of suppressed fingerprints, or None if no filtering."""
     if include_suppressed:
@@ -2282,7 +2405,7 @@ def run(
     # Batch mode parameters
     commands: list[str] | None = None,
     stop_on_failure: bool = True,
-) -> dict[str, Any]:
+) -> RunResult:
     """Run a registered command and capture its output.
 
     Can run a single command or multiple commands in sequence (batch mode).
@@ -2340,7 +2463,7 @@ def exec(
     timeout: int | None = None,
     shell: bool = False,
     lines: str | None = None,
-) -> dict[str, Any]:
+) -> ExecResult:
     """Execute an ad-hoc shell command and capture its output.
 
     IMPORTANT: Do NOT use shell pipes, redirects, or command chains
@@ -2379,7 +2502,7 @@ def query(
     sql: str | None = None,
     filter: str | None = None,
     limit: int = 100,
-) -> dict[str, Any]:
+) -> QueryResult:
     """Query stored log events with SQL or simple filter expressions.
 
     Use either `sql` for raw SQL queries or `filter` for simple expressions.
@@ -2421,7 +2544,7 @@ def events(
     # Batch mode
     run_ids: list[int] | None = None,
     limit_per_run: int = 10,
-) -> dict[str, Any]:
+) -> EventsResult:
     """Get events with optional severity filter.
 
     For errors only: use severity="error"
@@ -2493,7 +2616,7 @@ def inspect(
     include_fingerprint_history: bool = False,
     # Batch mode
     refs: list[str] | None = None,
-) -> dict[str, Any]:
+) -> InspectResult:
     """Get comprehensive event details with context and enrichment.
 
     Returns event details with optional context and enrichment:
@@ -2572,7 +2695,7 @@ def output(
     context: int = 0,
     lines: str | None = None,
     debug_formats: bool = False,
-) -> dict[str, Any]:
+) -> OutputResult:
     """Get raw output for a run with optional search and filtering.
 
     Retrieves the captured stdout/stderr from a command execution.
@@ -2606,7 +2729,7 @@ def output(
 
 
 @mcp.tool()
-def status() -> dict[str, Any]:
+def status() -> StatusResult:
     """Get current status summary of all sources.
 
     Returns:
@@ -2975,7 +3098,7 @@ def _last_impl(
 @mcp.tool()
 def history(
     limit: int | None = None, source: str | None = None, status: str | None = None
-) -> dict[str, Any]:
+) -> HistoryResult:
     """Get run history.
 
     Args:
@@ -2995,7 +3118,7 @@ def history(
 
 
 @mcp.tool()
-def diff(run1: int, run2: int) -> dict[str, Any]:
+def diff(run1: int, run2: int) -> DiffResult:
     """Compare errors between two runs.
 
     Args:
@@ -3023,7 +3146,7 @@ def register_command(
     lines: str | None = None,
     sandbox: str | dict[str, Any] | None = None,
     lock: str | None = None,
-) -> dict[str, Any]:
+) -> CommandMutationResult:
     """Register a new command.
 
     If a command with the same name or same command string already exists,
@@ -3075,7 +3198,7 @@ def register_command(
 
 
 @mcp.tool()
-def unregister_command(name: str) -> dict[str, Any]:
+def unregister_command(name: str) -> CommandMutationResult:
     """Remove a registered command.
 
     Note: This tool can be disabled via mcp.disabled_tools config.
@@ -3091,7 +3214,7 @@ def unregister_command(name: str) -> dict[str, Any]:
 
 
 @mcp.tool()
-def commands() -> dict[str, Any]:
+def commands() -> CommandsResult:
     """List all registered commands.
 
     Returns:
@@ -3592,7 +3715,7 @@ def ci_check(
     baseline: str | None = None,
     fail_on_any: bool = False,
     run_id: int | None = None,
-) -> dict[str, Any]:
+) -> CiCheckResult:
     """Check for regressions compared to a baseline run.
 
     Compares error fingerprints between the current run and a baseline to
@@ -3619,7 +3742,7 @@ def ci_check(
 def ci_generate(
     commands: list[str] | None = None,
     shell: str = "bash",
-) -> dict[str, Any]:
+) -> CiGenerateResult:
     """Generate standalone shell scripts from registered commands.
 
     Creates shell script content for CI environments where blq may not be

{blq_cli-1.1.0 → blq_cli-1.2.0}/tests/test_mcp_ci_tools.py

@@ -16,7 +16,18 @@ if fastmcp:
 
 
 def get_data(result):
-    """Extract data from CallToolResult."""
+    """Extract data from CallToolResult as a plain dict.
+
+    Prefer `structured_content`: once a tool declares an outputSchema (which
+    they now do, so callers can see the key names — see #47), fastmcp
+    deserializes `.data` into a generated model rather than a dict, and a model
+    is not subscriptable. `structured_content` is the JSON payload a real MCP
+    client receives over the wire, including any keys the schema does not
+    declare, so asserting against it tests what a consumer actually gets.
+    """
+    sc = getattr(result, "structured_content", None)
+    if sc is not None:
+        return sc
     if hasattr(result, "data"):
         return result.data
     return result

{blq_cli-1.1.0 → blq_cli-1.2.0}/tests/test_mcp_server.py

@@ -16,7 +16,18 @@ if fastmcp:
 
 
 def get_data(result):
-    """Extract data from CallToolResult."""
+    """Extract data from CallToolResult as a plain dict.
+
+    Prefer `structured_content`: once a tool declares an outputSchema (which
+    they now do, so callers can see the key names — see #47), fastmcp
+    deserializes `.data` into a generated model rather than a dict, and a model
+    is not subscriptable. `structured_content` is the JSON payload a real MCP
+    client receives over the wire, including any keys the schema does not
+    declare, so asserting against it tests what a consumer actually gets.
+    """
+    sc = getattr(result, "structured_content", None)
+    if sc is not None:
+        return sc
     if hasattr(result, "data"):
         return result.data
     return result

blq_cli-1.2.0/tests/test_output_schemas.py

@@ -0,0 +1,90 @@
+"""MCP tools must publish the NAMES of the keys they return.
+
+fastmcp derives `outputSchema` from a tool's return annotation. A bare
+`dict[str, Any]` becomes:
+
+    {"type": "object", "additionalProperties": true}
+
+which tells a caller it will receive *an object* and nothing more. A
+programmatic consumer then has to guess the keys, and a wrong guess produces
+a program that validates, runs, and answers incorrectly.
+
+Measured by a session driving four local models against this suite through
+lackpy, which generates one restricted-Python program per intent:
+
+    0/24 correct while 17/24 called the correct tool
+
+`len()` on `events`' returned dict gives 2 — its key count — where the answer
+was 1. Annotating the return types is the whole fix: the wire format already
+carries the property names, nothing else changes, and it helps every
+programmatic caller rather than one harness.
+
+See #47.
+"""
+
+import pytest
+
+fastmcp = pytest.importorskip("fastmcp")
+
+
+async def _schema_for(tool_name):
+    from fastmcp import Client
+    from blq.serve import mcp
+
+    async with Client(mcp) as client:
+        for tool in await client.list_tools():
+            if tool.name == tool_name:
+                return tool.outputSchema
+    raise AssertionError(f"tool {tool_name!r} not published")
+
+
+def _properties(schema):
+    """The named properties a caller can rely on.
+
+    fastmcp wraps a non-object return in {"result": ...}; for a TypedDict it
+    emits the properties directly. Accept either, and look through the wrapper
+    so the assertion is about the tool's shape, not fastmcp's packaging.
+    """
+    assert schema is not None, "tool publishes no outputSchema at all"
+    props = schema.get("properties") or {}
+    if set(props) == {"result"}:
+        inner = props["result"]
+        props = inner.get("properties") or {}
+    return props
+
+
+# Keys taken from the impl's own `return {...}` statements, not from docs.
+EXPECTED = {
+    "events":  {"events", "total_count"},
+    "status":  {"sources"},
+    "history": {"runs"},
+    "query":   {"rows", "columns", "row_count"},
+    "inspect": {"events", "found", "total"},
+    "output":  {"streams", "ref"},
+    "diff":    {"new", "fixed", "summary"},
+    "commands": {"commands"},
+}
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("tool_name,expected", sorted(EXPECTED.items()))
+async def test_tool_publishes_named_properties(tool_name, expected):
+    schema = await _schema_for(tool_name)
+    props = _properties(schema)
+    missing = expected - set(props)
+    assert not missing, (
+        f"{tool_name} publishes no property names for {sorted(missing)} — "
+        f"got {sorted(props) or 'nothing'}. A caller cannot write code "
+        f"against this."
+    )
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("tool_name", sorted(EXPECTED))
+async def test_schema_is_not_an_open_object(tool_name):
+    """`additionalProperties: true` with no properties is the defect."""
+    schema = await _schema_for(tool_name)
+    props = _properties(schema)
+    assert props, (
+        f"{tool_name}'s outputSchema names no properties at all"
+    )