github-mcp-sketch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Adel Nawar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+# github-mcp-sketch
+
+A local MCP server that proxies the [GitHub MCP](https://github.com/github/github-mcp-server) and returns the JSON's inferred schema instead of the raw response. Adds a `query_response` tool the agent uses to pull specific fields it actually needs.
+
+The point: most GitHub API responses are 80%+ metadata the agent doesn't read. `list_pull_requests` for 30 PRs is ~80KB; the agent usually needs 4–5 fields per PR. Returning a schema first lets the model see the shape and decide what to fetch back.
+
+## What the numbers look like
+
+Benchmarked across 13 agentic tasks on [`facebook/react`](https://github.com/facebook/react) and [`kubernetes/kubernetes`](https://github.com/kubernetes/kubernetes), Anthropic SDK with prompt caching enabled (matching how Claude Code uses the API). N=3 runs per case per side. Sum of medians across all 13 cases:
+
+| Metric | Baseline (`github`) | Sketch (`github-sketch`) | Δ |
+|---|---|---|---|
+| Final context size (tokens) | 844,136 | 348,292 | **−58.7%** |
+| API cost (Claude Opus 4.7) | $5.59 | $2.73 | **−51.2%** |
+| Total tokens billed | 1.84M | 1.27M | −30.8% |
+
+Where the win lives — the 13 cases grouped by the shape of response they exercise:
+
+| Response shape | Cases | Δ context | Δ cost |
+|---|---|---|---|
+| Single-object fetches (one issue, one PR) | 2 | +3% | +52% |
+| List endpoints with rich metadata (30+ items, lots of URL/reaction noise) | 3 | **−74%** | **−71%** |
+| Comment-heavy threads (KEP review, long React discussion) | 3 | **−69%** | **−57%** |
+| Multi-step agentic workflows (triage, investigation, drill-down) | 3 | **−40%** | **−27%** |
+| File contents and commit history | 2 | −2% | 0% |
+
+The first and last rows are where the proxy doesn't help. On a single issue with ~15 fields, the agent queries back ~11 of them anyway — no noise to skip, and the extra round-trip costs more than it saves. On raw file source, the contents are opaque text — schemas can't compress text. Both were included in the benchmark intentionally so the data isn't cherry-picked.
+
+Full report and reproducible bench: [`json-schema-sketch-bench`](https://github.com/markadelnawar/json-schema-sketch-bench).
+
+## How it works
+
+Every upstream tool call (`list_issues`, `pull_request_read`, etc.) goes through this pipeline:
+
+1. The proxy forwards the call to `https://api.githubcopilot.com/mcp` with the agent-supplied PAT.
+2. The raw JSON response is cached in memory under a generated `cache_id`.
+3. The response shape is inferred via [`json-schema-sketch`](https://github.com/markadelnawar/json-schema-sketch) into a compact text-form schema.
+4. The proxy returns `cache_id: gh-1-abc (pass to query_response)` followed by the schema. That's the entire tool result the agent sees.
+
+When the agent wants actual values, it calls `query_response`:
+
+```
+query_response(cache_id="gh-1-abc", path="items[*].title")
+```
+
+Path syntax supports dot/bracket navigation and `[*]` wildcards. The agent can pass an array of paths to batch multiple field extractions into one tool call:
+
+```
+query_response(cache_id="gh-1-abc", path=["items[*].title", "items[*].state", "items[*].user.login"])
+```
+
+Cache entries live until the proxy process exits. There's no TTL; the design assumes one agent session per proxy process.
+
+## Install
+
+Requires Node 20+.
+
+```bash
+npm install -g github-mcp-sketch
+```
+
+You'll need a GitHub Personal Access Token (fine-grained, read-only is enough). [Create one](https://github.com/settings/personal-access-tokens/new) with content and metadata read on whatever repos you'll use it against.
+
+## Configuration
+
+All configuration is via environment variables.
+
+| Variable | Required | Default | Purpose |
+|---|---|---|---|
+| `GITHUB_PAT` | yes | — | Bearer token forwarded as the `Authorization` header on every upstream request. |
+| `UPSTREAM_MCP_URL` | no | `https://api.githubcopilot.com/mcp` | Upstream MCP endpoint. Override for testing or self-hosted GitHub MCPs. |
+| `CACHE_SIZE` | no | `50` | Max number of cached responses kept in memory before LRU eviction. Each cached entry is one upstream tool result. |
+| `METRICS_CSV` | no | *(off)* | If set to a file path, the proxy appends per-tool-call metrics (raw vs sketched response size, tokens, timing) to that CSV. Off by default — set it explicitly to opt in. |
+
+How the variables get set depends on how you launch the proxy:
+
+- **From an MCP host** (Claude Code, Claude Desktop, Cline, etc.) — the host passes env vars to the spawned process. In Claude Code that's the `-e KEY=VALUE` flag of `claude mcp add` (shown below). Values are stored in the host's MCP config (`~/.claude.json` for Claude Code).
+- **Direct shell invocation** — `GITHUB_PAT=ghp_... github-mcp-sketch`, or export the variable in your shell rc.
+- **Running from a clone of the source** — copy `.env.example` → `.env`, fill it in. Dotenv loads it on startup. (`.env` is gitignored.)
+
+## Wire into Claude Code
+
+Minimal — just the required PAT:
+
+```bash
+claude mcp add github-sketch \
+  -e GITHUB_PAT=<your_pat> \
+  -- npx github-mcp-sketch
+```
+
+With optional variables — stack additional `-e KEY=VALUE` flags before the `--`:
+
+```bash
+claude mcp add github-sketch \
+  -e GITHUB_PAT=<your_pat> \
+  -e CACHE_SIZE=200 \
+  -e METRICS_CSV=/tmp/github-sketch-metrics.csv \
+  -- npx github-mcp-sketch
+```
+
+All `-e` values are persisted in `~/.claude.json` and passed to the proxy on every spawn.
+
+Verify the server is registered:
+
+```bash
+claude mcp list | grep github-sketch
+# github-sketch: npx github-mcp-sketch - ✓ Connected
+```
+
+Restart Claude Code so the new server is registered.
+
+### Changing variables after wire-up
+
+Claude Code doesn't expose an in-place edit for MCP env vars. To change one:
+
+```bash
+claude mcp remove github-sketch
+claude mcp add github-sketch -e GITHUB_PAT=<new_pat> -- npx github-mcp-sketch
+```
+
+Or edit `~/.claude.json` directly under the `mcpServers.github-sketch.env` block.
+
+## Wire into other MCP hosts
+
+The proxy is a standard stdio MCP — anything that speaks MCP can host it. The general pattern:
+
+- Spawn `npx github-mcp-sketch` as a stdio process
+- Pass env vars (at minimum `GITHUB_PAT`) on that spawn
+
+For example, in a custom Anthropic SDK app using `@modelcontextprotocol/sdk`:
+
+```ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const transport = new StdioClientTransport({
+  command: "npx",
+  args: ["github-mcp-sketch"],
+  env: {
+    ...process.env,
+    GITHUB_PAT: process.env.GITHUB_PAT!,
+    CACHE_SIZE: "100",  // optional
+  },
+});
+const client = new Client({ name: "my-app", version: "0.1.0" });
+await client.connect(transport);
+```
+
+Verify:
+
+```bash
+claude mcp list | grep github-sketch
+# github-sketch: node /.../dist/server.js - ✓ Connected
+```
+
+Restart Claude Code so the new server is registered. The proxy exposes the same tool names as the upstream GitHub MCP (`list_issues`, `pull_request_read`, `get_file_contents`, etc.) plus the added `query_response`.
+
+## Tools
+
+The proxy passes through every tool from the upstream GitHub MCP with identical names, descriptions, and input schemas. The agent calls them exactly as it would call the upstream MCP.
+
+The one added tool:
+
+### `query_response(cache_id, path, max_items?)`
+
+Extract values from a response cached by a previous tool call.
+
+**Path syntax:**
+
+| Path | Returns |
+|---|---|
+| `""` (empty string) | The whole cached value |
+| `"user.login"` | A nested scalar |
+| `"[0].title"` | First array item's field |
+| `"[*].title"` | A field from every array item |
+| `"items[*].user.login"` | Nested field across an array |
+
+**Batch mode** — pass an array of paths to get multiple fields in one call:
+
+```
+path=["items[*].number", "items[*].title", "items[*].state"]
+```
+
+Returns `{ results: { "items[*].number": [...], "items[*].title": [...], ... } }`. Per-path errors are reported in that path's entry; other paths still succeed.
+
+**`max_items`** — optional cap on items returned per wildcard expansion. Defaults to unlimited; the agent only sets it when it explicitly wants a sample.
+
+## When it doesn't help
+
+Looking at the per-tier table above:
+
+- **Single-object fetches of small objects** (one issue, one user) — the agent queries back most of the fields anyway, so the schema + query overhead exceeds the per-call wire savings.
+- **File contents** — raw file text isn't structured, so there's no schema noise to skip. The proxy passes the file through with minor envelope savings only.
+- **Tasks where the agent really does need every field** — almost never happens for list and search endpoints, but is the failure mode if it does.
+
+Known variance: on `t3-06` (a 67-comment review thread on a Kubernetes KEP), one of three sketch runs occasionally consumes ~60K context (vs ~39K median) because the agent issues a doubly-nested wildcard query (`review_threads[*].comments[*].body`) that materializes most of the original payload. The median is still ~56% better than baseline, but this is a real pattern the agent can fall into. The proxy doesn't currently guard against it.
+
+## Reproduce the bench
+
+The benchmark is a separate repo: [`json-schema-sketch-bench`](https://github.com/markadelnawar/json-schema-sketch-bench).
+
+```bash
+git clone https://github.com/markadelnawar/json-schema-sketch-bench
+cd json-schema-sketch-bench
+npm install
+cp .env.example .env  # add ANTHROPIC_API_KEY and GITHUB_PAT
+npm run bench   # 13 cases × 2 sides × 3 runs, ~45 min, ~$5-10
+npm run report  # generates summary.md
+```
+
+Cases, raw CSVs, methodology details, and the final `summary.md` from a recent run are all checked in.
+
+## Architecture
+
+The proxy is a thin stdio MCP server:
+
+- Connects to `https://api.githubcopilot.com/mcp` over Streamable HTTP using the agent-provided `GITHUB_PAT`.
+- On startup, calls upstream `listTools()` and registers each tool with its original name and description. Adds `query_response` to the manifest.
+- On `tools/call`: if the name is `query_response`, resolves the path against the cache; otherwise forwards upstream, caches the parsed JSON, infers the schema, and returns the wrapped response.
+
+There's no rate limiting, no retry, no auth refresh. Upstream errors are returned verbatim.
+
+## Caveats
+
+- **Stateful in memory.** Cache entries live until the proxy process exits. Restart Claude Code = empty cache.
+- **One PAT per process.** The proxy reads `GITHUB_PAT` once at startup. To rotate, restart.
+- **Schemas drop list-element variance.** If items in an array have different shapes, the schema picks a representative one. Rarely a problem for GitHub responses but can be surprising.
+- **No write-tool optimization.** Tools that perform writes (`create_issue`, `merge_pull_request`) work but the response sketching is wasted on small confirmation payloads.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Related
+
+- [`json-schema-sketch`](https://github.com/markadelnawar/json-schema-sketch) — the underlying library that infers compact text-form schemas from JSON values.
+- [`json-schema-sketch-bench`](https://github.com/markadelnawar/json-schema-sketch-bench) — the benchmark harness used to produce the numbers above.
+- [GitHub MCP server](https://github.com/github/github-mcp-server) — the upstream this proxies.
+- [Model Context Protocol](https://modelcontextprotocol.io) — the protocol both speak.

package/dist/cache.js

@@ -0,0 +1,34 @@
+export class ResponseCache {
+    maxSize;
+    store = new Map();
+    counter = 0;
+    constructor(maxSize) {
+        this.maxSize = maxSize;
+    }
+    put(tool, args, response) {
+        this.counter += 1;
+        const id = `gh-${this.counter}-${Math.random().toString(36).slice(2, 8)}`;
+        this.store.set(id, { tool, args, response, createdAt: Date.now() });
+        while (this.store.size > this.maxSize) {
+            const oldest = this.store.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.store.delete(oldest);
+        }
+        return id;
+    }
+    get(id) {
+        return this.store.get(id);
+    }
+    size() {
+        return this.store.size;
+    }
+    list() {
+        return Array.from(this.store.entries()).map(([id, e]) => ({
+            id,
+            tool: e.tool,
+            createdAt: e.createdAt,
+        }));
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAOA,MAAM,OAAO,aAAa;IAIJ;IAHZ,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IACtC,OAAO,GAAG,CAAC,CAAC;IAEpB,YAAoB,OAAe;QAAf,YAAO,GAAP,OAAO,CAAQ;IAAG,CAAC;IAEvC,GAAG,CAAC,IAAY,EAAE,IAAa,EAAE,QAAiB;QAChD,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;QAClB,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QAC1E,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACpE,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;YACtC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAC9C,IAAI,MAAM,KAAK,SAAS;gBAAE,MAAM;YAChC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,IAAI;QACF,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,IAAI;QACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACxD,EAAE;YACF,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,SAAS,EAAE,CAAC,CAAC,SAAS;SACvB,CAAC,CAAC,CAAC;IACN,CAAC;CACF"}

package/dist/const/messages.js

@@ -0,0 +1,20 @@
+export const MSG_MISSING_PAT = "[github-mcp-sketch] GITHUB_PAT is not set. Refusing to start.";
+export const MSG_READY = "[github-mcp-sketch] ready on stdio.";
+export function msgUpstreamConnected(toolCount) {
+    return `[github-mcp-sketch] Connected upstream. ${toolCount} tools available.`;
+}
+export function msgUnknownCacheId(cacheId, available) {
+    const list = available.length === 0 ? "(none)" : available.join(", ");
+    return (`Unknown cache_id "${cacheId}". Available: ${list}. ` +
+        `Call an upstream tool first to populate the cache.`);
+}
+export function wrapSketchResponse(cacheId, schema) {
+    return `cache_id: ${cacheId} (pass to query_response)\n\n${schema}`;
+}
+export function msgPathCommaHint(path) {
+    return (`Path "${path}" contains a comma. Path strings do NOT support comma-separated field selection. ` +
+        `To get multiple fields in one call, pass an array of paths instead: ` +
+        `path=["[*].title","[*].state","[*].user.login"]. Each path is run against the same cached response ` +
+        `and the results are returned together in one tool call.`);
+}
+//# sourceMappingURL=messages.js.map

package/dist/const/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../src/const/messages.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAC1B,+DAA+D,CAAC;AAElE,MAAM,CAAC,MAAM,SAAS,GAAG,qCAAqC,CAAC;AAE/D,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,OAAO,2CAA2C,SAAS,mBAAmB,CAAC;AACjF,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,SAAmB;IACpE,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtE,OAAO,CACL,qBAAqB,OAAO,iBAAiB,IAAI,IAAI;QACrD,oDAAoD,CACrD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,MAAc;IAChE,OAAO,aAAa,OAAO,gCAAgC,MAAM,EAAE,CAAC;AACtE,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,CACL,SAAS,IAAI,mFAAmF;QAChG,sEAAsE;QACtE,qGAAqG;QACrG,yDAAyD,CAC1D,CAAC;AACJ,CAAC"}

package/dist/const/tools.js

@@ -0,0 +1,40 @@
+export const QUERY_RESPONSE_TOOL = {
+    name: "query_response",
+    description: "Extract values from a response cached by a previous tool call.\n\n" +
+        "PATH SYNTAX (per path):\n" +
+        '  "user.login"             → nested key\n' +
+        '  "[0].title"              → array index, then key\n' +
+        '  "[*].title"              → wildcard: title from each array element\n' +
+        '  "items[*].user.login"    → wildcard with nested key\n' +
+        '  ""                       → return the whole cached value\n\n' +
+        "BATCH MULTIPLE FIELDS IN ONE CALL — pass `path` as an array of strings:\n" +
+        '  path: ["[*].title", "[*].state", "[*].user.login"]\n' +
+        "  → returns { results: { \"<path>\": {value,...}, ... } }, one entry per path.\n" +
+        "  Per-path errors are reported in that path's entry; other paths still succeed.\n\n" +
+        "Notes:\n" +
+        "  - Do NOT comma-separate fields inside a single path string. Use the array form.\n" +
+        "  - max_items applies to every wildcard expansion in the batch.\n" +
+        "  - Single string returns the value directly; array returns a results map.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            cache_id: {
+                type: "string",
+                description: "cache_id returned by a previous proxy tool call.",
+            },
+            path: {
+                oneOf: [
+                    { type: "string" },
+                    { type: "array", items: { type: "string" }, minItems: 1 },
+                ],
+                description: 'Single path string OR array of path strings. Examples: "user.login" | "[*].title" | ["[*].title", "[*].state"]. Empty string returns the whole cached value. No commas inside a path.',
+            },
+            max_items: {
+                type: "number",
+                description: "OPTIONAL cap on items returned per wildcard expansion. Default unlimited — returns all items. Set this only when you specifically want a sample (e.g. \"give me the first 5 titles to scan\"). Applies to every path in a batch.",
+            },
+        },
+        required: ["cache_id", "path"],
+    },
+};
+//# sourceMappingURL=tools.js.map

package/dist/const/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/const/tools.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,mBAAmB,GAAS;IACvC,IAAI,EAAE,gBAAgB;IACtB,WAAW,EACT,oEAAoE;QACpE,2BAA2B;QAC3B,2CAA2C;QAC3C,sDAAsD;QACtD,wEAAwE;QACxE,yDAAyD;QACzD,gEAAgE;QAChE,2EAA2E;QAC3E,wDAAwD;QACxD,kFAAkF;QAClF,qFAAqF;QACrF,UAAU;QACV,qFAAqF;QACrF,mEAAmE;QACnE,4EAA4E;IAC9E,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,QAAQ,EAAE;gBACR,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,kDAAkD;aAChE;YACD,IAAI,EAAE;gBACJ,KAAK,EAAE;oBACL,EAAE,IAAI,EAAE,QAAQ,EAAE;oBAClB,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE;iBAC1D;gBACD,WAAW,EACT,uLAAuL;aAC1L;YACD,SAAS,EAAE;gBACT,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,kOAAkO;aACrO;SACF;QACD,QAAQ,EAAE,CAAC,UAAU,EAAE,MAAM,CAAC;KAC/B;CACF,CAAC"}

package/dist/metrics.js

@@ -0,0 +1,45 @@
+import { appendFileSync, existsSync, writeFileSync } from "node:fs";
+import { get_encoding } from "tiktoken";
+const HEADER = "timestamp,tool,cache_id,raw_bytes,sketched_bytes,bytes_saved_pct,raw_tokens,sketched_tokens,tokens_saved_pct\n";
+let encoder = null;
+function getEncoder() {
+    if (!encoder)
+        encoder = get_encoding("cl100k_base");
+    return encoder;
+}
+export function freeEncoder() {
+    encoder?.free();
+    encoder = null;
+}
+function countTokens(text) {
+    return getEncoder().encode(text).length;
+}
+function byteLen(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+function pct(saved, raw) {
+    if (raw <= 0)
+        return 0;
+    return Math.round((saved / raw) * 1000) / 10;
+}
+export function recordMetric(csvPath, row) {
+    if (!existsSync(csvPath))
+        writeFileSync(csvPath, HEADER);
+    const rawBytes = byteLen(row.rawText);
+    const sketchedBytes = byteLen(row.sketchedText);
+    const rawTokens = countTokens(row.rawText);
+    const sketchedTokens = countTokens(row.sketchedText);
+    const line = [
+        new Date().toISOString(),
+        row.tool,
+        row.cacheId,
+        rawBytes,
+        sketchedBytes,
+        pct(rawBytes - sketchedBytes, rawBytes),
+        rawTokens,
+        sketchedTokens,
+        pct(rawTokens - sketchedTokens, rawTokens),
+    ].join(",");
+    appendFileSync(csvPath, line + "\n");
+}
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACpE,OAAO,EAAE,YAAY,EAAiB,MAAM,UAAU,CAAC;AAEvD,MAAM,MAAM,GACV,gHAAgH,CAAC;AAEnH,IAAI,OAAO,GAAoB,IAAI,CAAC;AAEpC,SAAS,UAAU;IACjB,IAAI,CAAC,OAAO;QAAE,OAAO,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC;IACpD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,OAAO,EAAE,IAAI,EAAE,CAAC;IAChB,OAAO,GAAG,IAAI,CAAC;AACjB,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,OAAO,UAAU,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;AAC1C,CAAC;AAED,SAAS,OAAO,CAAC,IAAY;IAC3B,OAAO,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACzC,CAAC;AAED,SAAS,GAAG,CAAC,KAAa,EAAE,GAAW;IACrC,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACvB,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;AAC/C,CAAC;AASD,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,GAAc;IAC1D,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAEzD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAChD,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3C,MAAM,cAAc,GAAG,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAErD,MAAM,IAAI,GAAG;QACX,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACxB,GAAG,CAAC,IAAI;QACR,GAAG,CAAC,OAAO;QACX,QAAQ;QACR,aAAa;QACb,GAAG,CAAC,QAAQ,GAAG,aAAa,EAAE,QAAQ,CAAC;QACvC,SAAS;QACT,cAAc;QACd,GAAG,CAAC,SAAS,GAAG,cAAc,EAAE,SAAS,CAAC;KAC3C,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEZ,cAAc,CAAC,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC,CAAC;AACvC,CAAC"}

package/dist/server.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+import { config as loadEnv } from "dotenv";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { ResponseCache } from "./cache.js";
+import { sketchValue, queryValue } from "./sketch.js";
+import { recordMetric, freeEncoder } from "./metrics.js";
+import { UpstreamMcp } from "./upstream.js";
+import { QUERY_RESPONSE_TOOL } from "./const/tools.js";
+import { MSG_MISSING_PAT, MSG_READY, msgUpstreamConnected, msgUnknownCacheId, msgPathCommaHint, wrapSketchResponse, } from "./const/messages.js";
+import { extractTextFromUpstream, tryParseJson } from "./util/parse.js";
+import { buildToolError } from "./util/errors.js";
+import { registerShutdown } from "./util/shutdown.js";
+loadEnv();
+const PAT = process.env.GITHUB_PAT;
+const UPSTREAM_URL = process.env.UPSTREAM_MCP_URL ?? "https://api.githubcopilot.com/mcp";
+const CACHE_SIZE = Number(process.env.CACHE_SIZE ?? 50);
+const METRICS_CSV = process.env.METRICS_CSV ?? null;
+if (!PAT) {
+    console.error(MSG_MISSING_PAT);
+    process.exit(1);
+}
+async function main() {
+    const upstream = new UpstreamMcp(UPSTREAM_URL, PAT);
+    await upstream.connect();
+    const upstreamTools = await upstream.listTools();
+    console.error(msgUpstreamConnected(upstreamTools.length));
+    const cache = new ResponseCache(CACHE_SIZE);
+    const server = new Server({ name: "github-mcp-sketch", version: "0.0.1" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        // Pass upstream tool descriptions through unchanged. The schema-sketch
+        // behavior teaches itself on the first call: every response wraps with
+        // `cache_id: gh-N-xxx (pass to query_response)\n\n<schema>`, and the
+        // `query_response` tool's own description explains how to use it.
+        // Appending a per-tool NOTE here would cost ~60 tokens × every upstream
+        // tool, which on heavy tool sets is several thousand wasted input tokens
+        // per request — the very thing the proxy is supposed to save.
+        const tools = upstreamTools.map((t) => ({ ...t }));
+        tools.push(QUERY_RESPONSE_TOOL);
+        return { tools };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const toolName = req.params.name;
+        const args = req.params.arguments;
+        if (toolName === "query_response") {
+            const argsObj = (args ?? {});
+            const cacheId = String(argsObj.cache_id ?? "");
+            const maxItems = typeof argsObj.max_items === "number" ? argsObj.max_items : Infinity;
+            const entry = cache.get(cacheId);
+            if (!entry) {
+                return buildToolError(msgUnknownCacheId(cacheId, cache.list().map((e) => e.id)));
+            }
+            const pathInput = argsObj.path;
+            const isBatch = Array.isArray(pathInput);
+            const paths = isBatch
+                ? pathInput.map((p) => String(p))
+                : [String(pathInput ?? "")];
+            const resolveOne = (p) => {
+                const r = queryValue(entry.response, p, maxItems);
+                if (!r.ok) {
+                    const msg = p.includes(",")
+                        ? `${msgPathCommaHint(p)}\n\nOriginal parser error: ${r.error}`
+                        : r.error;
+                    return { error: msg };
+                }
+                const out = { value: r.value };
+                const returned = Array.isArray(r.value) ? r.value.length : 0;
+                if (r.totalItems !== undefined && r.totalItems > returned) {
+                    out.totalItems = r.totalItems;
+                }
+                return out;
+            };
+            if (!isBatch) {
+                const single = resolveOne(paths[0]);
+                if ("error" in single)
+                    return buildToolError(single.error);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(single, null, 2) }],
+                };
+            }
+            const results = {};
+            for (const p of paths)
+                results[p] = resolveOne(p);
+            return {
+                content: [{ type: "text", text: JSON.stringify({ results }, null, 2) }],
+            };
+        }
+        const upstreamResult = await upstream.callTool(toolName, args);
+        if (upstreamResult.isError)
+            return upstreamResult;
+        const rawText = extractTextFromUpstream(upstreamResult);
+        if (rawText === null)
+            return upstreamResult;
+        const parsed = tryParseJson(rawText);
+        if (parsed === undefined)
+            return upstreamResult;
+        const schema = sketchValue(parsed);
+        const cacheId = cache.put(toolName, args, parsed);
+        const wrapped = wrapSketchResponse(cacheId, schema);
+        if (METRICS_CSV) {
+            try {
+                recordMetric(METRICS_CSV, {
+                    tool: toolName,
+                    cacheId,
+                    rawText,
+                    sketchedText: wrapped,
+                });
+            }
+            catch (err) {
+                console.error("[github-mcp-sketch] metrics write failed:", err);
+            }
+        }
+        return { content: [{ type: "text", text: wrapped }] };
+    });
+    registerShutdown([
+        async () => {
+            try {
+                await upstream.close();
+            }
+            catch { }
+        },
+        () => freeEncoder(),
+    ]);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(MSG_READY);
+}
+main().catch((err) => {
+    console.error("[github-mcp-sketch] fatal:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/sketch.js

@@ -0,0 +1,9 @@
+import { inferSchema, renderSchema, resolvePath } from "json-schema-sketch";
+export function sketchValue(value) {
+    const node = inferSchema(value);
+    return renderSchema(node);
+}
+export function queryValue(value, path, maxItems) {
+    return resolvePath(value, path, maxItems);
+}
+//# sourceMappingURL=sketch.js.map

package/dist/sketch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sketch.js","sourceRoot":"","sources":["../src/sketch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAG5E,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAChC,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,UAAU,CACxB,KAAc,EACd,IAAY,EACZ,QAAgB;IAEhB,OAAO,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC5C,CAAC"}

package/dist/upstream.js

@@ -0,0 +1,32 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+export class UpstreamMcp {
+    client;
+    transport;
+    constructor(url, pat) {
+        this.transport = new StreamableHTTPClientTransport(new URL(url), {
+            requestInit: {
+                headers: { Authorization: `Bearer ${pat}` },
+            },
+        });
+        this.client = new Client({ name: "github-mcp-sketch", version: "0.0.1" }, { capabilities: {} });
+    }
+    async connect() {
+        await this.client.connect(this.transport);
+    }
+    async close() {
+        await this.client.close();
+    }
+    async listTools() {
+        const result = await this.client.listTools();
+        return result.tools;
+    }
+    async callTool(name, args) {
+        const result = await this.client.callTool({
+            name,
+            arguments: (args ?? {}),
+        });
+        return result;
+    }
+}
+//# sourceMappingURL=upstream.js.map

package/dist/upstream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream.js","sourceRoot":"","sources":["../src/upstream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AASnG,MAAM,OAAO,WAAW;IACd,MAAM,CAAS;IACf,SAAS,CAAgC;IAEjD,YAAY,GAAW,EAAE,GAAW;QAClC,IAAI,CAAC,SAAS,GAAG,IAAI,6BAA6B,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,EAAE;YAC/D,WAAW,EAAE;gBACX,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,GAAG,EAAE,EAAE;aAC5C;SACF,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CACtB,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,OAAO,EAAE,EAC/C,EAAE,YAAY,EAAE,EAAE,EAAE,CACrB,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,SAAS;QACb,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QAC7C,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,IAAY,EAAE,IAAa;QACxC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;YACxC,IAAI;YACJ,SAAS,EAAE,CAAC,IAAI,IAAI,EAAE,CAA4B;SACnD,CAAC,CAAC;QACH,OAAO,MAA4B,CAAC;IACtC,CAAC;CACF"}

package/dist/util/errors.js

@@ -0,0 +1,7 @@
+export function buildToolError(message) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: message }],
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/util/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/util/errors.ts"],"names":[],"mappings":"AAMA,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;KAC3C,CAAC;AACJ,CAAC"}

package/dist/util/parse.js

@@ -0,0 +1,19 @@
+export function extractTextFromUpstream(result) {
+    if (!result.content || !Array.isArray(result.content))
+        return null;
+    const texts = result.content
+        .filter((c) => c.type === "text" && typeof c.text === "string")
+        .map((c) => c.text);
+    if (texts.length === 0)
+        return null;
+    return texts.join("\n");
+}
+export function tryParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=parse.js.map

package/dist/util/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/util/parse.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,uBAAuB,CAAC,MAA0B;IAChE,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IACnE,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO;SACzB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC;SAC9D,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAc,CAAC,CAAC;IAChC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/util/shutdown.js

@@ -0,0 +1,29 @@
+export function registerShutdown(handlers) {
+    let shuttingDown = false;
+    const run = async (reason, exitCode) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.error(`[github-mcp-sketch] shutting down (${reason})`);
+        for (const h of handlers) {
+            try {
+                await h();
+            }
+            catch (err) {
+                console.error("[github-mcp-sketch] shutdown handler error:", err);
+            }
+        }
+        process.exit(exitCode);
+    };
+    process.on("SIGINT", () => void run("SIGINT", 0));
+    process.on("SIGTERM", () => void run("SIGTERM", 0));
+    process.on("uncaughtException", (err) => {
+        console.error("[github-mcp-sketch] uncaughtException:", err);
+        void run("uncaughtException", 1);
+    });
+    process.on("unhandledRejection", (err) => {
+        console.error("[github-mcp-sketch] unhandledRejection:", err);
+        void run("unhandledRejection", 1);
+    });
+}
+//# sourceMappingURL=shutdown.js.map

package/dist/util/shutdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.js","sourceRoot":"","sources":["../../src/util/shutdown.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,gBAAgB,CAAC,QAA2B;IAC1D,IAAI,YAAY,GAAG,KAAK,CAAC;IAEzB,MAAM,GAAG,GAAG,KAAK,EAAE,MAAc,EAAE,QAAgB,EAAE,EAAE;QACrD,IAAI,YAAY;YAAE,OAAO;QACzB,YAAY,GAAG,IAAI,CAAC;QACpB,OAAO,CAAC,KAAK,CAAC,sCAAsC,MAAM,GAAG,CAAC,CAAC;QAC/D,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,MAAM,CAAC,EAAE,CAAC;YACZ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,KAAK,CAAC,6CAA6C,EAAE,GAAG,CAAC,CAAC;YACpE,CAAC;QACH,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACzB,CAAC,CAAC;IAEF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC;IAClD,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC;IACpD,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,GAAG,EAAE,EAAE;QACtC,OAAO,CAAC,KAAK,CAAC,wCAAwC,EAAE,GAAG,CAAC,CAAC;QAC7D,KAAK,GAAG,CAAC,mBAAmB,EAAE,CAAC,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,GAAG,EAAE,EAAE;QACvC,OAAO,CAAC,KAAK,CAAC,yCAAyC,EAAE,GAAG,CAAC,CAAC;QAC9D,KAAK,GAAG,CAAC,oBAAoB,EAAE,CAAC,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "github-mcp-sketch",
+  "version": "0.1.0",
+  "description": "MCP proxy in front of the GitHub MCP that returns inferred schemas instead of raw JSON, plus a query_response tool for drilling back into cached values. Built on json-schema-sketch.",
+  "type": "module",
+  "main": "dist/server.js",
+  "bin": {
+    "github-mcp-sketch": "dist/server.js"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/server.js",
+    "dev": "tsx src/server.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "anthropic",
+    "claude",
+    "claude-code",
+    "github",
+    "github-mcp",
+    "json-schema",
+    "token-efficiency",
+    "llm",
+    "agent"
+  ],
+  "author": "Mark Adel Nawar",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/markadelnawar/github-mcp-sketch.git"
+  },
+  "bugs": {
+    "url": "https://github.com/markadelnawar/github-mcp-sketch/issues"
+  },
+  "homepage": "https://github.com/markadelnawar/github-mcp-sketch#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "json-schema-sketch": "^0.1.1",
+    "tiktoken": "^1.0.20",
+    "dotenv": "^16.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}