m1: AgentKeys MCP server — Phase 1 (closes #107)

[hanwencheng]

Summary

Resolves #107 — the Phase 1 MCP server that turns the Phase 0 backend (broker + memory/audit/cred workers + signer) into 10 tools that an MCP-speaking LLM host (xiaozhi-server, Volcano Ark) can call.

New crate: crates/agentkeys-mcp-server/. Additive — no existing crate touched besides adding the workspace member.

This PR is parallel to #131, which bundles #107 + #108/#109/#111 across 429 files. This one stays scoped to #107 alone (32 files, +3187 LOC), so it's reviewable in isolation. PR #131 stays open as the alternative if reviewers prefer the bundled approach.

Why Rust, not Python

Issue #107 lists Python as preferred, Rust as fallback. We went Rust because:

• Every other service in the workspace is Rust — single toolchain, one CI, one Docker pattern.
• The broker / worker DTOs come from agentkeys-core. Re-declaring as Pydantic models = drift.
• MCP is a wire protocol; xiaozhi-server doesn't import the server's source. The "Python integrates faster with xiaozhi" claim is weak across a process boundary.
• Phase 0's crates/agentkeys-mcp/ already proved Rust → xiaozhi-server works.

What landed

Tools (10 total)

Tool	Status	Backend
agentkeys.identity.whoami	active	local (M4 lifts to broker /v1/identity/whoami)
agentkeys.memory.get	active	broker /v1/cap/memory-get → memory worker
agentkeys.memory.put	active	broker /v1/cap/memory-put → memory worker
agentkeys.permission.check	active	deterministic policy engine (no LLM)
agentkeys.cap.mint	active	broker /v1/cap/{cred,memory}-{store,fetch,put,get}
agentkeys.cap.revoke	active	M1 stub — broker endpoint scheduled for M4
agentkeys.audit.append	active	audit worker /v1/audit/append/v2
agentkeys.delegation.{grant,revoke} + agentkeys.approval.request	schema-only	{\"error\":\"not_implemented_in_v1\",\"scheduled_for\":\"M4\",\"spec_url\":...}

Auth (HTTP transport)

• Authorization: Bearer <vendor> → 401 on missing / wrong / malformed
• X-AgentKeys-Actor: <omni> → 403 on missing
• Tool param naming a different actor than the header → JSON-RPC -32003 (FORBIDDEN)

Stdio transport bypasses auth (parent process is implicitly trusted).

Acceptance criteria

#	Criterion	Status	Evidence
1	7 active tools respond correctly	✅ wired; live demo operator-driven	tests/three_acts.rs, tests/http_auth.rs
2	3 schema-only tools return documented shape	✅	tests/schema_only_stubs.rs (3 tests)
3	Bearer + actor scoping (401/403/403)	✅	tests/http_auth.rs (6 tests)
4	Unit tests per tool happy + 1 negative	✅	17 unit tests + tool-specific
5	Integration test exercising three-act storyboard	✅	tests/three_acts.rs (5 tests)
6	CI publishes image; one-command deploy	✅	.github/workflows/mcp-server.yml + Dockerfile
7	Live xiaozhi-server demo	⏳ operator-driven	runbook in plan §5

Tests

unit tests:           17 / 17  (auth, policy, identity, permission)
http_auth.rs:          6 /  6  (acceptance #3)
schema_only_stubs.rs:  3 /  3  (acceptance #2)
three_acts.rs:         5 /  5  (acceptance #5)
─────────────────────────────
total:                31 / 31  +  clippy clean

Live binary smoke test (built + run, verified all four auth paths and Act 2 verdict):

--- healthz --- {\"name\":\"agentkeys-mcp-server\",\"ok\":true}
--- missing bearer --- 401
--- bad bearer --- 401
--- happy path --- tools_count: 10
--- act 2 ---
  \"verdict\": \"deny\"
  \"reason\": \"daily_spend_cap_exceeded\"
  \"explanation\": \"cap=500, requested=600, period=daily\"

What did NOT land (deferred per spec)

• Broker /v1/identity/whoami + /v1/revoke/cap/:id — M4 with vendor portal Phase 2: Tuya Cloud Development connector #114
• Namespace as a SIGNED CapPayload field — follow-up to Phase 1: Memory namespace model — wire to cap-token + worker filter #108
• Active delegation + approval — M4 (issue says schema-only for v1)
• Audit Tier-2 actual on-chain appendRootV2 — out of scope for Phase 1: AgentKeys MCP server — 7 active tools + 3 schema-only #107, covered by Phase 1: Two-tier audit wiring (real-time off-chain feed + 2-min on-chain anchor) #109
• Volcano Ark marketplace registration — Phase 1: Volcano Ark MCP marketplace registration (PoC) #112
• Live xiaozhi-server demo — operator-driven (runbook in plan §5)

Full landed-vs-deferred table: docs/spec/plans/issue-107-mcp-server-phase1.md.

Test plan

• cargo test -p agentkeys-mcp-server — 31/31 green
• cargo clippy -p agentkeys-mcp-server --all-targets -- -D warnings — clean
• cargo build --workspace — clean (no regressions)
• Binary smoke test — 4 auth paths + Act 2 verdict verified
• Live three-act demo against a fresh broker — operator-driven
• xiaozhi-server mcp_server_settings.json integration dry-run with an internal reviewer