Skip to main content
Glama
deenesjakoruzh
nihar777

apollo-cache-copilot

by nihar777
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

apollo-cache-copilot

CI TypeScript Tested with Vitest License: ISC MCP

用于诊断 Apollo InMemoryCache 规范化缺陷的 AI copilot 和 MCP 服务器——专为 React Native 构建，因为那里没有 Apollo DevTools。

问题

Apollo Client 会将每个结果规范化为 __typename:id 实体的扁平映射，并将交叉引用存储为 { "__ref": "Type:id" } 指针。这种规范化在写入时不可见，只在读取时才会失败——通常是在离导致问题的 mutation 很远的屏幕上。有三类缺陷最为常见，而且这三类都是静默的：

缺陷

Apollo 的行为

症状

孤立指针 —— { __ref: "User:99" }，但存储中没有 User:99

对该字段返回 undefined

空白行，不抛错

缺少 __typename / id

无法计算缓存键，将对象内联存储

渲染正常，但第二次写入时开始分叉

类型/键漂移 —— keyFields 与服务器负载不一致

同一逻辑实体出现在两个键下

列表项重复，读取过期数据

React Native 会让每一类问题都变得更糟：

  • 没有 Apollo DevTools。 浏览器扩展是主要的缓存调试工具，但在 RN 上并不存在。退而求其次的做法是 console.log(JSON.stringify(client.cache.extract()))，然后靠肉眼阅读数 MB 的文本块。

  • 持久化缓存。 apollo3-cache-persist + AsyncStorage 意味着损坏的缓存在应用重启后依然存在——顽固且只会在用户设备上复现。

  • 离线优先的 mutation。 乐观响应按设计写入部分实体，而这正是触发缺陷 1 和 2 的形态。

  • 长时间会话。 移动应用会常驻数天，因此漂移累积的时间远比浏览器标签页长。

Related MCP server: mcp-rn-devtools

解决方案

检测是确定性的。解释是模型的工作。

  1. 缓存分析器，遍历 cache.extract() 的输出并报告带有精确路径的结构性缺陷（User:1.avatar → Avatar:99）。纯图遍历——不涉及模型，不靠猜测，可在 10MB 快照上运行。

  2. MCP 服务器，将该分析器暴露给开发者正在使用的任何 agent。agent 只请求发现结果和相关的子图，因此无需在上下文中持有整个缓存。

诊断从“粘贴 10MB 文本块然后眯眼细看”变成了一次对话。

架构

flowchart TD
    subgraph client["MCP client — Claude Desktop / Cursor"]
        A["Agent (the LLM)"]
    end

    subgraph server["apollo-cache-copilot (stdio process)"]
        T["StdioServerTransport<br/>apollo-copilot mcp"]
        R["Tool registry<br/>inspect_dangling_refs<br/>patch_cache<br/>diagnose_cache_graph"]
        Z["Zod schemas<br/>parse in, shape out"]

        subgraph g["cacheAgentGraph (LangGraph, LLM-free)"]
            I["inspectorNode<br/>writes findings"]
            RE["reasonerNode<br/>writes proposedPatches"]
            P["patcherNode<br/>writes narration"]
            I --> RE --> P
        end

        TOOL1["inspectDanglingRefs()<br/>pure, on a snapshot"]
        TOOL2["patchCache()<br/>modify / evict / gc"]

        T --> R --> Z --> I
        I -.->|calls| TOOL1
        P -.->|plans for| TOOL2
    end

    A <-->|"JSON-RPC 2.0 over stdio"| T
    TOOL1 --- CACHE["cache.extract() snapshot"]
    TOOL2 --- LIVE["live ApolloCache"]

ASCII，同样的内容：

  MCP client (Claude Desktop, Cursor, any stdio client)
        │  JSON-RPC 2.0  ▲
        ▼   over stdio   │  stdout IS the protocol channel —
  ┌─────────────────────────────────┐   all logs go to stderr
  │ StdioServerTransport            │
  ├─────────────────────────────────┤
  │ tools: inspect_dangling_refs    │  read-only
  │        patch_cache              │  mutating (dryRun available)
  │        diagnose_cache_graph     │  read-only, plans only
  ├─────────────────────────────────┤
  │ Zod schemas — parse at the edge │
  └───────────────┬─────────────────┘
                  ▼
  ┌─────────────────────────────────────────────────────┐
  │  cacheAgentGraph  (LangGraph, deliberately LLM-free)│
  │                                                     │
  │  INSPECTOR ──────► REASONER ──────► PATCHER         │
  │  walks the store   maps findings    narrates the     │
  │  → findings[]      → patch ops      plan             │
  │      │                  │                            │
  │      │ owns `findings`  │ owns `proposedPatches`      │
  └──────┼──────────────────┼────────────────────────────┘
         ▼                  ▼
  inspectDanglingRefs()   patchCache()
  pure, on a snapshot     cache.modify / evict / gc on a live cache

每个图节点只拥有一个状态通道——检查器写入 findings，推理器写入 proposedPatches，修补器写入 messages。只有 messages 会累积；重新运行某个节点会重新分析同一缓存，因此如果在其他地方追加，第二次运行时就会重复每一条发现。

为什么图中没有 LLM？ 这个 copilot 检测到的每个缺陷都有机械式的修复方法（修剪指针、驱逐孤立实体）。模型会给一个 switch 已经能正确做出的决策增加延迟、成本和不确定性。图的价值在于编排；模型存在于 MCP 客户端中，在那里它将发现与写入它的 mutation 或 fragment 关联起来。

安装

npm install @indianic/apollo-cache-copilot
# or, from a checkout
npm install && npm run build

需要 Node.js ≥ 20（vitest 4 和 @langchain/core 都要求它；CI 覆盖 20 和 22）。@apollo/client（v3.8+ 或 v4）、react 和 react-native 是 peer 依赖——该包使用你应用中的副本。

库用法

仅支持 ESM。该包自带类型声明。

inspectDanglingRefs —— 审计快照

纯函数且同步。接收 cache.extract() 的输出，返回发现结果 + 统计信息。

import { inspectDanglingRefs } from 'apollo-cache-copilot';

const { findings, stats } = inspectDanglingRefs({
  cache: client.cache.extract(),
  // all optional:
  rootIds: ['ROOT_QUERY', 'ROOT_MUTATION'], // reachability roots
  includeUnreachable: true,                  // report gc candidates
  includeNormalizationGaps: true,            // report un-keyable inline objects
});

console.log(stats);
// { entityCount: 4, refCount: 3, danglingCount: 1, unreachableCount: 1 }

for (const f of findings) {
  console.log(f.kind, f.path, f.danglingRef ?? '');
  // ORPHANED_REF  User:1.avatar  Avatar:99
  // UNREACHABLE_ENTITY  Post:7
}

发现类型：ORPHANED_REF、UNREACHABLE_ENTITY、MISSING_TYPENAME、MISSING_ID。每条发现都带有精确的缓存路径。

patchCache —— 对实时缓存应用修复

操作是声明式描述符，因此可以安全地经过 JSON 传输；该工具会将它们还原为 cache.modify 所需的函数。操作是有序的，失败会被记录而不是抛出，这样批次中间的一个坏键不会让缓存停留在半修补状态。

import { patchCache } from 'apollo-cache-copilot';

const { dryRun, results, collected } = patchCache(client.cache, {
  operations: [
    // drop dangling refs from a list field
    { type: 'modify', id: 'User:1', fields: { posts: { action: 'PRUNE_DANGLING_REFS' } } },
    // delete / invalidate / overwrite a field
    { type: 'modify', id: 'User:1', fields: { avatar: { action: 'DELETE' } } },
    { type: 'modify', id: 'User:1', fields: { bio: { action: 'SET', value: 'unset' } } },
    // evict an entity, or one field of it
    { type: 'evict', id: 'Post:7' },
    { type: 'evict', id: 'ROOT_QUERY', fieldName: 'user', args: { id: '1' } },
  ],
  gc: true,       // run cache.gc() once, after everything lands
  dryRun: false,  // true = validate only, cache untouched
});

results.forEach((r) => console.log(r.changed, r.error ?? ''));
console.log('collected:', collected); // keys gc() removed

字段操作：DELETE、INVALIDATE、SET（带 value）、PRUNE_DANGLING_REFS。

cacheAgentGraph —— 检查 → 推理 → 规划

编译后的 LangGraph。返回发现结果、它将应用的修补操作以及逐步说明。它从不修改任何内容——在你审查完 proposedPatches 后，将它们交给 patchCache。

import { cacheAgentGraph } from 'apollo-cache-copilot';

const state = await cacheAgentGraph.invoke({ cacheState: client.cache.extract() });

state.messages.forEach((m) => console.log(String(m.content)));
// 2 findings: 1 orphaned ref, 1 unreachable entity.
// ...

// Review, then apply:
patchCache(client.cache, { operations: state.proposedPatches });

还导出了：buildCacheAgentGraph()（未编译的构建器）、各个节点 inspectorNode / reasonerNode / patcherNode、CacheAgentAnnotation、每个 Zod schema（InspectDanglingRefsInputSchema、PatchCacheInputSchema、……）及其推断类型，以及 MCP 接口（createServer、startStdioServer、runInspectDanglingRefs、runPatchCache、runDiagnoseCacheGraph）。

CLI 用法

apollo-copilot [mcp]          Start the stdio MCP server (default when no args)
apollo-copilot inspect FILE   Diagnose a JSON cache snapshot and print findings

apollo-copilot inspect <file>

从你的应用中导出缓存，然后读取它：

// in the RN app
console.log(JSON.stringify(client.cache.extract()));
npx -y -p @indianic/apollo-cache-copilot apollo-copilot inspect ./cache-snapshot.json
━━ Cache Diagnostic ━━

Entities: 4 | Refs: 3 | Dangling: 1 | Unreachable: 1

⚠  ORPHANED_REF (1)
   • User:1.avatar → Avatar:99
     Points at "Avatar:99", which is not in the cache. Reads here return undefined.

🗑  UNREACHABLE_ENTITY (1)
   • Post:7
     No root reaches this entity; cache.gc() would collect it.

干净的缓存会输出 ✓ Cache is clean: no findings.

退出码：0 成功，1 意外失败，2 输入错误（文件缺失、文件不可读、JSON 无效、未知命令）。

apollo-copilot mcp

在 stdio 上启动 MCP 服务器并阻塞。只有当 MCP 客户端拥有该进程时才有用——见下文。apollo-copilot-mcp 是同一功能的旧别名。

stdout 是协议通道。 服务器只向 stdout 写入 JSON-RPC；所有诊断信息都输出到 stderr。绝不要在此路径中添加 console.log。

MCP 配置

暴露的工具

工具

输入

行为

inspect_dangling_refs

cache，可选 rootIds / includeUnreachable / includeNormalizationGaps

只读。返回 findings + stats。

diagnose_cache_graph

cache

只读。运行完整图。返回 findings、proposedPatches、narration。仅做规划。

patch_cache

cache、operations、gc、dryRun

将快照恢复到一次性的 InMemoryCache 中，进行修补，返回 results + 重新提取的 cache。

patch_cache 携带快照，因为 stdio 服务器没有实时缓存可以交给修补器——只有 JSON。将返回的 cache 与你的缓存进行 diff，或者用 client.cache.restore() 恢复它。

每个工具都返回人类可读的摘要行和机器可读的 structuredContent，因此不理解结构化输出的客户端仍然能获得 JSON。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "apollo-cache-copilot": {
      "command": "npx",
      "args": ["-y", "-p", "@indianic/apollo-cache-copilot", "apollo-copilot", "mcp"]
    }
  }
}

从本地检出开始——先构建（npm run build），然后用绝对路径指向 bin：

{
  "mcpServers": {
    "apollo-cache-copilot": {
      "command": "node",
      "args": ["/absolute/path/to/apollo-cache-copilot/bin/apollo-copilot.js", "mcp"]
    }
  }
}

重启 Claude Desktop。这三个工具会出现在工具菜单下。

Cursor

项目中的 .cursor/mcp.json（或用于所有项目的 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "apollo-cache-copilot": {
      "command": "npx",
      "args": ["-y", "-p", "@indianic/apollo-cache-copilot", "apollo-copilot", "mcp"]
    }
  }
}

本地检出：

{
  "mcpServers": {
    "apollo-cache-copilot": {
      "command": "node",
      "args": ["${workspaceFolder}/bin/apollo-copilot.js", "mcp"]
    }
  }
}

然后 Cursor → Settings → MCP → 确认服务器是绿色状态。

然后直接提问

“这是我的缓存快照——为什么个人资料页上的头像一片空白？”

agent 会调用 diagnose_cache_graph，得到 User:1.avatar → Avatar:99 以及建议的 PRUNE_DANGLING_REFS，并将其与那个只写了引用而没有实体内容的 mutation 关联起来。

开发

npm install
npm run build      # tsc -> dist/  (run first: typecheck and tests import dist)
npm run typecheck  # tsc --noEmit -p tsconfig.test.json (includes tests)
npm test           # vitest run

tsconfig.json 用于构建，并排除了 __tests__ / __mocks__，因此发布的包只包含工具。tsconfig.test.json 对所有内容进行类型检查，但不产生任何输出。

成功指标

#

指标

目标

1

在测试夹具套件上的检测召回率

100%——每个注入的缺陷都被发现

2

健康快照上的误报

0

3

分析器在 10MB extract() 上的运行时间

< 1s

4

带有精确缓存路径的发现

100%

5

开发者从症状到定位根因的时间

< 5 分钟（而以前是数小时）

6

每次诊断发送给模型的 token 数

< 10k——发现结果 + 子图，绝不是整个缓存

许可证

ISC——见 LICENSE。

Available Tools

3 tools
diagnose_cache_graphDiagnose cache graphA
Read-only

Run the full inspect -> reason -> plan graph over a serialized cache. Returns findings, the proposed patch operations (feed them to patch_cache), and per-step narration. Plans only; never mutates.

ParametersJSON Schema
NameRequiredDescriptionDefault
cacheYesThe full serialized cache, exactly as returned by `cache.extract()`. Keys are cache IDs (e.g. "ROOT_QUERY", "User:1"); values are that entity's stored fields, which may contain `{ "__ref": "<cache id>" }` pointers to other entries in this same object.

Output Schema

ParametersJSON Schema
NameRequiredDescription
findingsYesEvery defect the inspector found in `cache`.
narrationYes
proposedPatchesYesMechanically-derived fixes for the fixable findings, ready to pass to patch_cache as-is.

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare readOnlyHint=true, and the description reinforces this with 'Plans only; never mutates.' It adds useful behavioral context about what the tool does not do and how its output should be consumed, going beyond the structured annotation without contradicting it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences deliver the pipeline, the return value, the downstream consumer, and the side-effect guarantee. Every phrase earns its place and the most important behavioral constraint is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with a fully documented schema and an output schema, the description is complete: it names the inputs, outputs, downstream action, and non-mutating behavior. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides 100% coverage, including a detailed description of the cache object and its structure. The tool description does not need to restate parameter details; the schema carries the semantic weight, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Run the full inspect -> reason -> plan graph over a serialized cache') and clearly differentiates itself from the sibling tools by describing its broader pipeline. It also states what it returns, making its role unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when this tool fits: it produces patch operations that should be fed to patch_cache, and it is a planning-only step. It does not explicitly state when to prefer it over inspect_dangling_refs, but the pipeline framing and output-to-patch_cache relationship make the usage context clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

inspect_dangling_refsInspect dangling refsA
Read-only

Audit a serialized Apollo InMemoryCache (cache.extract() output) for dangling __refs, unreachable entities, and objects Apollo could not normalize. Read-only.

ParametersJSON Schema
NameRequiredDescriptionDefault
cacheYesThe full serialized cache, exactly as returned by `cache.extract()`. Keys are cache IDs (e.g. "ROOT_QUERY", "User:1"); values are that entity's stored fields, which may contain `{ "__ref": "<cache id>" }` pointers to other entries in this same object.
rootIdsNoCache IDs to treat as reachability roots for the UNREACHABLE_ENTITY check, e.g. ["ROOT_QUERY"]. Omit to use every one of ROOT_QUERY / ROOT_MUTATION / ROOT_SUBSCRIPTION that is present in `cache`. Has no effect on ORPHANED_REF or normalization-gap findings.
includeUnreachableNoInclude UNREACHABLE_ENTITY findings for entities no root can reach (candidates `cache.gc()` would collect). Set false to skip reachability analysis and only check refs/normalization.
includeNormalizationGapsNoInclude MISSING_TYPENAME / MISSING_ID findings for inline (non-entity) objects that Apollo could not normalize because they lack a `__typename` or an `id`/`_id` field.

Output Schema

ParametersJSON Schema
NameRequiredDescription
statsYesAggregate counts over the whole cache, independent of the findings list.
findingsYesEvery defect found, in walk order.

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint, and the description repeats 'Read-only.' It adds the scope of audit findings but no additional behavioral context such as error behavior, performance implications, or what the tool does not inspect. With the safety profile already covered by annotations, this is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences totaling 19 words. It front-loads the verb, resource, and primary finding types, and 'Read-only' is a harmless, minimal redundancy with the annotation. Every word contributes to understanding what the tool does.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 4 parameters, 2 siblings, and subtle optional-parameter interactions, but the input schema is exceptionally detailed and an output schema exists, so the short description is sufficient for invocation. The main completeness gap is the lack of an explicit decision rule versus diagnose_cache_graph, preventing a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with detailed parameter documentation for cache, rootIds, includeUnreachable, and includeNormalizationGaps, including defaults and effects on findings. The description itself adds no parameter-level detail beyond the cache.extract() context, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with the specific verb 'Audit' and names the exact resource: a serialized Apollo InMemoryCache from cache.extract(). It then enumerates the three distinct finding categories (dangling __refs, unreachable entities, normalization gaps), which makes the tool's scope precise and differentiates it from the write-oriented patch_cache and the broader-sounding diagnose_cache_graph.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: use this when you have cache.extract() output and need to audit for ref/reachability/normalization issues. However, there is no explicit when-to-use versus alternatives, no exclusions, and no routing to sibling tools such as diagnose_cache_graph. The context is clear but the guidance is not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

patch_cachePatch cacheA
Idempotent

Apply declarative repairs (modify / evict, optional gc) to a serialized cache and return the patched store. Set dryRun to validate the operations without changing anything.

ParametersJSON Schema
NameRequiredDescriptionDefault
gcNoRun `cache.gc()` once after all operations land, to collect anything the patches orphaned.
cacheYesThe full serialized cache, exactly as returned by `cache.extract()`. Keys are cache IDs (e.g. "ROOT_QUERY", "User:1"); values are that entity's stored fields, which may contain `{ "__ref": "<cache id>" }` pointers to other entries in this same object.
dryRunNoValidate `operations` and report what would happen without mutating the cache.
operationsYesOne or more modify/evict operations to apply, in order.

Output Schema

ParametersJSON Schema
NameRequiredDescription
cacheYesThe store after the operations landed. Unchanged when `dryRun` is true.
dryRunYesEchoes the request's dryRun — true means the cache was not actually touched.
resultsYesOne result per input operation, in the same order.
collectedYesCache keys removed by the trailing `gc()`, when it ran.

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=false and idempotentHint=true, and the description adds meaningful behavioral context beyond those flags: it explicitly states that dryRun validates without mutating the cache, that the modified store is returned, and that gc is optional. This goes beyond what the annotations alone convey, while not contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler. The core action is front-loaded, and the dryRun safety note earns its place as a critical usage caveat. It is appropriately sized for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the very rich input and output schemas, the description only needs to establish the operation intent, the mutating nature, and the dryRun flow, which it does. The main missing element is explicit guidance on when to choose this tool over the siblings, but the schema and annotations cover most invocation details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already thoroughly documents each parameter and nested operation shape. The description mentions modify/evict and dryRun, but it does not add parameter-level meaning beyond what the schema provides. The baseline of 3 applies because the schema carries the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool applies declarative repairs (modify/evict, optional gc) to a serialized cache and returns the patched store. The specific verb 'apply' plus the resource 'serialized cache' and operation types distinguish it from the sibling tools inspect_dangling_refs and diagnose_cache_graph, which are non-mutating inspection tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for mutating a serialized cache and mentions dryRun for validation, but it gives no explicit guidance on when to use patch_cache versus the sibling tools. No exclusion criteria or alternative routing is provided, so an agent must infer the appropriate context from the tool name and sibling names alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.2
    • Changeddiagnose_cache_graph8 fields changed
      • addedInput schema / properties / cache / additionalProperties / description
        Added value: +"One normalized store entry: the raw field/value map Apollo keeps under a single cache key."
      • addedInput schema / properties / cache / description
        Added value: +"The full serialized cache, exactly as returned by `cache.extract()`. Keys are cache IDs (e.g. \"ROOT_QUERY\", \"User:1\"); values are that entity's stored fields, which may contain `{ \"__ref\": \"<cache id>\" }` pointers to other entries in this same object."
      • addedOutput schema / properties / findings / description
        Added value: +"Every defect the inspector found in `cache`."
      • addedOutput schema / properties / findings / items / properties / danglingRef / description
        Added value: +"The unresolved cache key the ref pointed at. Only present when kind is ORPHANED_REF."
      • addedOutput schema / properties / findings / items / properties / message / description
        Added value: +"Human-readable explanation of this finding."
      • addedOutput schema / properties / findings / items / properties / path / description
        Added value: +"Dotted path to the defect from its cache key, e.g. \"User:2.posts.1\"."
      • addedOutput schema / properties / proposedPatches / description
        Added value: +"Mechanically-derived fixes for the fixable findings, ready to pass to patch_cache as-is."
      • changedOutput schema / properties / proposedPatches / items / oneOf
        Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "broadcast": {
-        "default": true,
-        "type": "boolean"
-      },
-      "fields": {
-        "additionalProperties": {
-          "oneOf": [
-            {
-              "additionalProperties": false,
-              "properties": {
-                "action": {
-                  "const": "DELETE",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "action"
-              ],
-              "type": "object"
-            },
-            {
-              "additionalProperties": false,
-              "properties": {
-                "action": {
-                  "const": "INVALIDATE",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "action"
-              ],
-              "type": "object"
-            },
-            {
-              "additionalProperties": false,
-              "properties": {
-                "action": {
-                  "const": "SET",
-                  "type": "string"
-                },
-                "value": {}
-              },
-              "required": [
-                "action",
-                "value"
-              ],
-              "type": "object"
-            },
-            {
-              "additionalProperties": false,
-              "properties": {
-                "action": {
-                  "const": "PRUNE_DANGLING_REFS",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "action"
-              ],
-              "type": "object"
-            }
-          ]
-        },
-        "propertyNames": {
-          "type": "string"
-        },
-        "type": "object"
-      },
-      "id": {
-        "default": "ROOT_QUERY",
-        "type": "string"
-      },
-      "optimistic": {
-        "default": false,
-        "type": "boolean"
-      },
-      "type": {
-        "const": "modify",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "id",
-      "fields",
-      "optimistic",
-      "broadcast"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "args": {
-        "additionalProperties": {},
-        "propertyNames": {
-          "type": "string"
-        },
-        "type": "object"
-      },
-      "broadcast": {
-        "default": true,
-        "type": "boolean"
-      },
-      "fieldName": {
-        "type": "string"
-      },
-      "id": {
-        "type": "string"
-      },
-      "type": {
-        "const": "evict",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "id",
-      "broadcast"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "broadcast": {
+        "default": true,
+        "description": "Notify active queries/subscriptions of this change. Set false to patch silently.",
+        "type": "boolean"
+      },
+      "fields": {
+        "additionalProperties": {
+          "oneOf": [
+            {
+              "additionalProperties": false,
+              "description": "Remove this field from the entity entirely.",
+              "properties": {
+                "action": {
+                  "const": "DELETE",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "action"
+              ],
+              "type": "object"
+            },
+            {
+              "additionalProperties": false,
+              "description": "Mark this field stale so Apollo refetches it, without removing or changing its value.",
+              "properties": {
+                "action": {
+                  "const": "INVALIDATE",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "action"
+              ],
+              "type": "object"
+            },
+            {
+              "additionalProperties": false,
+              "description": "Overwrite this field with `value` (any JSON — a scalar, object, or `{ \"__ref\": \"<cache id>\" }`).",
+              "properties": {
+                "action": {
+                  "const": "SET",
+                  "type": "string"
+                },
+                "value": {}
+              },
+              "required": [
+                "action",
+                "value"
+              ],
+              "type": "object"
+            },
+            {
+              "additionalProperties": false,
+              "description": "Drop any `__ref` pointer(s) this field holds that no longer resolve to an entity in the cache. Works on a single ref or a list of refs; refs that still resolve are left untouched.",
+              "properties": {
+                "action": {
+                  "const": "PRUNE_DANGLING_REFS",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "action"
+              ],
+              "type": "object"
+            }
+          ]
+        },
+        "description": "Map of field name -> FieldPatch describing how to change that one field.",
+        "propertyNames": {
+          "type": "string"
+        },
+        "type": "object"
+      },
+      "id": {
+        "default": "ROOT_QUERY",
+        "description": "Cache key of the entity to modify, e.g. \"User:2\". Defaults to \"ROOT_QUERY\" if omitted.",
+        "type": "string"
+      },
+      "optimistic": {
+        "default": false,
+        "description": "Apply against the optimistic layer instead of the base cache. Mirrors `cache.modify`'s option.",
+        "type": "boolean"
+      },
+      "type": {
+        "const": "modify",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "id",
+      "fields",
+      "optimistic",
+      "broadcast"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "args": {
+        "additionalProperties": {},
+        "description": "Field arguments to match when evicting a specific parameterized field (used with `fieldName`).",
+        "propertyNames": {
+          "type": "string"
+        },
+        "type": "object"
+      },
+      "broadcast": {
+        "default": true,
+        "description": "Notify active queries/subscriptions of this eviction. Set false to patch silently.",
+        "type": "boolean"
+      },
+      "fieldName": {
+        "description": "Evict only this one field instead of the whole entity at `id`.",
+        "type": "string"
+      },
+      "id": {
+        "description": "Cache key of the entity to evict, e.g. \"Post:5\".",
+        "type": "string"
+      },
+      "type": {
+        "const": "evict",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "id",
+      "broadcast"
+    ],
+    "type": "object"
+  }
+]
    • Changedinspect_dangling_refs14 fields changed
      • addedInput schema / properties / cache / additionalProperties / description
        Added value: +"One normalized store entry: the raw field/value map Apollo keeps under a single cache key."
      • addedInput schema / properties / cache / description
        Added value: +"The full serialized cache, exactly as returned by `cache.extract()`. Keys are cache IDs (e.g. \"ROOT_QUERY\", \"User:1\"); values are that entity's stored fields, which may contain `{ \"__ref\": \"<cache id>\" }` pointers to other entries in this same object."
      • addedInput schema / properties / includeNormalizationGaps / description
        Added value: +"Include MISSING_TYPENAME / MISSING_ID findings for inline (non-entity) objects that Apollo could not normalize because they lack a `__typename` or an `id`/`_id` field."
      • addedInput schema / properties / includeUnreachable / description
        Added value: +"Include UNREACHABLE_ENTITY findings for entities no root can reach (candidates `cache.gc()` would collect). Set false to skip reachability analysis and only check refs/normalization."
      • addedInput schema / properties / rootIds / description
        Added value: +"Cache IDs to treat as reachability roots for the UNREACHABLE_ENTITY check, e.g. [\"ROOT_QUERY\"]. Omit to use every one of ROOT_QUERY / ROOT_MUTATION / ROOT_SUBSCRIPTION that is present in `cache`. Has no effect on ORPHANED_REF or normalization-gap findings."
      • addedOutput schema / properties / findings / description
        Added value: +"Every defect found, in walk order."
      • addedOutput schema / properties / findings / items / properties / danglingRef / description
        Added value: +"The unresolved cache key the ref pointed at. Only present when kind is ORPHANED_REF."
      • addedOutput schema / properties / findings / items / properties / message / description
        Added value: +"Human-readable explanation of this finding."
      • addedOutput schema / properties / findings / items / properties / path / description
        Added value: +"Dotted path to the defect from its cache key, e.g. \"User:2.posts.1\"."
      • addedOutput schema / properties / stats / description
        Added value: +"Aggregate counts over the whole cache, independent of the findings list."
      • addedOutput schema / properties / stats / properties / danglingCount / description
        Added value: +"Of those refs, how many did not resolve."
      • addedOutput schema / properties / stats / properties / entityCount / description
        Added value: +"Total cache keys in the input."
      • addedOutput schema / properties / stats / properties / refCount / description
        Added value: +"Total `__ref` pointers encountered."
      • addedOutput schema / properties / stats / properties / unreachableCount / description
        Added value: +"Entities no root reaches."
    • Changedpatch_cache15 fields changed
      • addedInput schema / properties / cache / additionalProperties / description
        Added value: +"One normalized store entry: the raw field/value map Apollo keeps under a single cache key."
      • addedInput schema / properties / cache / description
        Added value: +"The full serialized cache, exactly as returned by `cache.extract()`. Keys are cache IDs (e.g. \"ROOT_QUERY\", \"User:1\"); values are that entity's stored fields, which may contain `{ \"__ref\": \"<cache id>\" }` pointers to other entries in this same object."
      • addedInput schema / properties / dryRun / description
        Added value: +"Validate `operations` and report what would happen without mutating the cache."
      • addedInput schema / properties / gc / description
        Added value: +"Run `cache.gc()` once after all operations land, to collect anything the patches orphaned."
      • addedInput schema / properties / operations / description
        Added value: +"One or more modify/evict operations to apply, in order."
      • changedInput schema / properties / operations / items / oneOf
        Previous value: -[
-  {
-    "properties": {
-      "broadcast": {
-        "default": true,
-        "type": "boolean"
-      },
-      "fields": {
-        "additionalProperties": {
-          "oneOf": [
-            {
-              "properties": {
-                "action": {
-                  "const": "DELETE",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "action"
-              ],
-              "type": "object"
-            },
-            {
-              "properties": {
-                "action": {
-                  "const": "INVALIDATE",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "action"
-              ],
-              "type": "object"
-            },
-            {
-              "properties": {
-                "action": {
-                  "const": "SET",
-                  "type": "string"
-                },
-                "value": {}
-              },
-              "required": [
-                "action",
-                "value"
-              ],
-              "type": "object"
-            },
-            {
-              "properties": {
-                "action": {
-                  "const": "PRUNE_DANGLING_REFS",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "action"
-              ],
-              "type": "object"
-            }
-          ]
-        },
-        "propertyNames": {
-          "type": "string"
-        },
-        "type": "object"
-      },
-      "id": {
-        "default": "ROOT_QUERY",
-        "type": "string"
-      },
-      "optimistic": {
-        "default": false,
-        "type": "boolean"
-      },
-      "type": {
-        "const": "modify",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "fields"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "args": {
-        "additionalProperties": {},
-        "propertyNames": {
-          "type": "string"
-        },
-        "type": "object"
-      },
-      "broadcast": {
-        "default": true,
-        "type": "boolean"
-      },
-      "fieldName": {
-        "type": "string"
-      },
-      "id": {
-        "type": "string"
-      },
-      "type": {
-        "const": "evict",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "id"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "properties": {
+      "broadcast": {
+        "default": true,
+        "description": "Notify active queries/subscriptions of this change. Set false to patch silently.",
+        "type": "boolean"
+      },
+      "fields": {
+        "additionalProperties": {
+          "oneOf": [
+            {
+              "description": "Remove this field from the entity entirely.",
+              "properties": {
+                "action": {
+                  "const": "DELETE",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "action"
+              ],
+              "type": "object"
+            },
+            {
+              "description": "Mark this field stale so Apollo refetches it, without removing or changing its value.",
+              "properties": {
+                "action": {
+                  "const": "INVALIDATE",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "action"
+              ],
+              "type": "object"
+            },
+            {
+              "description": "Overwrite this field with `value` (any JSON — a scalar, object, or `{ \"__ref\": \"<cache id>\" }`).",
+              "properties": {
+                "action": {
+                  "const": "SET",
+                  "type": "string"
+                },
+                "value": {}
+              },
+              "required": [
+                "action",
+                "value"
+              ],
+              "type": "object"
+            },
+            {
+              "description": "Drop any `__ref` pointer(s) this field holds that no longer resolve to an entity in the cache. Works on a single ref or a list of refs; refs that still resolve are left untouched.",
+              "properties": {
+                "action": {
+                  "const": "PRUNE_DANGLING_REFS",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "action"
+              ],
+              "type": "object"
+            }
+          ]
+        },
+        "description": "Map of field name -> FieldPatch describing how to change that one field.",
+        "propertyNames": {
+          "type": "string"
+        },
+        "type": "object"
+      },
+      "id": {
+        "default": "ROOT_QUERY",
+        "description": "Cache key of the entity to modify, e.g. \"User:2\". Defaults to \"ROOT_QUERY\" if omitted.",
+        "type": "string"
+      },
+      "optimistic": {
+        "default": false,
+        "description": "Apply against the optimistic layer instead of the base cache. Mirrors `cache.modify`'s option.",
+        "type": "boolean"
+      },
+      "type": {
+        "const": "modify",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "fields"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "args": {
+        "additionalProperties": {},
+        "description": "Field arguments to match when evicting a specific parameterized field (used with `fieldName`).",
+        "propertyNames": {
+          "type": "string"
+        },
+        "type": "object"
+      },
+      "broadcast": {
+        "default": true,
+        "description": "Notify active queries/subscriptions of this eviction. Set false to patch silently.",
+        "type": "boolean"
+      },
+      "fieldName": {
+        "description": "Evict only this one field instead of the whole entity at `id`.",
+        "type": "string"
+      },
+      "id": {
+        "description": "Cache key of the entity to evict, e.g. \"Post:5\".",
+        "type": "string"
+      },
+      "type": {
+        "const": "evict",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "id"
+    ],
+    "type": "object"
+  }
+]
      • addedOutput schema / properties / cache / additionalProperties / description
        Added value: +"One normalized store entry: the raw field/value map Apollo keeps under a single cache key."
      • addedOutput schema / properties / cache / description
        Added value: +"The store after the operations landed. Unchanged when `dryRun` is true."
      • addedOutput schema / properties / collected / description
        Added value: +"Cache keys removed by the trailing `gc()`, when it ran."
      • addedOutput schema / properties / dryRun / description
        Added value: +"Echoes the request's dryRun — true means the cache was not actually touched."
      • addedOutput schema / properties / results / description
        Added value: +"One result per input operation, in the same order."
      • addedOutput schema / properties / results / items / properties / changed / description
        Added value: +"Whether `cache.modify` / `cache.evict` actually changed anything."
      • addedOutput schema / properties / results / items / properties / error / description
        Added value: +"Set when this one operation failed; the rest of the batch still ran."
      • addedOutput schema / properties / results / items / properties / operation / description
        Added value: +"The operation this result is reporting on, echoed back."
      • changedOutput schema / properties / results / items / properties / operation / oneOf
        Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "broadcast": {
-        "default": true,
-        "type": "boolean"
-      },
-      "fields": {
-        "additionalProperties": {
-          "oneOf": [
-            {
-              "additionalProperties": false,
-              "properties": {
-                "action": {
-                  "const": "DELETE",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "action"
-              ],
-              "type": "object"
-            },
-            {
-              "additionalProperties": false,
-              "properties": {
-                "action": {
-                  "const": "INVALIDATE",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "action"
-              ],
-              "type": "object"
-            },
-            {
-              "additionalProperties": false,
-              "properties": {
-                "action": {
-                  "const": "SET",
-                  "type": "string"
-                },
-                "value": {}
-              },
-              "required": [
-                "action",
-                "value"
-              ],
-              "type": "object"
-            },
-            {
-              "additionalProperties": false,
-              "properties": {
-                "action": {
-                  "const": "PRUNE_DANGLING_REFS",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "action"
-              ],
-              "type": "object"
-            }
-          ]
-        },
-        "propertyNames": {
-          "type": "string"
-        },
-        "type": "object"
-      },
-      "id": {
-        "default": "ROOT_QUERY",
-        "type": "string"
-      },
-      "optimistic": {
-        "default": false,
-        "type": "boolean"
-      },
-      "type": {
-        "const": "modify",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "id",
-      "fields",
-      "optimistic",
-      "broadcast"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "args": {
-        "additionalProperties": {},
-        "propertyNames": {
-          "type": "string"
-        },
-        "type": "object"
-      },
-      "broadcast": {
-        "default": true,
-        "type": "boolean"
-      },
-      "fieldName": {
-        "type": "string"
-      },
-      "id": {
-        "type": "string"
-      },
-      "type": {
-        "const": "evict",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "id",
-      "broadcast"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "broadcast": {
+        "default": true,
+        "description": "Notify active queries/subscriptions of this change. Set false to patch silently.",
+        "type": "boolean"
+      },
+      "fields": {
+        "additionalProperties": {
+          "oneOf": [
+            {
+              "additionalProperties": false,
+              "description": "Remove this field from the entity entirely.",
+              "properties": {
+                "action": {
+                  "const": "DELETE",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "action"
+              ],
+              "type": "object"
+            },
+            {
+              "additionalProperties": false,
+              "description": "Mark this field stale so Apollo refetches it, without removing or changing its value.",
+              "properties": {
+                "action": {
+                  "const": "INVALIDATE",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "action"
+              ],
+              "type": "object"
+            },
+            {
+              "additionalProperties": false,
+              "description": "Overwrite this field with `value` (any JSON — a scalar, object, or `{ \"__ref\": \"<cache id>\" }`).",
+              "properties": {
+                "action": {
+                  "const": "SET",
+                  "type": "string"
+                },
+                "value": {}
+              },
+              "required": [
+                "action",
+                "value"
+              ],
+              "type": "object"
+            },
+            {
+              "additionalProperties": false,
+              "description": "Drop any `__ref` pointer(s) this field holds that no longer resolve to an entity in the cache. Works on a single ref or a list of refs; refs that still resolve are left untouched.",
+              "properties": {
+                "action": {
+                  "const": "PRUNE_DANGLING_REFS",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "action"
+              ],
+              "type": "object"
+            }
+          ]
+        },
+        "description": "Map of field name -> FieldPatch describing how to change that one field.",
+        "propertyNames": {
+          "type": "string"
+        },
+        "type": "object"
+      },
+      "id": {
+        "default": "ROOT_QUERY",
+        "description": "Cache key of the entity to modify, e.g. \"User:2\". Defaults to \"ROOT_QUERY\" if omitted.",
+        "type": "string"
+      },
+      "optimistic": {
+        "default": false,
+        "description": "Apply against the optimistic layer instead of the base cache. Mirrors `cache.modify`'s option.",
+        "type": "boolean"
+      },
+      "type": {
+        "const": "modify",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "id",
+      "fields",
+      "optimistic",
+      "broadcast"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "args": {
+        "additionalProperties": {},
+        "description": "Field arguments to match when evicting a specific parameterized field (used with `fieldName`).",
+        "propertyNames": {
+          "type": "string"
+        },
+        "type": "object"
+      },
+      "broadcast": {
+        "default": true,
+        "description": "Notify active queries/subscriptions of this eviction. Set false to patch silently.",
+        "type": "boolean"
+      },
+      "fieldName": {
+        "description": "Evict only this one field instead of the whole entity at `id`.",
+        "type": "string"
+      },
+      "id": {
+        "description": "Cache key of the entity to evict, e.g. \"Post:5\".",
+        "type": "string"
+      },
+      "type": {
+        "const": "evict",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "id",
+      "broadcast"
+    ],
+    "type": "object"
+  }
+]
  2. 3 tool updatesv1.0.0
    • First observeddiagnose_cache_graph
    • First observedinspect_dangling_refs
    • First observedpatch_cache
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4.2/5.0

Scored across 3 tools

Disambiguation4/5

The three tools map to distinct workflow phases: focused read-only audit, planning/diagnosis, and mutation. inspect_dangling_refs and diagnose_cache_graph overlap in that both return findings, but the descriptions clearly differentiate the focused audit from the full inspect-reason-plan pipeline.

Naming Consistency5/5

All tool names follow a consistent snake_case verb_noun pattern: inspect_dangling_refs, patch_cache, diagnose_cache_graph. The verbs and noun objects are clear and predictable.

Tool Count5/5

Three tools is a well-scoped size for a focused Apollo cache repair copilot. Each tool covers a meaningful stage of the workflow—diagnose, plan, patch—without redundancy or bloat.

Completeness5/5

The surface covers the full repair lifecycle: audit problems, generate a plan, and apply/validate repairs with dry-run and optional GC. There are no obvious dead ends for the stated purpose.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers