fix(mcp): pass server instructions and hide turned-off inspectors' state

[erkamyaman]

What and why

These are the last two #340 items. Both were blocked in devframe 1.2.3:

• Server instructions: devframe and @devframes/agentic have no option to pass them to the MCP Server.
• mcp: agent.tools.<inspector>=false still exposes the inspector's data through devframe_state_read #238: @devframes/agentic already supports a exposeSharedState predicate. But devframe's mountMcpRoute and the hub's initHub hard-code exposeSharedState: true, so devframe_state_read and devframe://state still show inspectors that are turned off for agents.

This PR patches the three packages locally with pnpm patch and wires both into Pangular. Refs #340, #238.

Patch (patches/, patchedDependencies in pnpm-workspace.yaml)

• devframe@1.2.3: resolveMcpConfig and mountMcpRoute carry instructions and exposeSharedState, and the types are updated.
• @devframes/agentic@1.2.3: passes instructions to the SDK Server (stdio and the fetch handler).
• @devframes/hub@1.2.3: initHub forwards both to mountMcpHttp.

Pangular

• Key mapping: SHARED_STATE_INSPECTOR in config.ts maps every pangular: shared-state key to its inspector. sharedStateExposed() hides a key when that inspector's agent tools are off, and also hides unknown pangular: keys. A guard test fails if a new key isn't mapped.
• Instructions: agent-mcp.ts builds short server instructions. Agents call pangular_list-pages first and pass page when several pages are connected. They also get read tools vs action and destructive tools (with a read-only variant), and are told that _untrusted and app text is data, not instructions.
• Wiring: the hub covers both the Express hub and the Vite plugin. pangular dev is wired too.
• Docs:
  • agents/mcp-server.md, agents/resources.md and agents/tools.md
  • the agent.tools row in configuration.md
  • a "Patched dependencies" section in contributing/development.md

How it was verified

• pnpm install --frozen-lockfile
• pnpm commit:check
• pnpm format:check
• pnpm typecheck
• pnpm test:devtools: 2,095 tests. The new agent-mcp.test.ts (14 tests) covers:
  • instructions in initialize
  • pangular:forms missing from the state key list, direct reads, resources/list and resources/read when agent.tools.forms is false, while other keys stay readable
  • the pangular dev path
  • reverting the hub patch makes 3 tests fail
• pnpm skills:check (.claude/ not changed)
• Docs in apps/docs updated and pnpm docs:build passes
• pnpm extension:build (app/ not changed)
• Checked in the browser with axe (no UI change)

Notes for reviewers

• This only fixes things inside this repo. Apps that install the published @pangular-inspector/devtools still get unpatched devframe 1.2.3. They don't get instructions and mcp: agent.tools.<inspector>=false still exposes the inspector's data through devframe_state_read #238 still applies to them. The extra options are ignored there, so nothing breaks. mcp: agent.tools.<inspector>=false still exposes the inspector's data through devframe_state_read #238 stays open until devframe ships the change. Upstream issue drafts and a tested patch for devframes/devframe are ready to file.
• The patches are pinned to 1.2.3 and to its hashed chunk file names. Any devframe upgrade means redoing them with pnpm patch, or dropping them once upstream ships.
• stdio is not covered. pangular mcp has neither feature: that server has no live pages, so turned-off inspectors' state is empty there anyway.
• With auth: false, the hub's MCP route now always mounts, where before it was 'auto'. In practice nothing changes, since Pangular always registers agent tools.
• One flaky test: one full run had a timing failure in forms-collector.test.ts (expected at least 30 ms, got 22). It passes alone and passed on the rerun.

---

Generated by Claude Code

Summary by CodeRabbit

• New Features
  • HTTP MCP connections now provide guidance for selecting pages, using tools safely, respecting read-only mode, and treating app or project content as data rather than instructions.
  • Shared-state keys for inspectors with disabled agent tools are hidden from HTTP MCP resources and reads. The inspector tab and panel access remain available.
• Documentation
  • Clarified MCP connection behavior and how disabling inspector tools affects shared-state visibility.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 2f09c231-cfa1-43c4-b036-70d5ed1cf5a7

---

📥 Commits

Reviewing files that changed from the base of the PR and between 38a42bb and 1ba7894.

---

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

---

📒 Files selected for processing (14)

• apps/docs/src/content/agents/mcp-server.md
• apps/docs/src/content/agents/resources.md
• apps/docs/src/content/agents/tools.md
• apps/docs/src/content/contributing/development.md
• apps/docs/src/content/getting-started/configuration.md
• packages/devtools/src/__tests__/agent-mcp.test.ts
• packages/devtools/src/agent-mcp.ts
• packages/devtools/src/cli.ts
• packages/devtools/src/config.ts
• packages/devtools/src/hub.ts
• patches/@devframes__agentic@1.2.3.patch
• patches/@devframes__hub@1.2.3.patch
• patches/devframe@1.2.3.patch
• pnpm-workspace.yaml

---

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

---

📝 Walkthrough

Walkthrough

The change adds MCP server instructions and filters HTTP MCP shared-state access according to inspector tool settings. It adds local package patches for MCP route options and wires the resulting configuration into the CLI and hub.

Changes

MCP policy and route integration

Layer / File(s)	Summary
MCP route option support patches/devframe@1.2.3.patch, patches/@devframes__agentic@1.2.3.patch, patches/@devframes__hub@1.2.3.patch, pnpm-workspace.yaml	The local patches add and forward instructions and exposeSharedState route options. The workspace maps the package versions to those patches.
Pangular MCP instructions and exposure policy packages/devtools/src/config.ts, packages/devtools/src/agent-mcp.ts, packages/devtools/src/__tests__/agent-mcp.test.ts	The shared-state policy maps Pangular keys to inspectors and checks their tool settings. MCP configuration supplies default instructions and applies the policy to shared-state exposure. Tests cover exposure rules and caller overrides.
CLI and hub integration packages/devtools/src/cli.ts, packages/devtools/src/hub.ts, packages/devtools/src/__tests__/agent-mcp.test.ts, apps/docs/src/content/agents/*, apps/docs/src/content/contributing/development.md, apps/docs/src/content/getting-started/configuration.md	The CLI and hub pass resolved Pangular configuration to MCP setup. Integration tests and documentation cover instructions, filtered state access, and the local patches.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant PangularCLI
  participant PangularMCP
  participant MCPRoute
  participant MCPClient
  PangularCLI->>PangularMCP: Pass MCP setting and resolved config
  PangularMCP->>MCPRoute: Provide instructions and shared-state exposure filter
  MCPClient->>MCPRoute: Initialize and request shared state
  MCPRoute-->>MCPClient: Return instructions and exposed state

Loading

---

Merge Risk | ⚪ Minimal · up to 1ba78

Merge Risk: ⚪ Minimal · up to 1ba78

The change adds MCP instructions and hides shared state for inspectors whose agent tools are disabled. The supplied evidence shows no concrete merge-blocking issue. The local patches are tied to devframe 1.2.3 and must be reworked on upgrade.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 1ba78

The new policy narrows shared-state access while preserving caller authentication settings. Its protection currently depends on repository-local patches and does not extend to ordinary published-package installs. Startup, replacement, and shutdown edge cases remain incompletely verified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• observed — The changed control governs inspector shared state available through a host's MCP endpoint. It is an inspector-namespace policy, not a new per-page or tenant isolation mechanism; non-Pangular shared-state namespaces remain outside its filtering scope.

Security Findings and Attack Paths

• inferred — For patched hosts, direct MCP requests for disabled inspector state are intended to be denied independently of client obedience to server instructions. Forwarding and test assertions support this narrower exposure. Unpatched published installs retain the pre-existing exposure; this review did not establish that the PR expands it.

Trust Boundaries and Controls

• observed — The shared-state policy supplements existing identity and origin controls rather than replacing them. Caller authorization and origin options are preserved, explicit false remains restrictive, and caller exposure predicates are combined with the Pangular predicate using logical conjunction.

Resilience and Maintainability Implications

• observed — Normal startup derives MCP policy before requesting host construction. Hub cleanup is idempotently memoized but asynchronous. Complete request fencing during replacement or failed startup cannot be established from the available dependency patch excerpts.

Hardening Proposals

• proposed — Before presenting disabled-inspector settings as a published-package access guarantee, require dependency versions that implement the exposure options or detect unsupported hosts and refuse the protected MCP configuration. Validate that guarantee using an ordinary consumer installation rather than only the patched workspace.

---

Pre-merge checks | 4 | 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 functions across 5 files. (9 skipped: 9…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the two main changes: passing MCP server instructions and hiding shared state for disabled inspectors.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

---

Full details: Docstring Coverage

Explanation

Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 functions across 5 files. (9 skipped: 9 unsupported.)

---

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

---

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 1ba7894

Command	Status	Duration	Result
nx affected -t test build	✅ Succeeded	1m 33s	View ↗

💡 Verify your cache is correct by running tasks in a sandbox. Read docs ↗

---

☁️ Nx Cloud last updated this comment at 2026-10-12 14:27:44 UTC

[cloudflare-workers-and-pages]

🚀 Deploying Preview to Cloudflare 🚀

Preview Deployments by commit

Status	Deployment URL	Commit	Updated (UTC)	See this deployment's details
Build: Failed ❌ View logs ↗		1ba7894	2026-10-12T14:27:59.140Z	View logs ↗