feat(mcp): bridge governed memory tools (memory.*) through squad_state MCP server by tamirdresher · Pull Request #1245 · bradygaster/squad

tamirdresher · 2026-06-09T15:43:12Z

Summary

Adds 6 entries to MCP_TOOL_ALIASES in packages/squad-cli/src/cli/commands/state-mcp.ts so the existing squad_state MCP server advertises the governed memory tools alongside the squad_state_* family. Without this change, the memory.* tools are registered in the SDK ToolRegistry but invisible to agents running in Copilot CLI.

What changes

MCP_TOOL_ALIASES grows from 7 → 13 entries
New aliases: memory_classify, memory_write, memory_search, memory_promote, memory_delete, memory_audit → routed to the existing SDK ToolRegistry tools memory.classify, etc.
Underscore-in-key / dot-in-value follows the existing convention and MCP cross-client safety practice

What does NOT change

No SDK changes (the ToolRegistry already has these tools)
No init/upgrade config changes (the squad_state MCP server registration is unchanged)
No new MCP server
No behavior change to existing squad_state_* or squad_decide flows
Agents with tools: ["*"] automatically pick up the new tools

Why this matters

The governed memory subsystem (classification, audit log, forbidden-scan, loadGuidance) was previously reachable only from the CLI (squad memory ...) and direct SDK consumers. Autonomous agents in Copilot CLI couldn't invoke it, so the safety/governance benefits were dormant for the runtime path that Squad teams actually use. With this change, agents can:

Dry-run a write via memory_classify before committing
Record governed entries with classification + audit via memory_write
Search the governed memory index via memory_search
Promote/delete entries via memory_promote / memory_delete
Read the audit trail via memory_audit

Test plan

npm run build passes
Targeted tests pass: all 4 state-mcp tests pass (2 existing + 2 new)
- lists all 13 tools including the 6 governed memory bridges
- routes memory_classify via MCP to the SDK ToolRegistry memory.classify handler
Changeset added (patch bump for @bradygaster/squad-cli)
CI passes

Out of scope

Updating agent charters to instruct agents WHEN to use the memory tools (separate decision)
Documenting the new tools in user-facing docs (follow-up docs PR)
Adding a separate squad_memory MCP server (this PR uses the existing squad_state server — simpler, no new install)

The governed memory tools (memory.classify, memory.write, memory.search, memory.promote, memory.delete, memory.audit) are registered in the SDK ToolRegistry but were not exposed via the squad_state MCP server. As a result, autonomous agents running in Copilot CLI could not discover or invoke them — the entire classification/audit/search surface was reachable only via the CLI or direct SDK consumers. This change adds 6 entries to MCP_TOOL_ALIASES in state-mcp.ts so the existing MCP server advertises the memory tools alongside the existing squad_state_* family. The alias keys use underscores (memory_classify, etc.) per MCP cross-client safety; the values keep the dotted SDK tool names so the lookup against the ToolRegistry is unchanged. No SDK changes. No init/upgrade config changes. No new MCP server needed. No behavior change to existing squad_state_* or squad_decide flows. Closes #1244 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-06-09T15:43:32Z

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit 08472a7

PR Scope: 📦🔧 Mixed (product + infrastructure)

⚠️ 2 item(s) to address before review

Status	Check	Details
✅	Single commit	1 commit — clean history
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	Changeset file found
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
✅	Copilot threads resolved	No Copilot review threads
❌	CI passing	10 check(s) still running

Files Changed (3 files, +66 −0)

File	+/−
`.changeset/memory-mcp-bridge.md`	+5 −0
`packages/squad-cli/src/cli/commands/state-mcp.ts`	+9 −0
`test/cli/state-mcp.test.ts`	+52 −0

Total: +66 −0

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

github-actions · 2026-06-09T15:43:39Z

🟡 Impact Analysis — PR #1245

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	3
Files added	1
Files modified	2
Files deleted	0
Modules touched	3

🎯 Risk Factors

3 files changed (≤5 → LOW)
3 modules touched (2-4 → MEDIUM)

📦 Modules Affected

root (1 file)

.changeset/memory-mcp-bridge.md

squad-cli (1 file)

packages/squad-cli/src/cli/commands/state-mcp.ts

tests (1 file)

test/cli/state-mcp.test.ts

This report is generated automatically for every PR. See #733 for details.

Copilot

Pull request overview

This PR extends the squad_state MCP server bridge in squad-cli to advertise the governed memory tools (memory.*) via MCP-safe underscore aliases, making them discoverable/invocable by autonomous agents running under Copilot CLI.

Changes:

Added 6 memory_* aliases in MCP_TOOL_ALIASES, routing to the SDK ToolRegistry’s memory.classify/write/search/promote/delete/audit tools.
Expanded state-mcp bridge tests to validate the full tool list (13 total) and exercise MCP routing for memory_classify.
Added a patch changeset for @bradygaster/squad-cli.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
`packages/squad-cli/src/cli/commands/state-mcp.ts`	Adds MCP alias entries to expose governed memory tools through the existing `squad_state` MCP server.
`test/cli/state-mcp.test.ts`	Adds tests asserting the expanded tool list and validates MCP routing for `memory_classify`.
`.changeset/memory-mcp-bridge.md`	Patch changeset documenting the new MCP exposure of governed memory tools in the CLI.

