Skip to content

Commit f374810

Browse files
authored
feat(preflight): required-tools preflight — deterministic availability check with reason taxonomy (spec 098) (#996)
Related #969 Implements item 3 of #969 (the reporter-confirmed shape: cron/CI-first, REST+CLI, stat-only): a deterministic, side-effect-free availability check for a caller-supplied list of tool IDs, answering per-ID with a machine-readable reason instead of failing silently at discovery time. Lands on top of #995 (baseline counters), which shipped one release ahead per the Phase-0 decision. ## What - **`POST /api/v1/preflight`** — `{tools:[{id, pin_hash?}], profile?, policy?, wait_ms?}` → per-ID verdicts. HTTP 200 whenever the check executed (the verdict is data); 400 validation / 503 runtime-or-persistence failure. Standard `APIResponse` envelope. - **`mcpproxy tools preflight`** — typed exit codes `0` ready · `10` retryable (backoff) · `11` blocked (page operator) · `12` unknown ID (fix manifest); worst class wins. A cron wrapper branches without parsing JSON. - **One shared eligibility evaluator** (`internal/preflight`): closed 15-code reason taxonomy with a fixed precedence chain; existence = index ∨ approval record (the runtime de-indexes blocked/pending/changed tools — index absence alone proves nothing); zero upstream I/O and zero runtime mutation, structurally (the evaluator cannot reach a transport; asserted by instrumented-transport + state-snapshot tests). - **Four-path dispatch consolidation** (FR-002 no-skew): call_tool variants, direct mode, code_execution and stored scripts all consume the same gate. Notable hardening: **scripts previously enforced no per-tool policy at all** — a code_execution/stored script could call a quarantined tool; now refused like every other path. - **Transparency**: every executed preflight writes a durable activity record (synchronous, before the 200 — persistence failure ⇒ 503), request-ID-correlated and browsable via `mcpproxy activity list --request-id …` and the Web UI. - **Disclosure tiers**: operator (API key/socket/pipe) gets full diagnosis incl. `sha256/v{N}:{hex}` hash pins; agent tokens get scope-silence (out-of-scope, unconfigured — byte-indistinguishable `not_found`; no hashes; `did_you_mean` never crosses scope). Stale token ProfilePin now intersects to deny-all. - **Zero MCP-surface change**: `tools/list` byte-identical to merge-base across all three routing modes (golden-snapshot test, goldens captured from origin/main). ## Verification - **Sabotage E2E matrix** (`testdata/preflight_sabotage_matrix.json`): 23 scenario cells against a real binary + live fixture upstreams — quarantine flip, rug-pull drift, block, config-deny, disable, SIGSTOP/kill, mid-indexing, annotation cells per filter, unknown id/server, hash + schema-version mismatch, PendingAuth, profile scope at both tiers — each asserting exact {reason, retryable, action} + the activity record by request ID; a reflection test forbids enum codes without a cell. - Full gates: `go test -race ./...` (79 pkgs), server-edition build/tests/lint, 65/65 API E2E, golangci v2 both tag sets, swagger + generate-types idempotent, frontend build + 605 unit tests. - code_execution + stored scripts: byte-identical transcripts vs main on a 9-probe harness; live no-skew check across all four dispatch paths. ## Review Spec, plan, and full diff cross-model reviewed (opencode / gpt-5.6-sol): spec 3 rounds → APPROVE; plan 25 findings (12 P1) incorporated → APPROVE; code round 1 = 11 findings (6 P1, all genuine, each fix verified by restoring the old code), round 2 = 1 regression (startup-window 503 → `server_initializing`), round 3 → **APPROVE**. ## Docs New `docs/features/tools-preflight.md` (taxonomy, precedence, tiers, transparency, cron/GHA/n8n recipes, code-exec composition), REST + CLI references, README "How AI Agents Work Through MCPProxy" section with a preflight-gated automation example. Known follow-up (deliberately out of scope, pre-existing): `resolveActiveProfile` warn-skips a stale ProfilePin on the live session path — preflight is now stricter than dispatch there; the session path deserves its own reviewed fix.
1 parent a3a5e5b commit f374810

95 files changed

Lines changed: 14642 additions & 200 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitattributes‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,12 @@ internal/server/testdata/*.golden.json text eol=lf
1919
# comparisons fail with a trailing \r.
2020
internal/server/testdata/**/*.golden.json text eol=lf
2121

22+
# Spec 098 tools/list merge-base snapshots (FR-015 byte-identity): these are
23+
# plain .json (not *.golden.json), so the patterns above do not reach them.
24+
# Without this Windows checks out CRLF and all three
25+
# TestToolsListSnapshot_MatchesMergeBaseGoldens surfaces fail on \r alone.
26+
internal/server/testdata/toolslist_goldens/*.json text eol=lf
27+
2228
# Self-contained verification/QA reports embed base64 PNG screenshots, so a
2329
# single file is multiple MB of "HTML". They are point-in-time artifacts, not
2430
# source. Mark them linguist-generated so GitHub's language stats reflect the

‎CLAUDE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,6 @@ tail -f ~/Library/Logs/mcpproxy/main.log # main log (macOS; Linux: ~/.mcpproxy/
158158
- **Windows installer**: [docs/github-actions-windows-wix-research.md](docs/github-actions-windows-wix-research.md). **Prerelease** (`next` branch + `v*-rc.*` tags, opt-in, off stable channels): [docs/prerelease-builds.md](docs/prerelease-builds.md).
159159

160160
## Recent Changes
161+
- 098-tools-preflight: Added Go 1.24 module toolchain (repo builds with local Go 1.25) + existing only — chi (httpapi), bbolt (storage), Bleve (index), zap (logging), Cobra (CLI), swaggo/swag v2 (contract regen). **No new dependencies.**
161162
- 097-stored-scripts: Added Go 1.25 (os.Root/Root.ReadFile available — R1) + stdlib only (os.Root). **No new dependencies.**
162163
- 096-batched-call-tools: Added Go 1.24 module toolchain (repo builds with local Go 1.25) + existing only — goja (sandbox), mark3labs/mcp-go (tool surface), zap. **No new dependencies.**
163-
- 095-update-failure-ux: Added Swift 5.9 (tray, AppKit + Sparkle 2.9.3 vendored via SwiftPM) · Go 1.24 module toolchain (repo builds with local Go 1.25) + existing only — Sparkle 2.9.3 (`SPUUpdater`, `SPUStandardUserDriver`), chi (httpapi), bbolt (diagnostics counters), swaggo/swag v2 (contract regen). **No new dependencies.**

‎README.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,72 @@ See [Configuration](https://docs.mcpproxy.app/configuration/config-file/) and [U
181181

182182
---
183183

184+
## How AI Agents Work Through MCPProxy
185+
186+
Once connected, your agent sees a handful of built-in MCPProxy tools instead of hundreds of upstream schemas. A typical session has three beats — discover, call, audit — plus an optional preflight gate for unattended automations.
187+
188+
### 1. Discover — spend one query, not your context window
189+
190+
The agent asks for what it needs in plain keywords via `retrieve_tools`:
191+
192+
```json
193+
{ "query": "create github issue", "limit": 5 }
194+
```
195+
196+
MCPProxy runs a BM25 search across every connected server and returns only the top-ranked matches — each with a `call_with` hint recommending the right call variant for its annotations:
197+
198+
```json
199+
{
200+
"tools": [
201+
{ "name": "github:create_issue", "score": 0.89, "call_with": "call_tool_write" },
202+
{ "name": "gitlab:create_issue", "score": 0.72, "call_with": "call_tool_write" }
203+
]
204+
}
205+
```
206+
207+
This is where the token savings come from: the schemas of the hundreds of tools the agent *didn't* need never enter its context. The agent loads full schemas on demand with `describe_tool` (batch up to 5 ids) only for the tools it's about to use.
208+
209+
### 2. Call — with declared intent
210+
211+
The agent executes the tool through the variant matching its intent (`call_tool_read`, `call_tool_write`, or `call_tool_destructive`), addressing it as `server:tool`:
212+
213+
```json
214+
{
215+
"name": "github:create_issue",
216+
"args_json": "{\"repo\": \"acme/api\", \"title\": \"Bug report\"}",
217+
"intent": { "operation_type": "write", "reason": "Filing bug per user request" }
218+
}
219+
```
220+
221+
MCPProxy validates the intent against the tool's annotations (a "read" call can't reach a destructive tool), checks quarantine and approval state, and scans arguments and responses for sensitive data before anything leaves the machine.
222+
223+
### 3. Audit — every call is on the record
224+
225+
Every call lands in the local [Activity Log](https://docs.mcpproxy.app/features/activity-log/) with a request ID, so you can reconstruct exactly what an agent did:
226+
227+
```bash
228+
mcpproxy activity list # everything, newest first
229+
mcpproxy activity list --request-id <id> # one workflow, correlated
230+
```
231+
232+
### Gate automations before they burn tokens
233+
234+
For recurring headless jobs (cron, CI, n8n), don't let the agent discover a missing tool the expensive way. One preflight command checks that every required tool is ready — without contacting any upstream server — and reports exactly why when it isn't (server quarantined, tool changed since approval, OAuth expired, typo'd id):
235+
236+
```bash
237+
mcpproxy tools preflight gh-ops:sync_issues slack:post_message --wait 10s
238+
case $? in
239+
0) run-agent-session ;; # all ready — go
240+
10) exit 75 ;; # transient (server starting) — let the next cron tick retry
241+
11) page-operator ;; # blocked — someone must approve / enable / log in
242+
12) fail-pipeline ;; # unknown tool id — the automation itself is misconfigured
243+
esac
244+
```
245+
246+
See [Required-Tools Preflight](https://docs.mcpproxy.app/features/tools-preflight/) for the full reason taxonomy, REST endpoint, and GitHub Actions / n8n recipes.
247+
248+
---
249+
184250
## 🔐 Optional HTTPS Setup
185251

186252
MCPProxy works with HTTP by default for easy setup. HTTPS is optional and primarily useful for production environments or when stricter security is required.
@@ -295,6 +361,7 @@ curl -k https://localhost:8080/api/v1/status
295361
- [OAuth Authentication](https://docs.mcpproxy.app/features/oauth-authentication/)
296362
- [Code Execution](https://docs.mcpproxy.app/features/code-execution/)
297363
- [Activity Log](https://docs.mcpproxy.app/features/activity-log/)
364+
- [Required-Tools Preflight](https://docs.mcpproxy.app/features/tools-preflight/)
298365
- [Agent Tokens](https://docs.mcpproxy.app/features/agent-tokens/)
299366
- [Sensitive Data Detection](https://docs.mcpproxy.app/features/sensitive-data-detection/)
300367

‎ROADMAP.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -799,3 +799,4 @@ Legend: `shipped` ≥95% checked · `in-flight` 1–94% · `drafted` 0% · `—`
799799
| [095-update-failure-ux](./specs/095-update-failure-ux/) | `shipped` | 28/28 (100%) |
800800
| [096-batched-call-tools](./specs/096-batched-call-tools/) | `in-flight` | 15/16 (94%) |
801801
| [097-stored-scripts](./specs/097-stored-scripts/) | `in-flight` | 13/14 (93%) |
802+
| [098-tools-preflight](./specs/098-tools-preflight/) | `drafted` | 0/33 (0%) |

‎cmd/generate-types/main.go‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,90 @@ export type RejectionReason = 'queue_full' | 'queue_timeout';
114114
/** Limiter tier that shed the call (activity metadata rejection_scope). */
115115
export type RejectionScope = 'server' | 'global';
116116
117+
`)
118+
119+
// Required-tools preflight (Spec 098) - generated from internal/contracts/types.go,
120+
// which mirrors internal/preflight/reasons.go (the single source of truth for
121+
// the taxonomy). A drift test in internal/preflight keeps the two identical.
122+
sb.WriteString(`// Preflight (Spec 098) - generated from internal/contracts/types.go
123+
export const PreflightStatusReady = 'ready' as const;
124+
export const PreflightStatusUnavailable = 'unavailable' as const;
125+
export type PreflightStatus = typeof PreflightStatusReady | typeof PreflightStatusUnavailable;
126+
127+
/**
128+
* Closed 15-code failure enum. Additive-only: treat an unknown code as
129+
* non-retryable. 'server_saturated' is reserved and not emitted.
130+
*/
131+
export type PreflightReason =
132+
| 'server_initializing'
133+
| 'server_unhealthy'
134+
| 'server_disabled'
135+
| 'server_quarantined'
136+
| 'tool_pending_approval'
137+
| 'tool_changed'
138+
| 'tool_blocked_by_user'
139+
| 'oauth_required'
140+
| 'hash_mismatch'
141+
| 'server_not_in_scope'
142+
| 'tool_denied_by_config'
143+
| 'missing_annotation'
144+
| 'policy_filtered'
145+
| 'not_found'
146+
| 'server_not_configured';
147+
148+
/** Set-level aggregate (worst class present); drives the CLI exit code 0/10/11/12. */
149+
export const PreflightVerdictReady = 'ready' as const;
150+
export const PreflightVerdictDegradedRetryable = 'degraded_retryable' as const;
151+
export const PreflightVerdictBlocked = 'blocked' as const;
152+
export const PreflightVerdictUnknownIds = 'unknown_ids' as const;
153+
export type PreflightVerdict =
154+
| typeof PreflightVerdictReady
155+
| typeof PreflightVerdictDegradedRetryable
156+
| typeof PreflightVerdictBlocked
157+
| typeof PreflightVerdictUnknownIds;
158+
159+
export interface PreflightToolRef {
160+
id: string;
161+
/** "sha256/v{N}:{hex}" - the schema version distinguishes a proxy hash bump from upstream drift. */
162+
pin_hash?: string;
163+
}
164+
165+
export interface PreflightPolicy {
166+
read_only_only?: boolean;
167+
exclude_destructive?: boolean;
168+
exclude_open_world?: boolean;
169+
}
170+
171+
export interface PreflightRequest {
172+
tools: PreflightToolRef[];
173+
profile?: string;
174+
policy?: PreflightPolicy;
175+
wait_ms?: number;
176+
}
177+
178+
export interface PreflightToolResult {
179+
id: string;
180+
status: PreflightStatus;
181+
/** Present only when status is 'unavailable'. */
182+
reason?: PreflightReason;
183+
retryable?: boolean;
184+
/** Health-action vocabulary; omitted (not 'none') when the reason has no action. */
185+
action?: HealthAction;
186+
detail?: string;
187+
remediation?: string;
188+
/** Operator tier + ready results only; never disclosed to an agent token. */
189+
hash?: string;
190+
/** Up to 3 nearest caller-visible ids, on not_found only. */
191+
did_you_mean?: string[];
192+
}
193+
194+
export interface PreflightResponse {
195+
verdict: PreflightVerdict;
196+
checked_at: string; // RFC3339
197+
waited_ms?: number;
198+
tools: PreflightToolResult[];
199+
}
200+
117201
`)
118202

119203
// Server types
@@ -241,6 +325,10 @@ export interface IsolationDefaults {
241325
held_reason?: string;
242326
held_verdict?: string;
243327
held_signals?: string[];
328+
// The tool's current hash in the preflight pin format "sha256/v{N}:{hex}"
329+
// (spec 098 FR-011) — the value to paste into a preflight pin. Operator tier
330+
// only: absent for agent-token callers and for tools with no stored hash.
331+
hash?: string;
244332
}
245333
246334
export interface SearchResult {

0 commit comments

Comments
 (0)