@cyanheads/mcp-ts-core 0.6.10 → 0.6.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.6.10",
+  "version": "0.6.12",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for building MCP servers. Declarative definitions with auth, multi-backend storage, OpenTelemetry, and first-class support for Bun/Node/Cloudflare Workers.",
   "main": "dist/core/index.js",
@@ -159,12 +159,12 @@
     "yaml": "1.10.3"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.4.12",
+    "@biomejs/biome": "2.4.13",
     "@cloudflare/workers-types": "^4.20260423.1",
     "@hono/otel": "^1.1.1",
-    "@opentelemetry/instrumentation-http": "^0.215.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.215.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.215.0",
+    "@opentelemetry/instrumentation-http": "^0.215.0",
     "@opentelemetry/instrumentation-pino": "^0.61.0",
     "@opentelemetry/resources": "^2.7.0",
     "@opentelemetry/sdk-metrics": "^2.7.0",
@@ -183,20 +183,22 @@
     "bun-types": "^1.3.13",
     "chrono-node": "^2.9.0",
     "clipboardy": "^5.3.1",
+    "defuddle": "^0.18.1",
     "depcheck": "^1.4.7",
     "diff": "^9.0.0",
     "execa": "^9.6.1",
     "fast-check": "^4.7.0",
-    "js-yaml": "^4.1.1",
     "ignore": "^7.0.5",
+    "js-yaml": "^4.1.1",
+    "linkedom": "^0.18.12",
     "node-cron": "^4.2.1",
     "openai": "^6.34.0",
     "papaparse": "^5.5.3",
     "partial-json": "^0.1.7",
     "pdf-lib": "^1.17.1",
     "pino-pretty": "^13.1.3",
-    "sanitize-html": "^2.17.3",
     "repomix": "^1.13.1",
+    "sanitize-html": "^2.17.3",
     "tsc-alias": "^1.8.16",
     "typedoc": "^0.28.19",
     "typescript": "^6.0.3",
@@ -278,9 +280,11 @@
     "@opentelemetry/semantic-conventions": "^1.40.0",
     "@supabase/supabase-js": "^2.103.3",
     "chrono-node": "^2.9.0",
+    "defuddle": "^0.18.1",
     "diff": "latest",
     "fast-xml-parser": "latest",
     "js-yaml": "^4.1.1",
+    "linkedom": "^0.18.12",
     "node-cron": "^4.2.1",
     "openai": "^6.34.0",
     "papaparse": "^5.5.3",
@@ -327,6 +331,9 @@
     "chrono-node": {
       "optional": true
     },
+    "defuddle": {
+      "optional": true
+    },
     "diff": {
       "optional": true
     },
@@ -336,6 +343,9 @@
     "js-yaml": {
       "optional": true
     },
+    "linkedom": {
+      "optional": true
+    },
     "node-cron": {
       "optional": true
     },

package/skills/field-test/SKILL.md

@@ -1,127 +1,250 @@
 ---
 name: field-test
 description: >
-  Exercise tools, resources, and prompts with real-world inputs to verify behavior end-to-end. Use after adding or modifying definitions, or when the user asks to test, try out, or verify their MCP surface. Calls each definition with realistic and adversarial inputs and produces a report of issues, pain points, and recommendations.
+  Exercise tools, resources, and prompts against a live HTTP server via MCP JSON-RPC over curl. Starts the server, surfaces the catalog, runs real and adversarial inputs, and produces a tight report with concrete findings and numbered follow-up options. Use after adding or modifying definitions, or when the user asks to test, try out, or verify their MCP surface.
 metadata:
   author: cyanheads
-  version: "1.3"
+  version: "2.0"
   audience: external
   type: debug
 ---
 
 ## Context
 
-Unit tests (`add-test` skill) verify handler logic with mocked context. Field testing verifies the full picture: real server, real transport, real inputs, real outputs. It catches issues that unit tests miss — bad descriptions, awkward input shapes, unhelpful error messages, missing format functions, schema mismatches, silent divergence between `structuredContent` and model-visible `content[]`, and surprising edge-case behavior.
+Unit tests (`add-test` skill) verify handler logic with mocked context. Field testing exercises the real HTTP transport with real JSON-RPC: starts the server, calls `initialize`, surfaces the catalog, runs inputs, and checks what a client actually sees. It catches what unit tests miss — awkward input shapes, unhelpful errors, missing format output, drift between `structuredContent` and `content[]`, edge-case surprises.
 
-**Actively use** the tools — don't just read their code.
+**Actively call the tools. Don't read code and guess.**
 
 ---
 
 ## Steps
 
-### 1. Surface available definitions
+### 1. Start the server
+
+Write the helper to `/tmp/mcp-field-test.sh` once, then source it in every subsequent Bash call. Helper keeps PID / URL / session id in `/tmp/mcp-field-test.env` so state survives across tool invocations.
+
+```bash
+cat > /tmp/mcp-field-test.sh <<'HELPER_EOF'
+#!/bin/bash
+# Field-test helper: manage an MCP HTTP server + JSON-RPC session across shell calls.
+STATE_FILE="/tmp/mcp-field-test.env"
+[ -f "$STATE_FILE" ] && . "$STATE_FILE"
+
+mcp_start() {
+  local dir="${1:-$PWD}"
+  echo "building $dir ..."
+  (cd "$dir" && bun run rebuild) >/tmp/mcp-build.log 2>&1 \
+    || { echo "BUILD FAILED — see /tmp/mcp-build.log"; return 1; }
+  echo "starting server ..."
+  (cd "$dir" && bun run start:http) >/tmp/mcp-server.log 2>&1 &
+  local pid=$!
+  local line=""
+  for _ in $(seq 1 40); do
+    line=$(grep -Eo 'listening at http://[^" ]+/mcp' /tmp/mcp-server.log | head -1)
+    [ -n "$line" ] && break
+    sleep 0.25
+  done
+  if [ -z "$line" ]; then
+    echo "server failed to start — see /tmp/mcp-server.log"
+    kill "$pid" 2>/dev/null
+    return 1
+  fi
+  local url="${line#listening at }"
+  local port; port=$(echo "$url" | sed -E 's|.*:([0-9]+)/.*|\1|')
+  cat > "$STATE_FILE" <<EOF
+export MCP_PID=$pid
+export MCP_URL=$url
+export MCP_PORT=$port
+EOF
+  . "$STATE_FILE"
+  echo "ready pid=$pid url=$url"
+}
+
+mcp_init() {
+  [ -z "$MCP_URL" ] && { echo "run mcp_start first"; return 1; }
+  local hdr="/tmp/mcp-init-headers.txt"
+  curl -sS -D "$hdr" -X POST "$MCP_URL" \
+    -H "Content-Type: application/json" \
+    -H "Accept: application/json, text/event-stream" \
+    -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"field-test","version":"2.0"}}}' >/dev/null
+  local sid; sid=$(grep -i '^mcp-session-id:' "$hdr" | awk '{print $2}' | tr -d '\r\n')
+  [ -z "$sid" ] && { echo "no session id returned"; return 1; }
+  cat > "$STATE_FILE" <<EOF
+export MCP_PID=$MCP_PID
+export MCP_URL=$MCP_URL
+export MCP_PORT=$MCP_PORT
+export MCP_SID=$sid
+EOF
+  . "$STATE_FILE"
+  curl -sS -X POST "$MCP_URL" \
+    -H "Content-Type: application/json" \
+    -H "Accept: application/json, text/event-stream" \
+    -H "Mcp-Session-Id: $sid" \
+    -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' >/dev/null
+  echo "session=$sid"
+}
+
+# Usage: mcp_call METHOD [JSON_PARAMS]
+# Prints the JSON-RPC response (SSE framing stripped). Pipe to `jq`.
+mcp_call() {
+  [ -z "$MCP_SID" ] && { echo "run mcp_init first"; return 1; }
+  local method="$1"; local params="${2:-}"
+  local body
+  if [ -z "$params" ]; then
+    body=$(printf '{"jsonrpc":"2.0","id":%d,"method":"%s"}' "$RANDOM" "$method")
+  else
+    body=$(printf '{"jsonrpc":"2.0","id":%d,"method":"%s","params":%s}' "$RANDOM" "$method" "$params")
+  fi
+  curl -sS -X POST "$MCP_URL" \
+    -H "Content-Type: application/json" \
+    -H "Accept: application/json, text/event-stream" \
+    -H "Mcp-Session-Id: $MCP_SID" \
+    -d "$body" | sed -n 's/^data: //p'
+}
+
+mcp_stop() {
+  [ -n "$MCP_PID" ] && kill "$MCP_PID" 2>/dev/null
+  rm -f "$STATE_FILE"
+  echo "stopped"
+}
+HELPER_EOF
+
+. /tmp/mcp-field-test.sh
+mcp_start /absolute/path/to/server   # replace with the target server
+```
+
+**Notes**
+
+- `MCP_HTTP_PORT` is a *starting* port — the server auto-increments if taken. Helper parses the real URL from the log (`HTTP transport listening at ...`).
+- If `bun run rebuild` fails, stop. Don't field-test broken code — fix the build first.
+- If a server is already listening on the project's port (`lsof -i :<port>`), confirm with the user before killing it; it may be their own session.
+
+### 2. Initialize the session
+
+```bash
+. /tmp/mcp-field-test.sh
+mcp_init
+```
+
+Runs `initialize`, captures the session id, sends `notifications/initialized`.
+
+### 3. Surface the catalog
+
+```bash
+. /tmp/mcp-field-test.sh
+mcp_call tools/list     | jq '.result.tools[]     | {name, description, inputSchema}'
+mcp_call resources/list | jq '.result.resources[] | {uri, name, mimeType}'
+mcp_call prompts/list   | jq '.result.prompts[]   | {name, description, arguments}'
+```
+
+Present a compact catalog to the user: each definition's name + 1-line description. Flag vague or missing descriptions as you go — those feed into the report. Use this to build the test plan.
+
+### 4. Plan the test pass
+
+**Budget.** Don't run every category against every definition — the cross-product is infeasible. Apply the **universal battery** to everything; apply **situational categories** only when the definition triggers them.
+
+**Universal battery — run on every tool**
+
+| Category | What to verify |
+|:---------|:---------------|
+| Happy path | One realistic input. Output shape matches schema. `content[]` text reads clearly to a human. |
+| `structuredContent` ↔ `content[]` parity | Every field in `structuredContent` is surfaced in the text. Parity gap = client-specific blindness. |
+| Input error | One invalid input (wrong type or missing required). Error text says *what*, *why*, *how to fix*. |
+
+**Situational — add only when triggered**
+
+| Trigger (look in input schema or `annotations`) | Add category |
+|:------------------------------------------------|:-------------|
+| `include` / `fields` / `expand` / `view` / `projection` parameter | Field selection: non-default value renders requested fields |
+| Array return with `query` / `filter` inputs | Empty result: does response explain *why* (echo criteria, suggest broadening)? |
+| Batch / bulk input (arrays of IDs, multi-item ops) | Partial success: mix valid + invalid items |
+| `annotations.readOnlyHint: true` | Confirm no mutation happened |
+| `annotations.idempotentHint: true` | Call twice with same input — safe? |
+| Hits external API / live upstream | One call that exercises upstream; note rate-limit / timeout / transient-failure behavior |
+| Chained with other tools (search → detail → act) | Run one representative chain end-to-end; does each step return the IDs/cursors the next needs? |
+| `cursor` / `offset` / `limit` params | Pagination: second page, end-of-list |
 
