feat: basectl mcp serve (stdio) with deterministic lookup tools #2587

Goal

Expose Base's exact-lookup knowledge to agents over MCP without prose search.

Background

Much of 'query the docs' is exact lookup: a command and its flags, a finding ID such as BASE-D016, a schema, a stability tier. These can be served deterministically from canonical sources, which are cheaper and more accurate than retrieval. Decision recorded 2026-10-15: use the official mcp Python package as an optional extra, imported only when the server runs. Prerequisites: canonical command metadata (#1606) and the manifest JSON Schema (#1613).

Next-release planning review of 2026-10-14/15 against main at 7faf6dfb. Tracking: #2555.

Prerequisites: #2586, #1606, #1613.

Scope

• basectl mcp serve over stdio; tools for command and flag lookup, finding-ID explanation, schema retrieval, manifest field lookup, stability tier.
• Every tool returns structured JSON with source path and anchor and the index/commit SHA.
• Optional dependency handling with a clear install hint; pin and hash per docs/ci-supply-chain-policy.md.
• Experimental stability tier documented.

Acceptance Criteria

• MCP initialize, tools/list, and tools/call pass a protocol smoke test in CI using the SDK client.
• No tool executes commands or writes files.
• Responses are deterministic for a given commit.
• Missing optional dependency yields an actionable message, not a traceback.

Validation

BASE_CLI_SOURCE_DIR=../base-cli/lib/python \
PYTHONPATH=../base-cli/lib/python:lib/python:cli/python \
python -m pytest <new mcp tests>
git diff --check

Non-Goals

• No network listener.
• No embeddings or prose search in this issue.

Project Fields

• Status: Backlog
• Priority: P1
• Area: CLI
• Initiative: Agentic Coding Platform
• Size: M
• Milestone: v1.12.0
• Category: enhancement

Agent Assignment

Assignee: codeforester. Blocked on #2586, #1606, and #1613.

Plan revision (2026-10-16)

Keep this in v1.12.0, but revise the dependency order: prerequisites are #2586, #2589, #1606, #1613, and #2600. The security design and failing-before tests in #2589 must exist before the server is exposed, and #2600 must define the supported optional-SDK installation path. The server remains stdio-only, read-only, deterministic, and experimental; missing or unsupported dependencies must produce the documented diagnostic rather than an import traceback.