Skip to content

Serve the pinned Foundations as read-only MCP tools for one bot - #84

Merged
Akilleez-QA merged 1 commit into
mainfrom
feat/foundations-mcp
Nov 17, 2026
Merged

Akilleez-QA merged 1 commit into
mainfrom
feat/foundations-mcp

Conversation

@Akilleez-QA

Copy link
Copy Markdown
Owner

Change

Wave 1C: serve the pinned Foundations as read-only MCP tools for an agent ("Sage" or any other) in one bot's AOR, so domain answers come with their receipts and every call is a witnessed POODO decision.

tools/foundations_mcp.py --aor <slug> --foundation <name> ... launches adapters/foundations_mcp.py, an MCP stdio server that:

  • lists <foundation>.<tool> (for example refrigeration.saturation_pressure) for each Foundation the host named at launch that the bot's AOR does not deny, with input schemas from the pinned tool inventories. A request cannot add a Foundation; an unregistered name, a runtime such as cstack_forge, a repeat or an empty choice stops the launch;
  • checks arguments against the exact pinned input schema before any decision, so malformed input never spends budget or writes the ledger;
  • runs every other call through the bot's AorSession: a standing POODO goal per Foundation, host-authored checkpoints, a precommitted decision on the read-only ToolFace grant, then execution through the existing pinned adapter (manifest verified, live inventory pinned and, for the shared adapter, receipt input digest recomputed);
  • returns the Foundation's isError and structuredContent (receipt, evidence, boundary flags) unchanged, with the POODO record in _meta["cstack/poodo"]. CHECK values and the evidence ceiling are never rewritten. A refused, tampered, unadmitted, pending or over-budget call is a tool error; nothing is retried.

Rationale.

  • Reuse, not a second setup: build_aor_session gains an optional foundations subset, so cores, grants, witnessed ledgers, approvals and shields are the ones tools/cstack_mcp.py already uses. The server subclasses McpServer for framing and strict parsing; the only change there is that McpServer.INSTRUCTIONS became a class attribute (same text).
  • A top-level allOf/oneOf/anyOf (math.exact_scalar, robotics.mechanism_check) is merged into one object schema in tools/list, because some clients reject top-level combinators; the server still validates against the exact schema.
  • An Engine result that is not an object is returned as text only, because MCP structuredContent must be an object.
  • No core change.

Requirements, design and interface impact

  • Requirements added: CS-REQ-091 (Foundations MCP server), Baselined. The id sits deliberately above the ids other in-flight branches use (078, 080 to 082, 084 to 086), so the branches don't collide on merge.
  • SDD: new component SDD-C31 (chosen above the in-flight C25, C26, C28) and a flowchart edge. ICD: new "Foundations MCP interface" section in docs/icd/icd-foundations.md; pointer in contracts/INTERFACES.md. contracts/ADAPTERS.json: two rows (foundations-mcp-server, foundations-mcp-launcher), checked by tests/test_adapter_inventory.py.
  • Verification matrix updated: yes, one row against tests/test_foundations_mcp.py.
  • Small edits to shared files (bootstrap.py, adapters/mcp_stdio_server.py, ADAPTERS.json, requirements/verification docs), because feat/handoff-channel and feat/cstack-init edit the same files.

Verification

These ran on the head commit 54e2a9d on macOS with Python 3.15 in a throwaway venv (ci/requirements.txt installed). No model calls were made and no credentials were set.

  • python -B -m unittest discover -s tests: Ran 746, failures=76, errors=4, skipped=8. main at 0a9703b, same machine: Ran 734, failures=76, errors=4, skipped=8. The failing tests are identical on both (diffed). They are the known macOS workcell/EndoForge failures (workcell_not_executed) plus the tests that need npm ci for the workcell toolchain, which was not run. All 12 new tests pass. Linux CI is the authority.
  • bash ci/run-local.sh python links trace: suite results as above; check_links 1442 paths, 0 broken; check_trace 78 requirements, 77/77 test files traced, 0 failures.
  • gitleaks / TruffleHog: not run locally (not installed); the CI job runs them. I scanned the diff by hand for personal data, hosts and secrets and found none. All test inputs are synthetic.

New tests (tests/test_foundations_mcp.py): the tool list matches the pinned schemas; each vendored Foundation's representative tool is called over the real pinned bridges and its receipt comes back unchanged; unknown tool returns invalid params; malformed input never reaches the core; an out-of-profile number is refused before dispatch; the host chooses the Foundations; unknown, empty or repeated choices are refused; a denied domain lists nothing; an ask-class call waits for the owner; a tampered manifest is refused; the stdio launcher lists and calls; an unregistered Foundation stops the launch.

Not done

  • No session from a real MCP client or agent host (Claude Code subagent for Sage) is recorded. The tests use the in-process server and a minimal stdio client.
  • One session allows 64 calls per Foundation (the existing read grant budget).
  • With a witnessed ledger, this server and tools/cstack_mcp.py cannot both hold the same bot and domain at once (the existing lifetime store claim).
  • No STR regenerated; the matrix row says "Not yet in a recorded run".

Peer review record

  • Reviewers: none yet. An agent wrote this, so a review by another agent would not be independent.
  • Review type: code / docs / requirements / design
  • Findings: none recorded
  • Outcome: awaiting review. Draft: do not merge without the owner.

Checklist

  • One concern; about 400 changed lines maximum. (491 added, 5 removed. About 215 of the added lines are tests.)
  • No code comments added. The only # noqa: E402 markers follow the existing launcher pattern in tools/cstack_mcp.py.
  • Expected test results unchanged.
  • AI assistance disclosed: written by Claude Code.
  • Docs whose derivation paths this PR touches are updated.

🤖 Generated with Claude Code

tools/foundations_mcp.py launches an MCP stdio server (adapters/foundations_mcp.py)
for one bot's AOR on this device. It lists <foundation>.<tool> for each
Foundation the host names with --foundation, with input schemas from the pinned
tool inventories, and runs every call through the bot's AOR session: a standing
POODO goal per Foundation, host-authored checkpoints, a precommitted decision on
the read-only ToolFace grant, and execution through the existing pinned adapter
(manifest, live inventory and, for the shared adapter, the receipt input digest).
The Foundation's structuredContent is returned unchanged; the POODO record goes
in _meta["cstack/poodo"].

Why this shape:
- Reuse, not a second composition: build_aor_session gains a foundations
  subset, so cores, grants, witnessed ledgers, approvals and shields are the
  ones the existing MCP server uses. The server subclasses McpServer for
  framing and strict parsing; McpServer.INSTRUCTIONS became a class attribute.
- Arguments are validated against the exact pinned input schema before any
  decision, so malformed input never spends budget or writes the ledger.
- A top-level allOf/oneOf/anyOf (math.exact_scalar, robotics.mechanism_check)
  is projected into one object schema in tools/list, because some clients
  reject top-level combinators; the server still validates the exact schema.
- An Engine result that is not an object is returned as text only, because
  MCP structuredContent must be an object.
- No core change.
- Requirement CS-REQ-091 and design component SDD-C31, chosen above the ids
  other in-flight branches use.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Akilleez-QA
Akilleez-QA marked this pull request as ready for review November 17, 2026 05:18
@Akilleez-QA
Akilleez-QA merged commit a00d838 into main Nov 17, 2026
2 checks passed
Akilleez-QA pushed a commit that referenced this pull request Nov 17, 2026
#84 (now on main) imported tailnet_hostname from tools/cstack_mcp.py, which
this branch replaces with adapters.local_setup.resolve_device and
require_durable. Use the same flow in tools/foundations_mcp.py: refuse to
start without the durable ledger unless --allow-memory-ledger is given, and
take the device from --device, the recorded name, or the tailnet. Its launcher
tests pass --allow-memory-ledger, and a new test checks the refusal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Akilleez-QA added a commit that referenced this pull request Nov 17, 2026
…e; Tailscale optional (#85)

* Add cstack init; refuse the memory ledger in agent mode; make Tailscale optional

One command (python -B tools/cstack_init.py) sets up a private state
folder and a durable, signed witnessed ledger (per-bot signing keys, two
local witness keys, roster, per-bot anchors, ledger.json written last).
It is idempotent, never replaces a mismatched or exposed key, and
--check verifies every ledger file without changing anything.

tools/cstack_mcp.py now exits 2 before creating any state when Cstack is
not set up, naming the init command; --allow-memory-ledger keeps the
memory ledger for tests and throwaway development. A test fails if the
generated bot profiles ever emit that flag.

The device name comes from --device, the name init recorded, or the
tailnet name, so Tailscale is optional. cryptography moves into
requirements.txt because the witnessed ledger is now the default.

Requirements CS-REQ-084, CS-REQ-085, CS-REQ-086; design SDD-C28 (and
SDD-C15 for CS-REQ-085).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Start the Foundations MCP launcher through cstack init's checks

#84 (now on main) imported tailnet_hostname from tools/cstack_mcp.py, which
this branch replaces with adapters.local_setup.resolve_device and
require_durable. Use the same flow in tools/foundations_mcp.py: refuse to
start without the durable ledger unless --allow-memory-ledger is given, and
take the device from --device, the recorded name, or the tailnet. Its launcher
tests pass --allow-memory-ledger, and a new test checks the refusal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Cstack <cstack@Cstacks-Mac-Mini.local>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Akilleez-QA pushed a commit that referenced this pull request Nov 17, 2026
Brings in #84 (Foundations MCP server) and #85 (cstack init, durable
ledger required in agent mode). Conflicts in CHANGELOG.md,
docs/architecture/architecture.md and docs/guides/how-to/define-bots.md
resolved by keeping both sides' entries; EXPORT-MANIFEST.json
regenerated with tools/build_export_manifest.py.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Akilleez-QA pushed a commit that referenced this pull request Nov 17, 2026
Brings in #84 (Foundations MCP server), #85 (cstack init) and #86
(starter agents). Conflicts in docs/architecture/architecture.md and
docs/requirements/requirements.md resolved by keeping both sides:
component rows in SDD order (C26, C28, C29, C31) and requirements
CS-REQ-084 to CS-REQ-086 before CS-REQ-087. EXPORT-MANIFEST.json
regenerated with tools/build_export_manifest.py; data dictionary
--check passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Akilleez-QA pushed a commit that referenced this pull request Nov 17, 2026
Brings in #84 to #87. Conflicts resolved by keeping both sides:
CHANGELOG.md entries; requirements and verification-matrix revision
rows renumbered so main's 2.2 (cstack init) stays and this PR's
CS-REQ-088 row becomes 2.3, with each document's Version set to 2.3.
EXPORT-MANIFEST.json regenerated with tools/build_export_manifest.py;
data dictionary --check passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant