Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

docs: generate MCP catalog and lock architecture ownership

Rahman70d8491dbc80
diff --git a/AGENTS.md b/AGENTS.md
index 9eedca57..a0ba50e6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,6 +30,10 @@ For debugging, integrations, refactors, deployments, and MCP work, use this loop
`CLAUDE.md`, or a trusted `SKILL.md`; implementation contracts belong in current docs;
volatile host facts stay in project/runbook notes.
+## Architecture ownership
+
+Before adding another adapter/facade/barrel, read [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) and run `node scripts/check-architecture.mjs`. The architecture policy is ratcheted: transports share `lib/capabilities`, cross-layer DTOs live in `lib/contracts`, host calls use narrow `lib/host/*-api.ts`, generic apps use AppShell directly, and workflow persistence belongs to `lib/workflow`. Do not raise a ratchet just to make a change pass. Exact MCP catalog facts are generated with `node scripts/gen-mcp-catalog.mjs`; never hand-copy the current tool list into reference docs.
+
## Repository and worktree policy
- `/home/rahman/projects/mso` on `main` is the **only canonical MSO checkout and release SSOT**.
diff --git a/CLAUDE.md b/CLAUDE.md
index 3016a09d..35558127 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -338,30 +338,19 @@ the real runtime and working analogue before changing a tool or skill contract.
is the control, not the CSRF gate. `proxy.ts` exempts `/mcp`, `/oauth/token`,
`/oauth/register` and `/.well-known/oauth-*` from BOTH that gate and the document
CSP. `/oauth/authorize` is NOT exempt — it is a real HTML page and needs its nonce.
-- **Every tool is a thin call into `lib/host`**, never node `fs`/`child_process`. That
- is what makes the MCP surface inherit `OS_FS_*_ROOTS`, the credential denylist
- (including `~/.mso` itself) and `exec.ts`'s destructive filter for free. A tool that
- reimplements an operation reimplements its guard too — don't.
+- **Tool execution is transport-neutral.** `lib/capabilities/*` owns scope, required-argument validation, workflow correlation, rate limits, audit/activity and execution semantics. MCP/A2A/agent surfaces are adapters over that kernel. Host operations flow through narrow `lib/host/*-api.ts` facades, which preserve `OS_FS_*_ROOTS`, the credential denylist (including `~/.mso`) and destructive-command guards. Do not reimplement a guarded host operation inside an adapter.
- Scope ladder `read < write < exec`, picked per token on the consent page, capped by
`OS_MCP_MAX_SCOPE`. The default ceiling is `exec`, and consent preselects the highest
permitted tier; set the env to `read` or `write` to opt down. `tools/list` filters by
it AND `tools/call` re-checks it — a client can call a name it was never shown.
- **Tool names are an MSO public API contract.** Keep global names MSO-owned and generic.
Project-owned MCP names are data behind `project_mcp_tools` / `project_mcp_call`; never copy them into the global catalog.
- <!-- mcp-toolset: server=1.8.2 version=2026.09.03.7 tools=85 read=41 write=25 exec=19 -->
- The full MSO transport exposes **73 tools**: **72 model/operator tools** (34 read, 24 write, 14 exec) plus app-only `workflow_status`.
- ChatGPT receives a deliberately smaller static profile; hidden full-catalog names are rejected at call time, not merely omitted from `tools/list`.
+ The exact full MSO catalog **and** compact ChatGPT profile are source-generated in [`docs/generated/MCP-CATALOG.md`](./docs/generated/MCP-CATALOG.md); `GET /mcp` remains the live version/hash authority. Hidden ChatGPT-profile names are rejected at call time, not merely omitted from `tools/list`.
- Store is `~/.mso/mcp.json`, **sha256 only**, same atomic-write + fail-loud-on-corrupt
rule as `lib/auth/device-store.ts`. Codes are single-use, 60 s, deleted BEFORE the
token is minted. `browser_status` must never return the VNC password — that profile
holds a live Google session.
-- **The dispatcher writes the audit trail, because the tools bypass the one that
- exists.** `audit()` is called at the ROUTE layer for `/api/v1`; MCP tools call
- `lib/host` directly, so every write/delete/exec over MCP would otherwise be absent
- from `~/.mso/audit.log`. `McpTool.audit` declares the action + which arg is the
- target; `dispatch()` records it with `actor: mcp:<id>` (the id Settings shows) and
- `meta.via = "mcp"`. Scope refusals log `mcp.denied` — that is the prompt-injection
- signal. Reads stay unlogged, same rule the routes follow. `GET /api/v1/sys/audit`
+- **The capability kernel writes the audit trail, because model-facing tools bypass route-layer audit.** `/api/v1` routes audit at the route layer; capability tools may call guarded host APIs directly, so `lib/capabilities/execute.ts` enforces scope/rate/workflow telemetry and records declared `CapabilityTool.audit` actions once for MCP/A2A/agent adapters. MCP uses `actor: mcp:<id>` and `meta.via = "mcp"`; scope refusals log `mcp.denied`. Reads stay unlogged, same rule the routes follow. `GET /api/v1/sys/audit`
reads it (session-gated); there is deliberately **no MCP tool** for it, or a
compromised token could check whether it had been noticed.
diff --git a/architecture.boundaries.json b/architecture.boundaries.json
index 8d8a778f..d9486c87 100644
--- a/architecture.boundaries.json
+++ b/architecture.boundaries.json
@@ -10,7 +10,11 @@
"nonMcpMcpImports": 0,
"crossProtocolCycles": 0,
"legacyWorkflowFacadeImports": 0,
- "hostFacadeImports": 0
+ "hostFacadeImports": 0,
+ "legacyHostMockSeams": 0,
+ "osShellAppShellProxyExports": 0,
+ "cliEntrypointLines": 220,
+ "installerCoreLines": 450
},
"notes": {
"policy": "Ratchets may only stay equal or decrease. Raise a baseline only with an explicit architecture decision.",
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 2631f8b2..6ee75ba8 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -160,8 +160,9 @@ park a visible Approve/Deny card. The complete semantic contract is
**MCP** is for external clients such as ChatGPT, Claude.ai and Cursor. Its catalog lives in
`lib/mcp/`; access is controlled by the OAuth token scope rather than Alfa approval cards.
-<!-- mcp-toolset: server=1.8.2 version=2026.09.03.7 tools=85 read=41 write=25 exec=19 -->
-The full transport exposes **73 tools**: **72 model/operator tools** (34 read, 24 write, 14 exec) plus app-only `workflow_status`. ChatGPT gets a compact client profile rather than the full set. Project function/MCP names remain data behind `project_capabilities`, `project_function_call`, `project_mcp_tools`, and `project_mcp_call`; they never rewrite the global tool prefix. `GET /mcp` reports both full and ChatGPT signatures.
+
+Capability execution is transport-neutral: `lib/capabilities/` owns shared execution policy, while `lib/mcp/`, `lib/a2a/`, and agent surfaces remain adapters. Guarded filesystem/exec/project operations are exposed through narrow `lib/host/*-api.ts` facades rather than one giant host import surface.
+The exact full transport catalog and compact ChatGPT profile are generated from source in [`generated/MCP-CATALOG.md`](./generated/MCP-CATALOG.md). Project function/MCP names remain data behind `project_capabilities`, `project_function_call`, `project_mcp_tools`, and `project_mcp_call`; they never rewrite the global tool prefix. `GET /mcp` reports the live full and ChatGPT signatures.
See `docs/MCP.md` for protocol/security internals, `docs/A2A.md` for peer-agent delegation, and `docs/CHATGPT-PLUGIN.md` for the
ChatGPT-facing setup and diagrams.
diff --git a/docs/CHATGPT-PLUGIN.md b/docs/CHATGPT-PLUGIN.md
index 4a03623d..55ee22b6 100644
--- a/docs/CHATGPT-PLUGIN.md
+++ b/docs/CHATGPT-PLUGIN.md
@@ -4,13 +4,11 @@
>
> ChatGPT's Developer Mode/App UI can change independently of MSO. Use the current OpenAI MCP/App documentation for exact menu labels, and use MSO Settings → MCP / `GET /mcp` for the live server/profile signatures.
-<!-- mcp-chatgpt-profile: server=1.8.2 version=2026.09.03.7 tools=61 read=32 write=17 exec=12 app-only=1 total=62 -->
-
-MSO server **1.8.2**, toolset **2026.09.03.7** exposes the full generic catalog for MCP clients, while a registered ChatGPT client receives **62 transport tools**: **61 model/operator tools** (32 read, 17 write, 12 exec) plus app-only `workflow_status`.
+The exact current server/toolset identity plus the full MSO and compact ChatGPT name/scope catalogs are generated from source in [`generated/MCP-CATALOG.md`](./generated/MCP-CATALOG.md). `GET /mcp` and Settings → MCP remain the live deployed signature authority.
Browser-hosted MCP probes from ChatGPT are allowed only when they target the configured public `OS_PUBLIC_ORIGIN`; arbitrary origins and ChatGPT-origin requests aimed at loopback remain denied. Additional trusted browser hosts can be added explicitly with comma-separated `OS_MCP_BROWSER_ORIGINS`. Public OAuth discovery and DCR responses carry CORS metadata; authenticated `/mcp` echoes only an approved exact origin.
-The compact descriptor regression currently measures **64,180 JSON bytes** for all 62 ChatGPT transport tool definitions (roughly 16.0k tokens at a 4-byte/token estimate), with the largest individual descriptor **2,615 bytes**. CI keeps the profile below 72 KiB and each descriptor below 8 KiB. Bytes are the deterministic contract; token estimates vary by tokenizer.
+The compact descriptor regression currently measures **64,180 JSON bytes** for the current generated ChatGPT profile (roughly 16.0k tokens at a 4-byte/token estimate), with the largest individual descriptor **2,615 bytes**. CI keeps the profile below 72 KiB and each descriptor below 8 KiB. Bytes are the deterministic contract; token estimates vary by tokenizer.
## Why ChatGPT gets a compact profile
@@ -51,87 +49,15 @@ The ChatGPT projection compacts verbose descriptions/schema descriptions without
## Exact ChatGPT model tool profile
-### `read` — 32 ChatGPT model tools
-
-- `agent_session_current`
-- `apps_list`
-- `apps_logs`
-- `browser_status`
-- `cloudflare_zones_list`
-- `connections_list`
-- `dokploy_projects_list`
-- `exec_job_status`
-- `fs_list`
-- `fs_read`
-- `fs_search`
-- `fs_usage`
-- `infra_provider_doctor`
-- `infra_providers_list`
-- `local_agent_inbox`
-- `local_agent_request_wait`
-- `local_agents_list`
-- `project_agent_status`
-- `project_capabilities`
-- `project_changes_list`
-- `project_diff`
-- `project_get`
-- `project_knowledge_get`
-- `projects_list`
-- `read_pipeline`
-- `screen_capture`
-- `skills_list`
-- `skills_read`
-- `skills_search`
-- `sys_processes`
-- `sys_stats`
-- `vps_status`
-
-### `write` — + 17 ChatGPT model tools
-
-- `agent_session_rename`
-- `apps_power`
-- `cloudflare_dns_upsert`
-- `dokploy_project_ensure`
-- `fs_copy`
-- `fs_delete`
-- `fs_mkdir`
-- `fs_move`
-- `fs_upload_file`
-- `fs_write`
-- `hostinger_dns_upsert`
-- `local_agent_message_send`
-- `local_agent_reply`
-- `project_knowledge_set`
-- `workflow_cancel`
-- `workflow_finish`
-- `workflow_start`
-
-### `exec` — + 12 ChatGPT model tools
-
-- `browser_power`
-- `exec_job_cancel`
-- `exec_job_start`
-- `exec_run`
-- `project_agent_run`
-- `project_database_call`
-- `project_database_query`
-- `project_database_status`
-- `project_database_tools`
-- `project_function_call`
-- `project_mcp_call`
-- `project_mcp_tools`
-
-### App-only ChatGPT bridge
-
-`workflow_status` is available to the MCP Apps progress UI but is not counted as a model/operator action.
+The exact current ChatGPT profile is generated under **ChatGPT static profile** in [`generated/MCP-CATALOG.md`](./generated/MCP-CATALOG.md). Its source is `CHATGPT_TOOL_NAMES` in `lib/mcp/tool-contract.ts`; CI fails if that profile references a missing global tool. The profile remains fail-closed at both `tools/list` and `tools/call`, while OAuth `read < write < exec` is enforced independently.
The restored Original MSO operator primitives (`sys_*`, `fs_usage` + full bounded filesystem CRUD, `apps_*`, browser power/status, and Dokploy/Cloudflare/Hostinger operations) are again first-class ChatGPT actions. Fresh 3 adds `vps_status`, project snapshot/diff/history/knowledge, private project-agent message/status, connection inventory, and Convex database seams without removing the lower-level primitives. This is intentional: aggregate tools optimize common turns; bounded primitives preserve direct operator control.
-Project-owned MCP names and Convex's own dynamic schemas still load on demand through `project_mcp_tools` / `project_mcp_call` and `project_database_tools` / `project_database_call`. That is how MSO keeps a 61-action static model profile instead of copying every downstream provider/project action into ChatGPT.
+Project-owned MCP names and Convex's own dynamic schemas still load on demand through `project_mcp_tools` / `project_mcp_call` and `project_database_tools` / `project_database_call`. That is how MSO keeps a bounded static model profile instead of copying every downstream provider/project action into ChatGPT.
### Structured-result contract
-After the Fresh 3 rescan exposed `Output schema recommended` on non-UI actions, the ChatGPT profile now advertises an output schema on **all 62 transport actions** without duplicating dozens of provider/project result definitions. Tools with stable UI-critical shapes keep their explicit typed schemas. Every other ChatGPT action uses one exact outer `{ result: ... }` contract and returns the already-bounded JSON value inside `structuredContent.result`; its text `content` is a short acknowledgement so the same payload is not duplicated in the conversation transcript. Full/generic MCP clients keep the historical text-only contract unless a tool explicitly declares structured output. `screen_capture` keeps the image in MCP content and exposes only safe dimensions/URLs/expiry metadata in the structured envelope—never base64 image bytes.
+After the Fresh 3 rescan exposed `Output schema recommended` on non-UI actions, the ChatGPT profile now advertises an output schema on **all current ChatGPT transport actions** without duplicating dozens of provider/project result definitions. Tools with stable UI-critical shapes keep their explicit typed schemas. Every other ChatGPT action uses one exact outer `{ result: ... }` contract and returns the already-bounded JSON value inside `structuredContent.result`; its text `content` is a short acknowledgement so the same payload is not duplicated in the conversation transcript. Full/generic MCP clients keep the historical text-only contract unless a tool explicitly declares structured output. `screen_capture` keeps the image in MCP content and exposes only safe dimensions/URLs/expiry metadata in the structured envelope—never base64 image bytes.
### Native MCP skill snapshot
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index e03210fe..2670f1d4 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -122,12 +122,7 @@ Three things that will bite:
and the named root includes for `proxy.test.ts` / `proxy-websocket.test.ts`), cannot
run suites that use `vi.mock`, and **exits 0 having run nothing** — so `verify` goes
green while testing zero files. Same trap in CI.
-- **`node-pty` must stay in `trustedDependencies`.** It has no Linux prebuild, so it
- compiles at install time (hence the C++ toolchain + python3 requirement), and bun
- skips lifecycle scripts unless the package is trusted. Its binding loads eagerly via
- `lib/host/pty.ts` → `lib/host/index.ts`, which every `/api/v1` route imports — so a
- skipped build is not a Terminal outage, it is the entire host API failing at import.
- Gate any dependency change on `node -e "require('node-pty')"`.
+- **`node-pty` must stay in `trustedDependencies`.** It has no Linux prebuild, so it compiles at install time (hence the C++ toolchain + python3 requirement), and bun skips lifecycle scripts unless the package is trusted. Terminal code reaches it through the narrow `lib/host/terminal-api.ts` facade; unrelated routes no longer import a giant host barrel. Gate any dependency change on `node -e "require('node-pty')"` because PTY functionality is still release-critical.
- **Never `bunx`/`bun x` in a deploy script.** Unlike `pnpm exec`, bunx *downloads* a
missing package and runs it. On the box that serves an authenticated remote shell,
that turns a capability check into a fetch-and-execute. Call `node_modules/.bin/<tool>`
diff --git a/docs/MCP-FEATURE-IMPLEMENTATION.md b/docs/MCP-FEATURE-IMPLEMENTATION.md
index 20f309b7..84202a0e 100644
--- a/docs/MCP-FEATURE-IMPLEMENTATION.md
+++ b/docs/MCP-FEATURE-IMPLEMENTATION.md
@@ -62,7 +62,7 @@ A public tool is not only a function. Its release contract spans all of these su
| Public name | Stable snake_case name; renames/removals require external mapping review |
| Description/schema | Exact input contract, bounded values, required fields, and file annotations |
| Scope | `read`, `write`, or `exec`; list filtering and call-time enforcement must agree |
-| Handler | Thin adapter into `lib/host` or another existing guarded capability |
+| Handler | Thin tool descriptor/adapter; shared execution policy lives in `lib/capabilities`, host effects in the narrow guarded `lib/host/*-api.ts` facade |
| Audit | Mutating/exec operations declare action and target; dispatcher records MCP actor |
| Limits | Timeouts, rate/size caps, allowed roots, pagination, and continuation semantics |
| Parity | Alfa/MCP coverage or an explicit documented reason for MCP-only behavior |
@@ -72,11 +72,9 @@ A public tool is not only a function. Its release contract spans all of these su
Implementation sequence:
-1. Inspect the closest existing tool and the shared host capability it delegates to.
-2. Add or adjust the schema and scope in the authoritative MCP catalog; do not bypass the
- dispatcher or call raw `fs`/`child_process` from the tool.
-3. Add audit metadata for mutations/exec and keep reads unlogged unless the established policy
- changes deliberately.
+1. Inspect the closest existing tool, the transport-neutral capability policy it inherits, and the narrow host/domain facade it delegates to.
+2. Add or adjust the schema and scope in the authoritative MCP catalog; do not bypass `executeCapabilityCall()` or call raw `fs`/`child_process` from the tool.
+3. Add audit metadata for mutations/exec; the capability kernel records the transport actor consistently and keeps reads unlogged unless policy deliberately changes.
4. Test schema validation, scope visibility, call-time refusal, limits, handler response, audit,
and failure shape.
5. Run Alfa/MCP parity tests and treat every public MSO tool name/schema as a compatibility contract before changing it.
diff --git a/docs/MCP.md b/docs/MCP.md
index f9385380..03dd8cae 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -71,11 +71,13 @@ active in the **running** process (demo mode also forces MCP off).
Picked per token, on the consent screen, capped by `OS_MCP_MAX_SCOPE`. The highest allowed tier is preselected (`exec` on a default install); lower it before Allow when a client does not need full host access.
-| Scope | Tools |
+| Scope | Meaning |
|---|---|
-| `read` | `a2a_agent_discover` `a2a_agents_list` `a2a_task_get` `agent_memory_read` `agent_memory_search` `agent_session_current` `agent_session_resume` `agent_sessions_list` `apps_list` `apps_logs` `browser_status` `cloudflare_zones_list` `connections_list` `dokploy_projects_list` `exec_job_status` `fs_list` `fs_read` `fs_search` `fs_usage` `infra_provider_doctor` `infra_providers_list` `local_agent_inbox` `local_agent_request_wait` `local_agents_list` `project_agent_status` `project_capabilities` `project_changes_list` `project_diff` `project_get` `project_knowledge_get` `project_memory_search` `projects_list` `read_pipeline` `screen_capture` `skills_list` `skills_read` `skills_search` `sys_processes` `sys_stats` `tool_forge_candidates` `vps_status` |
-| `write` | + `a2a_agent_register` `a2a_agent_remove` `agent_memory_forget` `agent_memory_remember` `agent_session_note` `agent_session_rename` `apps_power` `cloudflare_dns_upsert` `dokploy_project_ensure` `fs_copy` `fs_delete` `fs_mkdir` `fs_move` `fs_upload_file` `fs_write` `hostinger_dns_upsert` `local_agent_message_send` `local_agent_reply` `project_knowledge_set` `project_memory_upsert` `project_script_run` `tool_forge_propose` `workflow_cancel` `workflow_finish` `workflow_start` |
-| `exec` | + `a2a_handoff` `a2a_message_send` `a2a_task_cancel` `agent_subagent_run` `browser_power` `exec_job_cancel` `exec_job_start` `exec_run` `local_agent_request` `project_agent_run` `project_database_call` `project_database_query` `project_database_status` `project_database_tools` `project_function_call` `project_mcp_call` `project_mcp_tools` `tool_forge_evaluate` `tool_forge_promote` |
+| `read` | bounded observation/discovery only |
+| `write` | cumulative `read` plus bounded mutation |
+| `exec` | cumulative `write` plus host/delegated execution |
+
+Exact full-catalog and ChatGPT-profile membership is source-generated in [`generated/MCP-CATALOG.md`](./generated/MCP-CATALOG.md). `tools/list` and `tools/call` independently enforce the same scope ladder.
Alfa — the in-app assistant — overlaps the same host capabilities under dot.case names,
and `lib/mcp/parity.test.ts` fails if one surface gains a tool the other lacks
@@ -116,10 +118,8 @@ The catalog has a stable server version plus a schema-derived toolset signature.
Settings → MCP shows the current version/hash/count and stores a browser-local acknowledgement when the operator marks ChatGPT refreshed. A later signature change becomes an explicit stale-snapshot warning. This does not mutate ChatGPT remotely; it makes the required refresh visible instead of relying on memory.
-<!-- mcp-toolset: server=1.8.2 version=2026.09.03.7 tools=85 read=41 write=25 exec=19 -->
+The exact current server/toolset identity, full transport/model counts, compact ChatGPT profile, scope counts and tool names are generated in [`generated/MCP-CATALOG.md`](./generated/MCP-CATALOG.md). `GET /mcp` remains the live deployed authority and additionally exposes schema-derived full/profile hashes. See [`CHATGPT-PLUGIN.md`](./CHATGPT-PLUGIN.md) for ChatGPT-specific behavior.
-Current full transport catalog: **86 tools**, server `1.8.2` / toolset `2026.09.03.7`.
-The model/operator catalog is **85 tools** (41 read, 25 write, 19 exec); `workflow_status` is the one app-only MCP Apps bridge. ChatGPT receives a smaller client profile rather than this full set; see [`CHATGPT-PLUGIN.md`](./CHATGPT-PLUGIN.md).
`agent_memory_search` is the typed-memory retrieval surface. It resolves semantic/episodic/procedural claims at an optional point in time, returns confidence/provenance and competing effective claims, and can expose superseded/retracted history when explicitly requested. `agent_memory_remember` remains the write surface and now accepts typed metadata; raw ChatGPT conversation ids are never stored as provenance.
Session/memory tools add durable conversation context without creating dynamic per-project global names. Project functions use `project_capabilities` / `project_function_call`; project MCP servers use `project_capabilities` / `project_mcp_tools` / `project_mcp_call`. In both cases project-specific names remain data, not entries in MSO `tools/list`.
diff --git a/docs/generated/MCP-CATALOG.md b/docs/generated/MCP-CATALOG.md
new file mode 100644
index 00000000..2103d995
--- /dev/null
+++ b/docs/generated/MCP-CATALOG.md
@@ -0,0 +1,206 @@
+# Generated MCP catalog
+
+> **Generated file — do not edit manually.** Source of truth: `lib/mcp/tools.ts`, its registered `tools-*` modules, `lib/mcp/toolset.ts`, and the compact ChatGPT name set in `lib/mcp/tool-contract.ts`. Regenerate with `node scripts/gen-mcp-catalog.mjs`. The live deployed authority remains `GET /mcp`.
+
+## Full MSO catalog
+
+<!-- mcp-toolset: server=1.8.2 version=2026.09.03.7 tools=85 read=41 write=25 exec=19 -->
+
+| Fact | Current source value |
+|---|---:|
+| MCP server | `1.8.2` |
+| Toolset | `2026.09.03.7` |
+| Toolset changed at | `2026-09-03T14:51:00Z` |
+| Transport tools | **86** |
+| Model/operator tools | **85** |
+| Read | **41** |
+| Write | **25** |
+| Exec | **19** |
+| App-only bridges | **1** |
+
+### Read (41)
+
+- `a2a_agent_discover`
+- `a2a_agents_list`
+- `a2a_task_get`
+- `agent_memory_read`
+- `agent_memory_search`
+- `agent_session_current`
+- `agent_session_resume`
+- `agent_sessions_list`
+- `apps_list`
+- `apps_logs`
+- `browser_status`
+- `cloudflare_zones_list`
+- `connections_list`
+- `dokploy_projects_list`
+- `exec_job_status`
+- `fs_list`
+- `fs_read`
+- `fs_search`
+- `fs_usage`
+- `infra_provider_doctor`
+- `infra_providers_list`
+- `local_agent_inbox`
+- `local_agent_request_wait`
+- `local_agents_list`
+- `project_agent_status`
+- `project_capabilities`
+- `project_changes_list`
+- `project_diff`
+- `project_get`
+- `project_knowledge_get`
+- `project_memory_search`
+- `projects_list`
+- `read_pipeline`
+- `screen_capture`
+- `skills_list`
+- `skills_read`
+- `skills_search`
+- `sys_processes`
+- `sys_stats`
+- `tool_forge_candidates`
+- `vps_status`
+
+### Write (25)
+
+- `a2a_agent_register`
+- `a2a_agent_remove`
+- `agent_memory_forget`
+- `agent_memory_remember`
+- `agent_session_note`
+- `agent_session_rename`
+- `apps_power`
+- `cloudflare_dns_upsert`
+- `dokploy_project_ensure`
+- `fs_copy`
+- `fs_delete`
+- `fs_mkdir`
+- `fs_move`
+- `fs_upload_file`
+- `fs_write`
+- `hostinger_dns_upsert`
+- `local_agent_message_send`
+- `local_agent_reply`
+- `project_knowledge_set`
+- `project_memory_upsert`
+- `project_script_run`
+- `tool_forge_propose`
+- `workflow_cancel`
+- `workflow_finish`
+- `workflow_start`
+
+### Exec (19)
+
+- `a2a_handoff`
+- `a2a_message_send`
+- `a2a_task_cancel`
+- `agent_subagent_run`
+- `browser_power`
+- `exec_job_cancel`
+- `exec_job_start`
+- `exec_run`
+- `local_agent_request`
+- `project_agent_run`
+- `project_database_call`
+- `project_database_query`
+- `project_database_status`
+- `project_database_tools`
+- `project_function_call`
+- `project_mcp_call`
+- `project_mcp_tools`
+- `tool_forge_evaluate`
+- `tool_forge_promote`
+
+### App-only bridges (1)
+
+- `workflow_status`
+
+## ChatGPT static profile
+
+<!-- mcp-chatgpt-profile: server=1.8.2 version=2026.09.03.7 tools=61 read=32 write=17 exec=12 app-only=1 total=62 -->
+
+The ChatGPT profile is a fail-closed static projection defined by `CHATGPT_TOOL_NAMES`. OAuth scope is still enforced independently; project-owned MCP tool names remain dynamic data behind the generic project bridge.
+
+| Fact | Current source value |
+|---|---:|
+| ChatGPT transport tools | **62** |
+| ChatGPT model/operator tools | **61** |
+| Read | **32** |
+| Write | **17** |
+| Exec | **12** |
+| App-only bridges | **1** |
+
+### ChatGPT read (32)
+
+- `agent_session_current`
+- `apps_list`
+- `apps_logs`
+- `browser_status`
+- `cloudflare_zones_list`
+- `connections_list`
+- `dokploy_projects_list`
+- `exec_job_status`
+- `fs_list`
+- `fs_read`
+- `fs_search`
+- `fs_usage`
+- `infra_provider_doctor`
+- `infra_providers_list`
+- `local_agent_inbox`
+- `local_agent_request_wait`
+- `local_agents_list`
+- `project_agent_status`
+- `project_capabilities`
+- `project_changes_list`
+- `project_diff`
+- `project_get`
+- `project_knowledge_get`
+- `projects_list`
+- `read_pipeline`
+- `screen_capture`
+- `skills_list`
+- `skills_read`
+- `skills_search`
+- `sys_processes`
+- `sys_stats`
+- `vps_status`
+
+### ChatGPT write (17)
+
+- `agent_session_rename`
+- `apps_power`
+- `cloudflare_dns_upsert`
+- `dokploy_project_ensure`
+- `fs_copy`
+- `fs_delete`
+- `fs_mkdir`
+- `fs_move`
+- `fs_upload_file`
+- `fs_write`
+- `hostinger_dns_upsert`
+- `local_agent_message_send`
+- `local_agent_reply`
+- `project_knowledge_set`
+- `workflow_cancel`
+- `workflow_finish`
+- `workflow_start`
+
+### ChatGPT exec (12)
+
+- `browser_power`
+- `exec_job_cancel`
+- `exec_job_start`
+- `exec_run`
+- `project_agent_run`
+- `project_database_call`
+- `project_database_query`
+- `project_database_status`
+- `project_database_tools`
+- `project_function_call`
+- `project_mcp_call`
+- `project_mcp_tools`
+
+### ChatGPT app-only bridges (1)
+
+- `workflow_status`
diff --git a/docs/integrations/CHATGPT-UI.md b/docs/integrations/CHATGPT-UI.md
index 5b423ead..4da9cd40 100644
--- a/docs/integrations/CHATGPT-UI.md
+++ b/docs/integrations/CHATGPT-UI.md
@@ -35,7 +35,9 @@ Source boundaries:
| Workflow structured schema | `lib/mcp/tools-workflow-start.ts`, `lib/mcp/tools-workflow-lifecycle.ts` |
| Project/diff structured schemas | `lib/mcp/tools-project-experience.ts` |
| VPS structured schema | `lib/mcp/tools-operator-dashboard.ts` |
-| Shared descriptor contract | `lib/mcp/tool-kit.ts`, `lib/mcp/tool-contract.ts` |
+| Shared executable capability schema | `lib/capabilities/tool.ts` (`lib/mcp/tool-kit.ts` is the compatibility adapter) |
+| MCP descriptor/profile contract | `lib/mcp/tool-contract.ts` |
+| Toolset signature | `lib/mcp/toolset.ts` |
| Tests | `lib/mcp/ui-resources.test.ts` |
## Data boundaries
diff --git a/package.json b/package.json
index e89bef41..38d65803 100644
--- a/package.json
+++ b/package.json
@@ -35,7 +35,8 @@
"bench:pipeline": "bun scripts/bench-read-pipeline.mjs",
"bench:corpus": "bun scripts/bench-agent-corpus.mjs",
"bench:corpus:repeat": "bun scripts/bench-agent-repeat.mjs",
- "bench:cache-calibration": "bun scripts/bench-agent-cache.mjs"
+ "bench:cache-calibration": "bun scripts/bench-agent-cache.mjs",
+ "mcp:catalog": "node scripts/gen-mcp-catalog.mjs"
},
"dependencies": {
"@anthropic-ai/sdk": "^0.120.0",
diff --git a/scripts/check-architecture.mjs b/scripts/check-architecture.mjs
index 3f60180c..1ec82b8f 100755
--- a/scripts/check-architecture.mjs
+++ b/scripts/check-architecture.mjs
@@ -34,11 +34,23 @@ const hostFacadeImports = sourceFiles.reduce((count, file) => {
const source = readFileSync(file, "utf8");
return count + (source.match(/from\s+["']@\/lib\/host["']/g)?.length ?? 0);
}, 0);
+const legacyHostMockSeams = sourceFiles.reduce((count, file) => {
+ const source = readFileSync(file, "utf8");
+ return count + (source.match(/vi\.(?:doMock|mock)\(["']@\/lib\/host["']/g)?.length ?? 0);
+}, 0);
+const osShellAppShellProxyExports = sourceFiles.reduce((count, file) => {
+ const relPath = rel(ROOT, file);
+ if (!relPath.startsWith("frontend/slices/os-shell/")) return count;
+ const source = readFileSync(file, "utf8");
+ return count + (source.match(/export\s+\*\s+from\s+["']@\/features\/appshell["']/g)?.length ?? 0);
+}, 0);
+const cliEntrypointLines = readFileSync(pathResolve(ROOT, "bin/mso"), "utf8").split("\n").length;
+const installerCoreLines = readFileSync(pathResolve(ROOT, "scripts/install-core.sh"), "utf8").split("\n").length;
const crossProtocol = structural.filter(({ ring }) => {
const domains = new Set(ring.slice(0, -1).map(domain));
return domains.has("lib/mcp") && (domains.has("lib/a2a") || domains.has("lib/agent"));
});
-const metrics = { structuralCycles: structural.length, crossDomainCycles: crossDomain.length, crossProtocolCycles: crossProtocol.length, filesOver220, filesOver500, serverFrontendImports, appshellSelfBarrelImports, nonMcpMcpImports, legacyWorkflowFacadeImports, hostFacadeImports };
+const metrics = { structuralCycles: structural.length, crossDomainCycles: crossDomain.length, crossProtocolCycles: crossProtocol.length, filesOver220, filesOver500, serverFrontendImports, appshellSelfBarrelImports, nonMcpMcpImports, legacyWorkflowFacadeImports, hostFacadeImports, legacyHostMockSeams, osShellAppShellProxyExports, cliEntrypointLines, installerCoreLines };
let failed = false;
console.log("Architecture health");
for (const [key, current] of Object.entries(metrics)) {
diff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjs
index a6a3f279..683d9dbb 100755
--- a/scripts/check-docs.mjs
+++ b/scripts/check-docs.mjs
@@ -3,120 +3,37 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
import { dirname, join, relative, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { spawnSync } from "node:child_process";
+import { collectMcpCatalog } from "./lib/mcp-catalog.mjs";
const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
const fail = [];
const read = (p) => readFileSync(join(ROOT, p), "utf8");
-// --- MCP toolset: source is authoritative; docs carry a machine-readable marker.
-const toolset = read("lib/mcp/toolset.ts");
-const server = /MCP_SERVER_VERSION\s*=\s*"([^"]+)"/.exec(toolset)?.[1];
-const version = /MCP_TOOLSET_VERSION\s*=\s*"([^"]+)"/.exec(toolset)?.[1];
-if (!server || !version) fail.push("could not parse MCP version constants");
+// --- MCP catalog: one generated SSOT for the full server + compact ChatGPT profile.
+const catalog = collectMcpCatalog(ROOT);
+for (const name of catalog.orphanModules) fail.push(`lib/mcp/${name}: tool module exists but is not reachable from lib/mcp/tools.ts`);
+for (const name of catalog.missingModules) fail.push(`lib/mcp/${name}: imported tool module is missing`);
+for (const name of catalog.profileMissing) fail.push(`lib/mcp/tool-contract.ts: ChatGPT profile references missing MCP tool ${name}`);
-// Tool catalog modules may be split recursively (for example RASMIC workflow
-// modules). Start at tools.ts and follow every local tools-* import transitively.
-// Any top-level tools-*.ts module that is not reachable is dead/unregistered code
-// and fails CI instead of silently escaping the documentation contract.
-const toolModuleName = /^tools-[A-Za-z0-9-]+\.ts$/;
-const discoveredToolModules = readdirSync(join(ROOT, "lib/mcp"))
- .filter((name) => toolModuleName.test(name))
- .sort();
-const reachable = new Set();
-const pending = ["tools.ts"];
-while (pending.length) {
- const name = pending.pop();
- if (!name || reachable.has(name)) continue;
- reachable.add(name);
- const text = read(`lib/mcp/${name}`);
- for (const match of text.matchAll(/from\s+["']\.\/(tools-[A-Za-z0-9-]+)["']/g)) {
- const child = `${match[1]}.ts`;
- if (!reachable.has(child)) pending.push(child);
- }
-}
-for (const name of discoveredToolModules) {
- if (!reachable.has(name)) fail.push(`lib/mcp/${name}: tool module exists but is not reachable from lib/mcp/tools.ts`);
-}
-for (const name of reachable) {
- if (name !== "tools.ts" && !discoveredToolModules.includes(name)) fail.push(`lib/mcp/${name}: imported tool module is missing`);
-}
-const toolFiles = [...reachable].sort().map((name) => `lib/mcp/${name}`);
-const tools = new Map();
-for (const file of toolFiles) {
- const text = read(file);
- const matches = text.matchAll(/name:\s*"([^"]+)"[\s\S]*?scope:\s*"(read|write|exec)"/g);
- for (const [, name, scope] of matches) tools.set(name, scope);
-}
-
-// App-only MCP bridge tools are intentionally absent from the model/operator action
-// catalogs. They must be documented in the MCP App UI guide instead. Keep this list
-// tiny and explicit: adding a hidden bridge should be a conscious review decision.
-const appOnlyTools = new Set(["workflow_status"]);
-const documentedTools = new Map([...tools].filter(([name]) => !appOnlyTools.has(name)));
const appUiDoc = read("docs/integrations/CHATGPT-UI.md");
-for (const name of appOnlyTools) {
- if (!tools.has(name)) fail.push(`app-only MCP tool ${name} is no longer in the source catalog`);
+for (const name of catalog.appOnly) {
if (!appUiDoc.includes(`\`${name}\``)) fail.push(`docs/integrations/CHATGPT-UI.md: app-only MCP tool ${name} is not documented`);
}
-const counts = { read: 0, write: 0, exec: 0 };
-for (const scope of documentedTools.values()) counts[scope] += 1;
-const marker = `server=${server} version=${version} tools=${documentedTools.size} read=${counts.read} write=${counts.write} exec=${counts.exec}`;
-const markerDocs = ["docs/MCP.md", "docs/ARCHITECTURE.md", "CLAUDE.md"];
-for (const file of markerDocs) {
- const text = read(file);
- if (!text.includes(`<!-- mcp-toolset: ${marker} -->`)) {
- fail.push(`${file}: MCP marker stale; expected ${marker}`);
- }
-}
-for (const file of ["docs/MCP.md"]) {
- const text = read(file);
- for (const name of documentedTools.keys()) {
- if (!text.includes(`\`${name}\``)) fail.push(`${file}: MCP tool ${name} is not documented`);
- }
-}
-
-// ChatGPT uses a deliberately compact static profile. Parse its SSOT name set
-// from tool-contract.ts, then require the ChatGPT guide to match THAT profile
-// rather than the full MSO catalog. Project-owned dynamic MCP names never belong
-// in this set.
-const toolContract = read("lib/mcp/tool-contract.ts");
-const profileBlock = /CHATGPT_TOOL_NAMES\s*=\s*new Set\(\[([\s\S]*?)\]\s*as const\)/.exec(toolContract)?.[1] ?? "";
-const chatgptNames = [...profileBlock.matchAll(/"([^"]+)"/g)].map((match) => match[1]);
-if (!chatgptNames.length) fail.push("could not parse CHATGPT_TOOL_NAMES from lib/mcp/tool-contract.ts");
-for (const name of chatgptNames) if (!tools.has(name)) fail.push(`ChatGPT profile references missing MCP tool ${name}`);
-const chatgptModelTools = new Map(chatgptNames.filter((name) => !appOnlyTools.has(name)).map((name) => [name, tools.get(name)]));
-const chatgptCounts = { read: 0, write: 0, exec: 0 };
-for (const scope of chatgptModelTools.values()) if (scope) chatgptCounts[scope] += 1;
-const chatgptAppOnly = chatgptNames.filter((name) => appOnlyTools.has(name)).length;
-const profileMarker = `server=${server} version=${version} tools=${chatgptModelTools.size} read=${chatgptCounts.read} write=${chatgptCounts.write} exec=${chatgptCounts.exec} app-only=${chatgptAppOnly} total=${chatgptNames.length}`;
-const chatgpt = read("docs/CHATGPT-PLUGIN.md");
-if (!chatgpt.includes(`<!-- mcp-chatgpt-profile: ${profileMarker} -->`)) fail.push(`docs/CHATGPT-PLUGIN.md: ChatGPT profile marker stale; expected ${profileMarker}`);
-for (const name of chatgptModelTools.keys()) if (!chatgpt.includes(`\`${name}\``)) fail.push(`docs/CHATGPT-PLUGIN.md: ChatGPT profile tool ${name} is not documented`);
-const scopeOrder = ["read", "write", "exec"];
-for (let i = 0; i < scopeOrder.length; i += 1) {
- const scope = scopeOrder[i];
- const next = scopeOrder[i + 1];
- const expected = [...chatgptModelTools].filter(([, value]) => value === scope).map(([name]) => name).sort();
- const heading = scope === "read"
- ? `### \`read\` — ${expected.length} ChatGPT model tools`
- : `### \`${scope}\` — + ${expected.length} ChatGPT model tools`;
- if (!chatgpt.includes(heading)) fail.push(`docs/CHATGPT-PLUGIN.md: stale ${scope} profile heading; expected ${heading}`);
- const start = chatgpt.indexOf(`### \`${scope}\` —`);
- const end = next ? chatgpt.indexOf(`### \`${next}\` —`, start + 1) : chatgpt.indexOf("\n### App-only ChatGPT bridge", start + 1);
- if (start < 0 || end < 0) { fail.push(`docs/CHATGPT-PLUGIN.md: could not parse ${scope} profile block`); continue; }
- const actual = [...chatgpt.slice(start, end).matchAll(/^- \`([^\`]+)\`/gm)].map((match) => match[1]).sort();
- if (actual.join("\n") !== expected.join("\n")) fail.push(`docs/CHATGPT-PLUGIN.md: ${scope} ChatGPT profile list differs from source contract`);
-}
+const generated = spawnSync(process.execPath, [join(ROOT, "scripts/gen-mcp-catalog.mjs"), "--check"], { cwd: ROOT, encoding: "utf8" });
+if (generated.status !== 0) fail.push((generated.stderr || generated.stdout || "docs/generated/MCP-CATALOG.md is stale").trim());
-// MCP.md's scope table must match source membership exactly.
-const mcpDoc = read("docs/MCP.md");
-for (const scope of scopeOrder) {
- const expected = [...documentedTools].filter(([, value]) => value === scope).map(([name]) => name).sort();
- const row = mcpDoc.split("\n").find((line) => line.startsWith(`| \`${scope}\` |`));
- if (!row) { fail.push(`docs/MCP.md: missing ${scope} scope row`); continue; }
- const actual = [...row.matchAll(/`([^`]+)`/g)].map((match) => match[1]).filter((name) => name !== scope).sort();
- if (actual.join("\n") !== expected.join("\n")) fail.push(`docs/MCP.md: ${scope} scope row differs from source catalog`);
+const catalogRefs = new Map([
+ ["docs/MCP.md", "./generated/MCP-CATALOG.md"],
+ ["docs/CHATGPT-PLUGIN.md", "./generated/MCP-CATALOG.md"],
+ ["docs/ARCHITECTURE.md", "./generated/MCP-CATALOG.md"],
+ ["CLAUDE.md", "./docs/generated/MCP-CATALOG.md"],
+]);
+for (const [file, ref] of catalogRefs) {
+ const text = read(file);
+ if (!text.includes(ref)) fail.push(`${file}: must reference the generated MCP catalog (${ref})`);
+ if (text.includes("<!-- mcp-toolset:") || text.includes("<!-- mcp-chatgpt-profile:"))
+ fail.push(`${file}: duplicated MCP catalog marker; keep volatile markers only in docs/generated/MCP-CATALOG.md`);
}
// --- Slice catalog counts.
@@ -188,4 +105,4 @@ if (fail.length) {
for (const item of fail) console.error(`- ${item}`);
process.exit(1);
}
-console.log(`docs: current — ${markdown.length} markdown files, ${documentedTools.size} model MCP tools + ${appOnlyTools.size} app-only bridge, ${sliceCount} slices, ${featureCount} AppShell feature dirs`);
+console.log(`docs: current — ${markdown.length} markdown files, full ${catalog.modelCount}+${catalog.appOnly.length} app-only MCP tools, ChatGPT ${catalog.chatgpt.modelCount}+${catalog.chatgpt.appOnly.length} app-only, ${sliceCount} slices, ${featureCount} AppShell feature dirs`);
diff --git a/scripts/gen-mcp-catalog.mjs b/scripts/gen-mcp-catalog.mjs
new file mode 100755
index 00000000..c83ec29a
--- /dev/null
+++ b/scripts/gen-mcp-catalog.mjs
@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { collectMcpCatalog, renderMcpCatalogMarkdown } from "./lib/mcp-catalog.mjs";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const OUT = join(ROOT, "docs/generated/MCP-CATALOG.md");
+const catalog = collectMcpCatalog(ROOT);
+const errors = [
+ ...catalog.orphanModules.map((name) => `orphan MCP tool module: lib/mcp/${name}`),
+ ...catalog.missingModules.map((name) => `missing MCP tool module: lib/mcp/${name}`),
+ ...catalog.profileMissing.map((name) => `ChatGPT profile references missing MCP tool: ${name}`),
+];
+if (errors.length) { for (const error of errors) console.error(error); process.exit(1); }
+const expected = renderMcpCatalogMarkdown(catalog);
+if (process.argv.includes("--check")) {
+ const actual = existsSync(OUT) ? readFileSync(OUT, "utf8") : "";
+ if (actual !== expected) { console.error("generated MCP catalog is stale; run: node scripts/gen-mcp-catalog.mjs"); process.exit(1); }
+ console.log(`mcp-catalog: current — full ${catalog.transportCount}/${catalog.modelCount}; ChatGPT ${catalog.chatgpt.transportCount}/${catalog.chatgpt.modelCount}`);
+ process.exit(0);
+}
+mkdirSync(dirname(OUT), { recursive: true });
+writeFileSync(OUT, expected);
+console.log(`wrote ${OUT}`);
diff --git a/scripts/lib/mcp-catalog.mjs b/scripts/lib/mcp-catalog.mjs
new file mode 100644
index 00000000..90e019b9
--- /dev/null
+++ b/scripts/lib/mcp-catalog.mjs
@@ -0,0 +1,146 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+export const APP_ONLY_MCP_TOOLS = new Set(["workflow_status"]);
+const TOOL_MODULE_NAME = /^tools-[A-Za-z0-9-]+\.ts$/;
+const SCOPES = ["read", "write", "exec"];
+
+const splitByScope = (rows) => {
+ const byScope = { read: [], write: [], exec: [] };
+ for (const [name, scope] of rows) byScope[scope].push(name);
+ for (const scope of SCOPES) byScope[scope].sort();
+ return byScope;
+};
+const countsFor = (byScope) => Object.fromEntries(SCOPES.map((scope) => [scope, byScope[scope].length]));
+
+export function collectMcpCatalog(root) {
+ const read = (rel) => readFileSync(join(root, rel), "utf8");
+ const toolset = read("lib/mcp/toolset.ts");
+ const serverVersion = /MCP_SERVER_VERSION\s*=\s*"([^"]+)"/.exec(toolset)?.[1];
+ const version = /MCP_TOOLSET_VERSION\s*=\s*"([^"]+)"/.exec(toolset)?.[1];
+ const changedAt = /MCP_TOOLSET_CHANGED_AT\s*=\s*"([^"]+)"/.exec(toolset)?.[1];
+ if (!serverVersion || !version || !changedAt) throw new Error("could not parse MCP toolset constants");
+
+ const discoveredModules = readdirSync(join(root, "lib/mcp")).filter((name) => TOOL_MODULE_NAME.test(name)).sort();
+ const reachable = new Set();
+ const pending = ["tools.ts"];
+ while (pending.length) {
+ const name = pending.pop();
+ if (!name || reachable.has(name)) continue;
+ reachable.add(name);
+ const text = read(`lib/mcp/${name}`);
+ for (const match of text.matchAll(/from\s+["']\.\/(tools-[A-Za-z0-9-]+)["']/g)) {
+ const child = `${match[1]}.ts`;
+ if (!reachable.has(child)) pending.push(child);
+ }
+ }
+ const orphanModules = discoveredModules.filter((name) => !reachable.has(name));
+ const missingModules = [...reachable].filter((name) => name !== "tools.ts" && !discoveredModules.includes(name));
+
+ const all = new Map();
+ for (const file of [...reachable].sort().map((name) => `lib/mcp/${name}`)) {
+ const text = read(file);
+ for (const match of text.matchAll(/name:\s*"([^"]+)"[\s\S]*?scope:\s*"(read|write|exec)"/g)) all.set(match[1], match[2]);
+ }
+
+ const appOnly = [...APP_ONLY_MCP_TOOLS].filter((name) => all.has(name)).sort();
+ const model = [...all].filter(([name]) => !APP_ONLY_MCP_TOOLS.has(name));
+ const byScope = splitByScope(model);
+
+ const toolContract = read("lib/mcp/tool-contract.ts");
+ const profileBlock = /CHATGPT_TOOL_NAMES\s*=\s*new Set\(\[([\s\S]*?)\]\s*as const\)/.exec(toolContract)?.[1] ?? "";
+ const chatgptNames = [...profileBlock.matchAll(/"([^"]+)"/g)].map((match) => match[1]);
+ const profileMissing = chatgptNames.filter((name) => !all.has(name));
+ const chatgptAppOnly = chatgptNames.filter((name) => APP_ONLY_MCP_TOOLS.has(name) && all.has(name)).sort();
+ const chatgptModel = chatgptNames.filter((name) => !APP_ONLY_MCP_TOOLS.has(name) && all.has(name)).map((name) => [name, all.get(name)]);
+ const chatgptByScope = splitByScope(chatgptModel);
+
+ return {
+ serverVersion, version, changedAt, all, model, byScope, appOnly,
+ transportCount: all.size,
+ modelCount: model.length,
+ counts: countsFor(byScope),
+ chatgpt: {
+ names: chatgptNames,
+ model: chatgptModel,
+ byScope: chatgptByScope,
+ appOnly: chatgptAppOnly,
+ transportCount: chatgptNames.filter((name) => all.has(name)).length,
+ modelCount: chatgptModel.length,
+ counts: countsFor(chatgptByScope),
+ },
+ orphanModules, missingModules, profileMissing,
+ };
+}
+
+export function renderMcpCatalogMarkdown(catalog) {
+ const list = (rows) => rows.map((name) => `- \`${name}\``).join("\n") || "- none";
+ const c = catalog.chatgpt;
+ return `# Generated MCP catalog
+
+> **Generated file — do not edit manually.** Source of truth: \`lib/mcp/tools.ts\`, its registered \`tools-*\` modules, \`lib/mcp/toolset.ts\`, and the compact ChatGPT name set in \`lib/mcp/tool-contract.ts\`. Regenerate with \`node scripts/gen-mcp-catalog.mjs\`. The live deployed authority remains \`GET /mcp\`.
+
+## Full MSO catalog
+
+<!-- mcp-toolset: server=${catalog.serverVersion} version=${catalog.version} tools=${catalog.modelCount} read=${catalog.counts.read} write=${catalog.counts.write} exec=${catalog.counts.exec} -->
+
+| Fact | Current source value |
+|---|---:|
+| MCP server | \`${catalog.serverVersion}\` |
+| Toolset | \`${catalog.version}\` |
+| Toolset changed at | \`${catalog.changedAt}\` |
+| Transport tools | **${catalog.transportCount}** |
+| Model/operator tools | **${catalog.modelCount}** |
+| Read | **${catalog.counts.read}** |
+| Write | **${catalog.counts.write}** |
+| Exec | **${catalog.counts.exec}** |
+| App-only bridges | **${catalog.appOnly.length}** |
+
+### Read (${catalog.counts.read})
+
+${list(catalog.byScope.read)}
+
+### Write (${catalog.counts.write})
+
+${list(catalog.byScope.write)}
+
+### Exec (${catalog.counts.exec})
+
+${list(catalog.byScope.exec)}
+
+### App-only bridges (${catalog.appOnly.length})
+
+${list(catalog.appOnly)}
+
+## ChatGPT static profile
+
+<!-- mcp-chatgpt-profile: server=${catalog.serverVersion} version=${catalog.version} tools=${c.modelCount} read=${c.counts.read} write=${c.counts.write} exec=${c.counts.exec} app-only=${c.appOnly.length} total=${c.transportCount} -->
+
+The ChatGPT profile is a fail-closed static projection defined by \`CHATGPT_TOOL_NAMES\`. OAuth scope is still enforced independently; project-owned MCP tool names remain dynamic data behind the generic project bridge.
+
+| Fact | Current source value |
+|---|---:|
+| ChatGPT transport tools | **${c.transportCount}** |
+| ChatGPT model/operator tools | **${c.modelCount}** |
+| Read | **${c.counts.read}** |
+| Write | **${c.counts.write}** |
+| Exec | **${c.counts.exec}** |
+| App-only bridges | **${c.appOnly.length}** |
+
+### ChatGPT read (${c.counts.read})
+
+${list(c.byScope.read)}
+
+### ChatGPT write (${c.counts.write})
+
+${list(c.byScope.write)}
+
+### ChatGPT exec (${c.counts.exec})
+
+${list(c.byScope.exec)}
+
+### ChatGPT app-only bridges (${c.appOnly.length})
+
+${list(c.appOnly)}
+`;
+}