feat(mcp): add optional fields projection to five tool outputs

.claude/context/linear.md

@@ -50,6 +50,17 @@ Selector rules:
 - `--query` matches a title substring. `--updated-after` needs RFC3339 and is rejected before any request when malformed.
 - Issue update `--state` names resolve from the issue identifier team (`GUZ-22` → `GUZ`). `--team` overrides. UUID issue ids still need `--team` or a state UUID.
 
+### Chart
+
+```bash
+# Render an HTML Mermaid chart of issues, sub-issues, and blockers, then open it
+mcptools linear chart GUZ-185 GUZ-186 GUZ-188
+mcptools linear chart GUZ-185 --out /tmp/linear-chart.html
+mcptools linear chart GUZ-185 --no-open
+```
+
+`chart` walks the transitive closure of children and `blocked_by` blockers (cap 300 issues, warning on the cap), drops canceled issues, and classifies the rest as complete, in progress, frontier (ready to start), or fog (prerequisite incomplete). Output defaults to `<temp dir>/mcptools-linear-chart.html`. Empty issue ids reject before any request.
+
 ### Discovery
 
 ```bash

.claude/context/mcp-server.md

@@ -20,6 +20,9 @@ mcptools mcp sse --port 3000 --host 127.0.0.1
 
 For web-based clients using Server-Sent Events over HTTP.
 
+mcptools mcp catalog # Print the compact tool catalog (domain, name, summary)
+mcptools mcp declarations [NAME...] # Print TypeScript declarations for named tools (all tools without names)
+
 ## Claude Desktop Configuration
 
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
@@ -131,6 +134,109 @@ Or manually add to `~/Library/Application Support/Claude/claude_code_config.json
 | `ui_annotations_resolve` | Mark annotation as resolved |
 | `ui_annotations_clear` | Clear all annotations |
 
+### Find tools
+
+| Tool | Description |
+|------|-------------|
+| `find_tools` | Ranks registered tools for a task description. Returns `none` score, `tools` list with a TypeScript `declaration` per tool, `backend` ("local" or "jev"), optional `fallback` ("unreachable" | "http_status" | "invalid_response" | "invalid_config"), and `usage`. |
+
+`find_tools` is advisory: it never dispatches a tool, and a Jev outage never blocks the caller.
+
+**Jev environment variables**
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `JEV_PROVIDER` | unset | `opencode`, `openrouter`, `vercel` or `typesafe` to enable Jev classifier |
+| `JEV_ENDPOINT` | provider preset | Override endpoint URL |
+| `JEV_MODEL` | provider preset | Override model name |
+| `JEV_API_KEY` | (none) | API key; falls back to the provider's conventional key var |
+| `OPENCODE_API_KEY` | - | Conventional key var when `JEV_PROVIDER=opencode` |
+| `OPENROUTER_API_KEY` | - | Conventional key var when `JEV_PROVIDER=openrouter` |
+| `AI_GATEWAY_API_KEY` | - | Conventional key var when `JEV_PROVIDER=vercel` |
+| `TYPESAFE_API_KEY` | - | Conventional key var when `JEV_PROVIDER=typesafe` |
+
+### Execute
+
+| Tool | Description |
+|------|-------------|
+| `execute` | Run JavaScript in a sandbox that binds the tools `find_tools` returns |
+
+Inputs:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `code` | string | (required) | JavaScript to run; the final expression or top-level `return` value becomes `result` |
+| `allowWrites` | boolean | `false` | Also bind tools of kind Write |
+| `allowSpend` | boolean | `false` | Also bind tools of kind Spend |
+
+Result shape, the `structuredContent` object:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `logs` | string[] | Lines captured from `console.log` up to the failure point |
+| `result` | any | Final expression or top-level return value; `null` when `error` is set |
+| `error` | object \| null | `null` on success; otherwise `{message, name}` |
+
+The envelope carries `isError: true` exactly when `error` is non-null. On
+failure `result` is `null` and `logs` still holds the lines printed before the
+failure.
+
+Error names:
+
+- `TimeoutError` — the run exceeded `--execute-timeout-secs`
+- `OutputLimitError` — the logs and result exceeded `--execute-output-kb`
+- JavaScript error names pass through unchanged (`TypeError`, `Error`, and so
+  on); memory exhaustion surfaces as `InternalError`
+
+Flag gating is by tool kind only: read tools bind by default, `allowWrites`
+adds write tools, `allowSpend` adds spend tools, and `execute` never binds as
+a global inside its own sandbox. A missing gated tool rejects with a
+`ReferenceError` whose message names the tool, its kind, and the flag to pass
+(e.g. `jira_update is a write tool; pass allowWrites: true to execute`); any
+other missing global keeps QuickJS's plain `<name> is not defined` message.
+
+Limits come from the server flags `--execute-timeout-secs` (default 30),
+`--execute-memory-mb` (default 64), and `--execute-output-kb` (default 256).
+
+## Agent loop
+
+1. Call `find_tools` with a task that names the system (e.g. "mark the Jira ticket done", not "mark it done").
+2. Read the returned `declaration` on the tool(s) of interest.
+3. Call the tool by name through `tools/call`.
+4. For a same-domain follow-up (e.g. `jira_comment_list` then `jira_comment_update`), call the follow-up tool directly; do not call `find_tools` again.
+5. `find_tools` is advisory: it never dispatches a tool, and Jev is consulted only inside `find_tools` itself, never in front of or around any other tool call.
+6. In discovery mode the loop needs a host that can call a tool absent from `tools/list` — see the Known limitation in [Discovery mode](#discovery-mode) below; this section restates none of that text.
+
+## Discovery mode
+
+Enable with the `--discovery` flag or the `MCPTOOLS_DISCOVERY` environment
+variable. Env values are case-insensitive booleans: `y`, `yes`, `t`, `true`,
+`on`, `1` enable the mode; `n`, `no`, `f`, `false`, `off`, `0` keep it off;
+any other value, including an empty one, exits with code 2 and the error
+`value was not a boolean`. In this mode `tools/list` returns exactly one tool,
+`find_tools`; `tools/call` still dispatches every real tool by name. Without
+this mode, hosts load all 63 schemas and Jev saves no context.
+
+Known limitation, planned and undesigned: hosts that declare only listed
+tools to the model, such as Claude Code, cannot yet call a tool directly
+when it is absent from `tools/list`. The returned declarations name the
+tools/call arguments and results of every tool they carry. Code mode closes
+this gap in practice: `tools/list` returns `execute` beside `find_tools`, and
+tools bind inside `execute` as async globals, under the flag gating
+documented in [Execute](#execute) above.
+
+## Code mode
+
+Enable with the `--code-mode` flag or the `MCPTOOLS_CODE_MODE` environment
+variable, with the same accepted values as `MCPTOOLS_DISCOVERY`. In this mode
+`tools/list` returns exactly two tools, in order: `find_tools`, then
+`execute`. Code mode wins over Discovery mode when both are enabled.
+`tools/call` still dispatches every real tool by name. The `find_tools`
+response `usage` field, also for nested `find_tools` calls inside `execute`,
+is `Call each declared function as an async global inside execute.`; other
+modes keep `Each declaration is the call signature: the input interface is
+the tools/call arguments object, the Promise type is the result.`
+
 ## Testing with curl
 
 ```bash

.claude/context/testing.md

@@ -7,6 +7,8 @@ All CLI arguments can be provided via environment variables, useful for scriptin
 | Variable | Description |
 |----------|-------------|
 | `MCPTOOLS_VERBOSE` | Enable verbose output (default: false) |
+| `MCPTOOLS_DISCOVERY` | List only `find_tools` via `tools/list`. Accepts `y`, `yes`, `t`, `true`, `on`, `1` (on) and `n`, `no`, `f`, `false`, `off`, `0` (off), any case; other values exit 2 (default: false) |
+| `MCPTOOLS_CODE_MODE` | List `find_tools,execute` via `tools/list`; wins over `MCPTOOLS_DISCOVERY`. Same accepted values, other values exit 2 (default: false) |
 
 ## Atlassian Variables
 
@@ -83,6 +85,33 @@ All CLI arguments can be provided via environment variables, useful for scriptin
 | `OPENAI_API_KEY` | Key for `--api openai` |
 | `OPENAI_BASE_URL` | Base URL for `--api openai` (default: `https://api.openai.com/v1`) |
 
+## Jev Variables
+
+| Variable | Description |
+|----------|-------------|
+| `JEV_PROVIDER` | `opencode`, `openrouter`, `vercel` or `typesafe` to enable Jev (unset selects local) |
+| `JEV_ENDPOINT` | Override gateway endpoint (defaults from provider) |
+| `JEV_MODEL` | Override model (defaults from provider) |
+| `JEV_API_KEY` | API key (falls back to the provider's conventional variable) |
+| `OPENCODE_API_KEY` | Key used by `opencode` preset |
+| `OPENROUTER_API_KEY` | Key used by `openrouter` preset |
+| `AI_GATEWAY_API_KEY` | Key used by `vercel` preset |
+| `TYPESAFE_API_KEY` | Key used by `typesafe` preset |
+
+On `jev-1.13-free` the full 61-tool catalog plus `none` returns in under 1.2 s per call. `none` separates in-scope from out-of-scope tasks except for one near-miss. The 0.05-floor selection rule matches the live probabilities for every query the spike ran. This covers the `opencode` preset only; other presets are unverified beyond gateway documentation.
+
+Live run against the `opencode` preset, one row per query (`JEV_PROVIDER=opencode`, `-k 5`, timed per call):
+
+| task | backend | fallback | none | tools | latency |
+|------|---------|----------|------|-------|---------|
+| `mark the ticket done` | `jev` | — | 0.01 | `jira_update`, `linear_issue_update` | 1.2 s |
+| `table of contents of this pdf` | `jev` | — | 0.0 | `pdf_toc` | 1.4 s |
+| `table of contents of this web page` | `jev` | — | 0.0 | `md_toc` | 1.2 s |
+| `update the jira comment I just listed` | `jev` | — | 0.0 | `jira_comment_update` | 1.2 s |
+| `jira_comment_update` | `jev` | — | 0.0 | `jira_comment_update` | 1.9 s |
+| `pdf_toc` | `jev` | — | 0.0 | `pdf_toc` | 1.1 s |
+| `book a flight to Paris` | `jev` | — | 1.0 | — | 1.1 s |
+
 ## Usage Examples
 
 ### Scripting

CLAUDE.md

@@ -60,6 +60,19 @@ export ATLASSIAN_API_TOKEN="your-api-token"
 | `ATLAS_FILE_MODEL` | `gpt-5.6-luna` | Model for file descriptions |
 | `ATLAS_DIR_MODEL` | `gpt-5.6-luna` | Model for directory descriptions |
 
+**Jev**
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `JEV_PROVIDER` | unset | `opencode`, `openrouter`, `vercel` or `typesafe` to enable Jev classifier |
+| `JEV_ENDPOINT` | provider preset | Override endpoint URL |
+| `JEV_MODEL` | provider preset | Override model name |
+| `JEV_API_KEY` | (none) | API key; falls back to the provider's conventional key var |
+| `OPENCODE_API_KEY` | - | Conventional key var when `JEV_PROVIDER=opencode` |
+| `OPENROUTER_API_KEY` | - | Conventional key var when `JEV_PROVIDER=openrouter` |
+| `AI_GATEWAY_API_KEY` | - | Conventional key var when `JEV_PROVIDER=vercel` |
+| `TYPESAFE_API_KEY` | - | Conventional key var when `JEV_PROVIDER=typesafe` |
+
 ## Detailed Documentation
 
 For detailed usage of each feature, see the context files:
@@ -142,6 +155,7 @@ mcptools linear issue list --assignee me --json
 mcptools linear teams list
 mcptools linear projects list --team GUZ
 mcptools linear users list --query "Ada"
+mcptools linear chart GUZ-185 GUZ-186 GUZ-188
 ```
 
 ### Bitbucket
@@ -192,9 +206,15 @@ mcptools md fetch https://docs.example.com --selector "main"
 
 ```bash
 mcptools mcp stdio   # For local agents (Claude Desktop)
+mcptools mcp stdio --discovery  # tools/list returns only find_tools (env: MCPTOOLS_DISCOVERY=true)
+mcptools mcp stdio --code-mode  # tools/list returns find_tools,execute (env: MCPTOOLS_CODE_MODE=true)
 mcptools mcp sse     # For web clients
+mcptools mcp catalog # Print the compact tool catalog (domain, name, summary)
+mcptools mcp declarations [NAME...] # Print TypeScript declarations for named tools (all tools without names)
 ```
 
+Find `find_tools` with a task that names the system, read the declaration, call the tool by name, and call same-domain follow-ups directly without another `find_tools` call. See [.claude/context/mcp-server.md#agent-loop](.claude/context/mcp-server.md#agent-loop) for the full loop and the discovery-mode limitation.
+
 ## Setup Guides
 
 - [Atlassian Setup](docs/ATLASSIAN_SETUP.md) - Detailed setup instructions