-List the MCP tools, resources, and prompts available in your environment. This confirms the server is connected and gives you everything you need — names, descriptions, parameter schemas — to plan your tests.
+**Resources.** Happy path, not-found URI, `list` if defined, pagination if used.
+**Prompts.** Happy path, defaults omitted, skim message quality.
 
-If you don't see any MCP tools from this server, ask the user to connect it first (e.g. `claude mcp add` for Claude Code, or the equivalent for their client). Don't proceed until the tools are visible.
+**Sampling for large servers.** If more than 15 tools, run the universal battery on all, but pick roughly 30–40% for situational testing. Weight toward: write-shaped tools, complex schemas, external deps. List which ones you skipped in the report.
 
-Present what you find: each definition's name, parameters (with types and descriptions), and any notable schema details (optional fields, enums, constraints). This is your test surface.
+**Auth & external state.**
 
-### 2. Test each definition
+- If a tool needs real API keys and they're not set, note `skipped — requires $VAR` and move on. Don't fabricate inputs.
+- Tools that write to real external systems (third-party APIs, shared DBs): confirm with the user before running, or use a dry-run input if one exists.
 
-For every tool, resource, and prompt, run through these categories:
+### 5. Execute
 
-#### Tools
+Use `TaskCreate` — one task per definition. Mark complete as you go. Don't batch.
 
-| Category | What to test |
-|:---------|:-------------|
-| **Happy path** | Realistic input that should succeed. Verify output shape matches the output schema. Verify format function produces sensible content blocks. |
-| **`structuredContent` parity** | The `format-parity` lint rule already asserts every terminal field in the output schema appears in `format()`'s rendered text (via sentinel injection at startup). Field testing layers real-data checks on top: are values rendered accurately (not just their labels)? Do conditional-render branches in `format()` still render every field when specific values are present? Does the content look right to a human reading the LLM's view? |
-| **Variations** | Different valid input combinations — optional fields omitted, optional fields included, different enum values, min/max boundaries. |
-| **Field selection / projection** | For tools with `fields`, `include`, `expand`, `view`, or similar parameters, call the tool with non-default selections. Verify the handler returns the requested fields and `format()` renders each requested field rather than a hardcoded summary subset. |
-| **Edge cases** | Empty strings, zero values, very long inputs, special characters, Unicode. |
-| **Error paths** | Missing required fields, wrong types, nonexistent IDs, inputs that should trigger domain errors. Verify errors are clear and actionable — they should name what went wrong, why, and what to do next. |
-| **Empty results** | Inputs that match nothing. Verify the response explains *why* (echoes criteria, suggests broadening) rather than returning a bare empty array. |
-| **Partial success** | For tools that operate on multiple items, test cases where some succeed and some fail. Verify both outcomes are reported — not just the successes. |
-| **Annotations** | Review tool `annotations` (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) against actual behavior. If a tool is marked read-only, verify it does not mutate state. If it is marked idempotent, verify retries with the same input are safe. If it is marked open-world false, verify it is not silently depending on live external systems. |
-| **Workflow chaining** | For servers with multi-step workflows, execute 1-2 representative chains end-to-end. Example: search → detail → follow-up action. Verify each step returns the IDs, cursors, URIs, tokens, or state needed for the next step without guessing. |
-| **Response quality** | Inspect successful responses for: (1) chaining IDs needed for follow-up calls, (2) operational metadata (counts, applied filters, truncation notices), (3) filtering transparency (if anything was excluded, does the response say what and how to include it?), (4) reasonable response size (not dumping unbounded data into context). See the `add-tool` skill's **Tool Response Design** section for the full set of patterns. |
-| **Resilience** | For tools backed by external APIs or slow subsystems, test or explicitly note rate-limit, timeout, and transient-failure behavior. Verify retries/backoff happen where intended, or at minimum that the error message clearly tells the user whether to retry, wait, or change input. |
-| **Descriptions** | Read every field's `.describe()` — would a user/LLM understand what to provide? Flag vague or missing descriptions. |
+For each call, capture: input sent, response (trim huge payloads to files), whether `isError: true` appeared, anything surprising (slow response, parity drift, unhelpful text, crash).
 
-#### Resources
+**Interpreting responses**
 
-| Category | What to test |
-|:---------|:-------------|
-| **Happy path** | Valid URI with known params. Verify returned content and MIME type. |
-| **List** | Call `list` if defined. Verify returned resources have names and valid URIs. |
-| **Not found** | URI with nonexistent params. Verify a clear error, not a crash. |
-| **Pagination** | If the resource uses `extractCursor`/`paginateArray`, test with varying limits and cursors. |
+- Tool domain errors return `{result: {content: [...], isError: true}}` — they live in `result`, not `error`. Check `isError`, not the JSON-RPC error field.
+- JSON-RPC `error` only appears for protocol issues (bad session, malformed envelope, unknown method).
+- `mcp_call` already strips SSE framing. Pipe to `jq` for readability.
 
-#### Prompts
+### 6. Tear down
 
-| Category | What to test |
-|:---------|:-------------|
-| **Happy path** | Valid args. Verify generated messages are well-formed. |
-| **Defaults** | Omit optional args. Verify the output still makes sense. |
-| **Content quality** | Read the generated messages — are they clear, well-structured prompts? |
+```bash
+. /tmp/mcp-field-test.sh
+mcp_stop
+```
 
-### 3. Track progress
+Kills the background server, clears state. Do this *before* writing the report so nothing leaks into the next session.
 
-Use a todo list to track each definition and its test status. Mark each as you go — don't batch.
+### 7. Report
 
-### 4. Produce the report
+Three sections. Tight. The user should be able to skim the summary, read details only for what matters, and act on numbered options.
 
-After testing everything, present a structured report:
+#### Summary (1 paragraph)
 
-#### Summary table
+One paragraph. How many definitions exercised, how many passed clean, how many have issues, and the single most important finding. No tables, no lists.
 
-| Definition | Type | Status | Issues |
-|:-----------|:-----|:-------|:-------|
-| `acme_search_items` | tool | pass | — |
-| `acme_get_item` | tool | issues | Error message unhelpful for missing ID |
-| `item://` | resource | fail | Crashes on nonexistent ID |
+#### Findings
 
-#### Detailed findings
+Only include definitions with issues. Group by severity. Each finding is 2–4 lines unless it genuinely needs more.
 
-For each definition with issues, include:
+| Severity | Meaning |
+|:---------|:--------|
+| **bug** | Broken: crash, wrong output, `isError: true` on valid input, data loss, schema violation |
+| **ux** | Works but degrades the user/LLM experience: vague description, unhelpful error text, missing `format()`, parity drift, annotation mismatches behavior |
+| **nit** | Polish: phrasing, inconsistent tone, minor doc gaps |
 
-- **What happened** — the input, the output or error, and what was expected
-- **Severity** — `bug` (broken behavior), `ux` (works but confusing/unhelpful), `nit` (minor polish)
-- **Recommendation** — specific fix suggestion
+Format:
 
-#### Pain points
+```
+**<tool_name> — <bug|ux|nit>**
+Input: `<short input>` → <what happened>
+Expected: <what should happen>
+Fix: <one sentence>
+```
 
-Cross-cutting observations that aren't tied to a single definition:
+#### Options
 
-- Inconsistent error message patterns across tools
-- Missing format functions (raw JSON returned to user)
-- `structuredContent` contains data that `content[]` silently drops
-- Requested projected fields are returned programmatically but not rendered for the model
-- Description quality issues (vague, missing, or misleading)
-- Schema design issues (required fields that should be optional, missing defaults, overly broad types, non-JSON-Schema-serializable types like `z.custom()` or `z.date()`)
-- Annotation hints that do not match real behavior (`readOnlyHint`, `idempotentHint`, `openWorldHint`)
-- Response quality issues (empty results with no context, silent filtering, missing chaining IDs, oversized payloads, no operational metadata)
-- Multi-step workflows that cannot be completed because intermediate outputs omit required IDs, cursors, or URIs
-- Error messages that don't guide recovery (generic "not found" instead of naming alternatives)
-- Resilience issues (rate limits, timeouts, transient upstream failures handled poorly or explained poorly)
-- Performance observations (unexpectedly slow responses)
+Numbered, actionable, cherry-pickable. Each item maps to a concrete change.
+
+```
+1. Fix empty-result message in `pubmed_search_articles` — echo criteria (finding #2)
+2. Add `format()` to `pubmed_lookup_mesh` — currently returns raw JSON (finding #5)
+3. Tighten `ids` description in `pubmed_fetch_articles` — silent on PMID vs DOI (finding #8)
+```
+
+End with:
+
+> Pick by number (e.g. "do 1, 3, 5" or "expand on 2").
 
 ---
 
 ## Checklist
 
-- [ ] All registered tools tested (happy path + edge cases + empty results)
-- [ ] All registered resources tested (happy path + not found)
-- [ ] All registered prompts tested (happy path + defaults)
-- [ ] Error messages reviewed for clarity and recovery guidance
-- [ ] Empty-result responses reviewed for context (criteria echo, suggestions)
-- [ ] `structuredContent` and `content[]` reviewed for parity
-- [ ] Field-selection / projection behavior reviewed where applicable
-- [ ] Response quality reviewed (chaining IDs, metadata, filtering transparency, payload size)
-- [ ] Tool annotations reviewed against actual behavior
-- [ ] Representative multi-step workflows exercised where applicable
-- [ ] External API resilience reviewed where applicable (rate limits, timeouts, transient failures)
-- [ ] Descriptions reviewed for completeness and accuracy
-- [ ] Format functions verified (or absence noted)
-- [ ] Summary report presented to user
+- [ ] Server built and started; real port parsed from log
+- [ ] Session initialized; `notifications/initialized` sent
+- [ ] Catalog surfaced and presented
+- [ ] Universal battery run on every definition
+- [ ] Situational categories applied only when triggered
+- [ ] External-state / auth-gated tools handled explicitly (run, skip, or confirm)
+- [ ] Server stopped; state file removed
+- [ ] Report: summary paragraph → grouped findings → numbered options

package/skills/report-issue-framework/SKILL.md

@@ -4,7 +4,7 @@ description: >
   File a bug or feature request against @cyanheads/mcp-ts-core when you hit a framework issue. Use when a builder, utility, context method, or config behaves contrary to the documented API — not for server-specific application bugs.
 metadata:
   author: cyanheads
-  version: "1.1"
+  version: "1.2"
   audience: external
   type: workflow
 ---
@@ -20,6 +20,8 @@ You've isolated a problem to `@cyanheads/mcp-ts-core` itself — not your server
 - Type exports are incorrect or missing (compile error on documented usage)
 - The definition linter (`bun run lint:mcp`) produces false positives or misses real violations
 
+For general `gh` CLI workflows outside issue filing (PRs, workflows, API access), see the `github-cli` skill.
+
 ## Before Filing
 
 1. **Confirm framework version** — `bun pm ls @cyanheads/mcp-ts-core` or check `node_modules/@cyanheads/mcp-ts-core/package.json`
@@ -31,6 +33,20 @@ You've isolated a problem to `@cyanheads/mcp-ts-core` itself — not your server
 gh issue list -R cyanheads/mcp-ts-core --search "your error message or keyword"
 ```
 
+## Writing Well-Structured Issues
+
+Good issues are scannable, concrete, and self-contained. These patterns apply to both bugs and features — the guidance targets any prose block (Description, Additional context, feature proposals).
+
+- **Lead with specifics.** Name the tool, function, module, or symptom. "Currently `createApp()` throws `ConfigurationError` when `MCP_HTTP_PORT` is set to `0`" beats "There's a problem with the config." A reader should know what's broken or missing before the end of the first sentence.
+- **Embed library/service links on first mention.** `[Hono](https://hono.dev/)`, `[linkedom](https://github.com/WebReflection/linkedom)`. Link to the canonical repo or homepage so readers can verify the dependency and reach docs in one click.
+- **Use `owner/repo#N` for cross-repo issue references.** GitHub auto-renders them as linked references (e.g. `cyanheads/pubmed-mcp-server#34`). Bare `#N` only works for same-repo issues.
+- **Add a `Related: #N` line** near the top when the issue grows from prior context (discussions, other issues, PRs). Makes provenance clickable.
+- **Lead design sections with a philosophy sentence.** Bold a short principle before the tradeoff details — e.g. "Philosophy: **fail fast on config errors, degrade gracefully on runtime errors.**" Establishes the lens for the rest of the section.
+- **Prefer Markdown tables for comparisons.** When showing options, tiers, strategies, or tradeoffs — tables are the highest-density format for scanning N rows × M attributes.
+- **Separate `### Scope` from `### Out of scope`.** The latter is as important as the former — it pre-empts scope-creep debates in comments and signals you've thought about the boundaries.
+- **Use `Depends on: owner/repo#N`** to declare ordering explicitly when implementation is blocked on another issue landing first.
+- **Skip collaborator-framing sign-offs.** Lines like "Happy to open a PR", "let me know if you'd like", "willing to contribute", "if that's the preferred flow" read as noise. A PR link beats an offer; if you're the maintainer filing against your own repo, the offer is redundant. End the body at the last substantive point.
+
 ## Redact Before Posting
 
 GitHub issues are **public**. Do not include secrets, credentials, API keys, or tokens. Redact sensitive values from env vars, headers, and logs before submitting. Replace with obvious placeholders: `REDACTED`, `sk-...REDACTED`. Do not rely on partial masking — partial keys can still be exploited.
@@ -174,14 +190,20 @@ gh issue create -R cyanheads/mcp-ts-core --template "Feature Request" --web
 
 ### CLI (non-interactive)
 
+Template below demonstrates the richer structure. Omit sections you don't need — simple requests don't require Flow / Design / Dependencies blocks.
+
 ````bash
 gh issue create -R cyanheads/mcp-ts-core \
   --title "feat(scope): concise description" \
   --label "enhancement" \
   --body "$(cat <<'ISSUE'
-### Use case
+Concrete statement of what's currently missing or broken in the framework. Name the specific builder, utility, context method, or config field. Two or three sentences — the reader should know the gap before the end of the paragraph.
 
-Describe the problem you're solving and why the framework should handle it.
+Related: #N
+
+## Proposal
+
+What you want the framework to do, in one paragraph. Link external libraries on first mention: [lib name](https://github.com/owner/repo). Include a short justification — what this gives us that we don't have today.
 
 ### Proposed API
 
@@ -194,9 +216,37 @@ const result = await withRetry(() => fetchExternal(url), {
 });
 ```
 
+### Flow (optional)
+
+Ordered steps — e.g. `trigger → resolve → fetch → degrade`. Useful when the change spans multiple phases or fallbacks.
+
+### Design / Tradeoffs (optional)
+
+Philosophy: **one-line principle in bold.**
+
+| Option | Strengths | Weaknesses |
+|:---|:---|:---|
+| A | ... | ... |
+| B | ... | ... |
+
+### Scope
+
+- Files or modules touched
+- New exports, env vars, or config keys
+- Tier (Tier 1 core / Tier 2 standard / Tier 3 optional peer dep)
+
+### Out of scope
+
+- What we're deliberately not doing
+- Adjacent work that belongs in a separate issue
+
+### Dependencies (optional)
+
+- Depends on: owner/repo#N
+
 ### Alternatives considered
 
-What you tried or considered instead.
+What you tried or evaluated instead, and why it didn't fit.
 ISSUE
 )"
 ````

package/skills/report-issue-local/SKILL.md

@@ -4,7 +4,7 @@ description: >
   File a bug or feature request against this MCP server's own repo. Use for server-specific issues — tool logic, service integrations, config problems, or domain bugs that aren't caused by the framework.
 metadata:
   author: cyanheads
-  version: "1.1"
+  version: "1.2"
   audience: external
   type: workflow
 ---
@@ -22,6 +22,8 @@ The bug is in this server's code, not in `@cyanheads/mcp-ts-core`. Typical trigg
 
 **If the issue is in the framework itself** (builders, Context, utilities, type exports, linter), use `report-issue-framework` instead.
 
+For general `gh` CLI workflows outside issue filing (PRs, workflows, API access), see the `github-cli` skill.
+
 ## Before Filing
 
 1. **Identify the repo**:
@@ -40,6 +42,20 @@ gh issue list --search "your error message or keyword"
 
 4. **Check logs** — review `ctx.log` output and any framework telemetry for clues. If running HTTP, check the response body for structured error details.
 
+## Writing Well-Structured Issues
+
+Good issues are scannable, concrete, and self-contained. These patterns apply to both bugs and features — the guidance targets any prose block (Description, Additional context, feature proposals).
+
+- **Lead with specifics.** Name the tool, service, resource, or symptom. "Currently `search_docs` returns an empty array for queries containing `&`" beats "Search is broken." A reader should know what's wrong before the end of the first sentence.
+- **Embed library/service links on first mention.** `[Hono](https://hono.dev/)`, `[Supabase](https://supabase.com/)`. Link to the canonical repo or homepage so readers can verify the dependency and reach docs in one click.
+- **Use `owner/repo#N` for cross-repo issue references.** GitHub auto-renders them as linked references (e.g. `cyanheads/mcp-ts-core#46`). Bare `#N` only works for same-repo issues — useful when the bug depends on or relates to a framework issue.
+- **Add a `Related: #N` line** near the top when the issue grows from prior context (discussions, other issues, PRs). Makes provenance clickable.
+- **Lead design sections with a philosophy sentence.** Bold a short principle before the tradeoff details — e.g. "Philosophy: **return best-effort data, don't fail the tool call on parsing edge cases.**" Establishes the lens for the rest of the section.
+- **Prefer Markdown tables for comparisons.** When showing options, data sources, strategies, or tradeoffs — tables are the highest-density format for scanning N rows × M attributes.
+- **Separate `### Scope` from `### Out of scope`.** The latter is as important as the former — it pre-empts scope-creep debates in comments and signals you've thought about the boundaries.
+- **Use `Depends on: owner/repo#N`** to declare ordering explicitly when implementation is blocked on an upstream framework change or another issue landing first.
+- **Skip collaborator-framing sign-offs.** Lines like "Happy to open a PR", "let me know if you'd like", "willing to contribute", "if that's the preferred flow" read as noise. A PR link beats an offer; if you're the maintainer filing against your own repo, the offer is redundant. End the body at the last substantive point.
+
 ## Redact Before Posting
 
 GitHub issues are **public**. Do not include secrets, credentials, API keys, or tokens. Redact sensitive values from env vars, headers, and logs before submitting. Replace with obvious placeholders: `REDACTED`, `sk-...REDACTED`. Do not rely on partial masking — partial keys can still be exploited.
@@ -158,22 +174,61 @@ gh issue create --template "Feature Request" --web
 
 ### CLI (non-interactive)
 
+Template below demonstrates the richer structure. Omit sections you don't need — simple requests don't require Flow / Design / Dependencies blocks.
+
 ````bash
 gh issue create \
   --title "feat(scope): concise description" \
   --label "enhancement" \
   --body "$(cat <<'ISSUE'
-### Use case
+Concrete statement of what's currently missing or broken. Name the specific tool, service, resource, or domain area. Two or three sentences — the reader should know the gap before the end of the paragraph.
 
-What problem does this solve? Who benefits?
+Related: #N
+
+## Proposal
+
+What you want the server to do, in one paragraph. Link external libraries or services on first mention: [lib name](https://github.com/owner/repo). Include a short justification — what this gives users that they don't have today.
 
 ### Proposed behavior
 
-Describe the expected behavior or API change.
+Describe the new behavior or surface. For tool/resource changes, show example input/output or the new schema fields:
+
+```ts
+// Example: new input field or output shape
+```
+
+### Flow (optional)
+
+Ordered steps — e.g. `request → lookup → fallback → respond`. Useful when the change spans multiple phases or fallbacks.
+
+### Design / Tradeoffs (optional)
+
+Philosophy: **one-line principle in bold.**
+
+| Option | Strengths | Weaknesses |
+|:---|:---|:---|
+| A | ... | ... |
+| B | ... | ... |
+
+### Scope
+
+- Files or modules touched
+- New env vars, config keys, or service integrations
+- New or modified tools / resources / prompts
+
+### Out of scope
+
+- What we're deliberately not doing
+- Adjacent work that belongs in a separate issue
+
+### Dependencies (optional)
+
+- Depends on: cyanheads/mcp-ts-core#N (upstream framework change)
+- Depends on: owner/repo#N (other server work)
 
 ### Alternatives considered
 
-What you tried or considered instead.
+What you tried or evaluated instead, and why it didn't fit.
 ISSUE
 )"
 ````