+  it('routes memory_classify via MCP to the SDK ToolRegistry memory.classify handler', { timeout: 30000 }, async () => {
+    const messages: JsonRpcMessage[] = [];
+    const session = createStateMcpSession(TMP, message => messages.push(message as JsonRpcMessage));
+
+    await session.handleRequest({
+      jsonrpc: '2.0',
+      id: 'classify',
+      method: 'tools/call',
+      params: {
+        name: 'memory_classify',
+        arguments: { content: 'Always deploy on Tuesdays' },
+      },
+    });
+
+    const result = resultAsRecord(messages[0]!);
+    expect(result['isError']).not.toBe(true);
+    const content = result['content'] as Array<{ type: string; text: string }>;
+    expect(content).toBeDefined();
+    expect(content[0]?.type).toBe('text');
+    // The classification result should be a non-empty text response
+    expect(content[0]?.text.length).toBeGreaterThan(0);
+  });
+


tamirdresher · 2026-06-09T17:25:46Z

Empirical re-test — bridge works, but MCP loading is the real blocker

After PR was filed, I built this branch locally and ran a series of A/B tests against the test repo to verify the fix actually changes agent behavior.

Test setup

Cloned squad-squad at this branch (squad/1244-memory-mcp-bridge)
npm run build → produces patched cli-entry.js with 6 new memory_* aliases in MCP_TOOL_ALIASES
Direct MCP probe via raw stdio JSON-RPC confirmed all 13 tools exposed: squad_decide, 6× squad_state_*, memory_classify, memory_write, memory_search, memory_promote, memory_delete, memory_audit ✅

Test 1 — bridge works in isolation

Project test repo with .mcp.json pointing to the patched local CLI
Direct probe: copilot -p "call memory_audit and show the result" → ✅ agent successfully called memory_audit via MCP, got back the audit log content

So the bridge fix itself is correct and the tools are reachable.

Test 2 — full directive flow exposes a second blocker

I then ran the realistic flow (user gives a directive, expects the team to remember it) under three configurations:

Scenario	`memory_` / `squad_state_` MCP calls in run
Workspace `.mcp.json` only (typical Squad bootstrap)	0
User-level + workspace `.mcp.json` (after `copilot mcp add squad_state ...`)	2
User-level + workspace (second clean run, same prompt)	4 (`squad_state_health`, `memory_classify`, `memory_write`, `squad_state_write`)

The bridge alone is necessary but not sufficient. With a plain workspace .mcp.json (the file Squad currently bootstraps), the Copilot CLI in non-interactive -p mode does not expose the squad MCP tools to the agent. The agent then falls back to platform Create/Edit writes and — worse — forges a fake audit-log JSON entry that mimics the SDK provider's format but is missing fields like id, path, reason, and provider. Tooling that parses audit.jsonl would not catch this.

Recommendation

Land this PR as-is — the bridge is correct.
File a follow-up to make Squad bootstrap register squad_state at user level (via copilot mcp add ... during squad init / squad upgrade), or surface a clear warning at session start when the MCP isn't reachable.
Tighten squad.agent.md (arch: directive capture + sub-agent decision-recording bypass the governed memory classifier #1246) so the coordinator can't silently fall back to file writes without first verifying via squad_state_health and refusing to forge audit entries.

Verified locally on Windows 10 / Node 24.16 / @bradygaster/squad-cli v0.10.0-build.7.

tamirdresher · 2026-06-10T12:01:36Z

Copilot AI review requested due to automatic review settings June 9, 2026 15:43

Copilot started reviewing on behalf of tamirdresher June 9, 2026 15:43 View session

Copilot AI reviewed Jun 9, 2026

View reviewed changes

tamirdresher closed this Jun 10, 2026

jagilber mentioned this pull request Jul 27, 2026

fix(sdk): normalize dotted ToolRegistry names at Copilot external-tool boundary jagilber/squad#21

Open

7 tasks

Navigation Menu

feat(mcp): bridge governed memory tools (memory.*) through squad_state MCP server - #1245

feat(mcp): bridge governed memory tools (memory.*) through squad_state MCP server#1245
tamirdresher wants to merge 1 commit into
devfrom
squad/1244-memory-mcp-bridge

tamirdresher commented Jun 9, 2026

Uh oh!

github-actions Bot commented Jun 9, 2026

Uh oh!

github-actions Bot commented Jun 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

tamirdresher commented Jun 9, 2026

Uh oh!

tamirdresher commented Jun 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

tamirdresher commented Jun 9, 2026

Summary

What changes

What does NOT change

Why this matters

Test plan

Out of scope

Uh oh!

github-actions Bot commented Jun 9, 2026

🛫 PR Readiness Check

⚠️ 2 item(s) to address before review

Files Changed (3 files, +66 −0)

Uh oh!

github-actions Bot commented Jun 9, 2026

🟡 Impact Analysis — PR #1245

📊 Summary

🎯 Risk Factors

📦 Modules Affected

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

tamirdresher commented Jun 9, 2026

Empirical re-test — bridge works, but MCP loading is the real blocker

Test setup

Test 1 — bridge works in isolation

Test 2 — full directive flow exposes a second blocker

Recommendation

Uh oh!

tamirdresher commented Jun 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants