apollo-cache-copilot
apollo-cache-copilot
ИИ-копilot и MCP-сервер для диагностики дефектов нормализации InMemoryCache в Apollo — создан для React Native, где Apollo DevTools не существует.
Проблема
Apollo Client нормализует каждый результат в плоскую карту сущностей __typename:id и хранит перекрёстные ссылки как указатели { "__ref": "Type:id" }. Эта нормализация невидима в момент записи и проявляется только в момент чтения — обычно на экране, далёком от мутации, которая её вызвала. Доминируют три класса дефектов, и все три молчаливы:
Дефект | Что делает Apollo | Симптом |
Осиротевший указатель — | Возвращает | Пустая строка, без исключения |
Отсутствует | Не может вычислить ключ кэша, хранит объект встроенно | Рендерится нормально, затем расходится при второй записи |
Дрейф типа/ключа — | Одна и та же логическая сущность под двумя ключами | Дублирующиеся элементы списка, устаревшие чтения |
React Native усугубляет каждый из них:
Нет Apollo DevTools. Расширение для браузера — основной отладчик кэша, и в RN его не существует. Запасной вариант —
console.log(JSON.stringify(client.cache.extract()))и чтение многомегабайтного блоба вручную.Персистентный кэш.
apollo3-cache-persist+ AsyncStorage означает, что повреждённый кэш переживает перезапуск приложения — липкая проблема, воспроизводимая только на устройстве пользователя.Офлайн-мутации. Оптимистичные ответы записывают частичные сущности по своей природе — это ровно та форма, которая провоцирует дефекты 1 и 2.
Долгие сессии. Мобильные приложения остаются в памяти днями, поэтому дрейф накапливается значительно дольше, чем в браузерной вкладке.
Related MCP server: mcp-rn-devtools
Решение
Детекция детерминирована. Объяснение — задача модели.
Анализатор кэша, который обходит вывод
cache.extract()и сообщает о структурных дефектах с точными путями (User:1.avatar → Avatar:99). Обычный обход графа — без модели, без догадок, работает на снимке в 10 МБ.MCP-сервер, предоставляющий этот анализатор любому агенту, с которым уже работает разработчик. Агент запрашивает находки плюс релевантный подграф, поэтому ему не нужно удерживать весь кэш в контексте.
Диагностика переходит от «вставь 10 МБ блоба и вглядывайся» к диалогу.
Архитектура
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? Каждый дефект, который обнаруживает этот копilot, имеет механическое
исправление (обрезать указатель, удалить осиротевшую сущность). Модель добавила бы задержку, стоимость
и недетерминизм в решение, которое switch уже принимает корректно. Граф
оправдывает себя как оркестрация; модель живёт в MCP-клиенте, где она
сопоставляет находку с мутацией или фрагментом, которые её породили.
Установка
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-схемы (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 findingsapollo-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
Запускает MCP-сервер на stdio и блокируется. Полезен только когда MCP-клиент владеет
процессом — см. ниже. apollo-copilot-mcp — легаси-алиас для того же
самого.
stdout — это канал протокола. Сервер пишет в stdout только JSON-RPC; вся диагностика идёт в stderr. Никогда не добавляйте
console.logв этот путь.
Настройка MCP
Доступные инструменты
Инструмент | Входные данные | Поведение |
|
| Только чтение. Возвращает |
|
| Только чтение. Запускает полный граф. Возвращает |
|
| Восстанавливает снимок в одноразовом |
patch_cache переносит снимок, потому что у stdio-сервера нет живого кэша, который можно
передать патчеру — только JSON. Сравните возвращённый cache со своим, или
вызовите 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), затем укажите на бинарник
абсолютным путём:
{
"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 → убедитесь, что сервер зелёный.
Затем просто спросите
«Вот мой снимок кэша — почему аватар пустой на экране профиля?»
Агент вызывает diagnose_cache_graph, получает User:1.avatar → Avatar:99 плюс
предлагаемый PRUNE_DANGLING_REFS и сопоставляет это с мутацией, которая записала
ссылку без тела сущности.
Разработка
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 runtsconfig.json — это сборка, и он исключает __tests__ / __mocks__, чтобы
опубликованный пакет содержал только инструменты. tsconfig.test.json проверяет типы
всего и ничего не генерирует.
Метрики успеха
# | Метрика | Цель |
1 | Полнота детекции на наборе фикстур | 100% — каждый посеянный дефект найден |
2 | Ложные срабатывания на здоровом снимке | 0 |
3 | Время работы анализатора на | < 1с |
4 | Находки с точным путём в кэше | 100% |
5 | Время разработчика от симптома до названной первопричины | < 5 мин (вместо часов) |
6 | Токенов, отправляемых модели на одну диагностику | < 10k — находки + подграф, никогда не весь кэш |
Лицензия
ISC — см. LICENSE.
Available Tools
3 toolsdiagnose_cache_graphDiagnose cache graphARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| cache | Yes | 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. |
Output Schema
| Name | Required | Description |
|---|---|---|
| findings | Yes | Every defect the inspector found in `cache`. |
| narration | Yes | |
| proposedPatches | Yes | Mechanically-derived fixes for the fixable findings, ready to pass to patch_cache as-is. |
TDQS
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.
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.
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.
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.
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.
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 refsARead-only
Audit a serialized Apollo InMemoryCache (cache.extract() output) for dangling __refs, unreachable entities, and objects Apollo could not normalize. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| cache | Yes | 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. | |
| rootIds | No | 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. | |
| includeUnreachable | No | 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. | |
| includeNormalizationGaps | No | 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. |
Output Schema
| Name | Required | Description |
|---|---|---|
| stats | Yes | Aggregate counts over the whole cache, independent of the findings list. |
| findings | Yes | Every defect found, in walk order. |
TDQS
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.
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.
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.
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.
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.
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 cacheAIdempotent
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.
| Name | Required | Description | Default |
|---|---|---|---|
| gc | No | Run `cache.gc()` once after all operations land, to collect anything the patches orphaned. | |
| cache | Yes | 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. | |
| dryRun | No | Validate `operations` and report what would happen without mutating the cache. | |
| operations | Yes | One or more modify/evict operations to apply, in order. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cache | Yes | The store after the operations landed. Unchanged when `dryRun` is true. |
| dryRun | Yes | Echoes the request's dryRun — true means the cache was not actually touched. |
| results | Yes | One result per input operation, in the same order. |
| collected | Yes | Cache keys removed by the trailing `gc()`, when it ran. |
TDQS
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.
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.
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.
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.
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.
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. Dates show when Glama detected each change.
3 tool updates
v1.0.2- Changed
diagnose_cache_graph8 fields changed- added
Input schema / properties / cache / additionalProperties / descriptionAdded value: +"One normalized store entry: the raw field/value map Apollo keeps under a single cache key." - added
Input schema / properties / cache / descriptionAdded 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." - added
Output schema / properties / findings / descriptionAdded value: +"Every defect the inspector found in `cache`." - added
Output schema / properties / findings / items / properties / danglingRef / descriptionAdded value: +"The unresolved cache key the ref pointed at. Only present when kind is ORPHANED_REF." - added
Output schema / properties / findings / items / properties / message / descriptionAdded value: +"Human-readable explanation of this finding." - added
Output schema / properties / findings / items / properties / path / descriptionAdded value: +"Dotted path to the defect from its cache key, e.g. \"User:2.posts.1\"." - added
Output schema / properties / proposedPatches / descriptionAdded value: +"Mechanically-derived fixes for the fixable findings, ready to pass to patch_cache as-is." - changed
Output schema / properties / proposedPatches / items / oneOfPrevious 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" + } +]
- Changed
inspect_dangling_refs14 fields changed- added
Input schema / properties / cache / additionalProperties / descriptionAdded value: +"One normalized store entry: the raw field/value map Apollo keeps under a single cache key." - added
Input schema / properties / cache / descriptionAdded 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." - added
Input schema / properties / includeNormalizationGaps / descriptionAdded 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." - added
Input schema / properties / includeUnreachable / descriptionAdded 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." - added
Input schema / properties / rootIds / descriptionAdded 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." - added
Output schema / properties / findings / descriptionAdded value: +"Every defect found, in walk order." - added
Output schema / properties / findings / items / properties / danglingRef / descriptionAdded value: +"The unresolved cache key the ref pointed at. Only present when kind is ORPHANED_REF." - added
Output schema / properties / findings / items / properties / message / descriptionAdded value: +"Human-readable explanation of this finding." - added
Output schema / properties / findings / items / properties / path / descriptionAdded value: +"Dotted path to the defect from its cache key, e.g. \"User:2.posts.1\"." - added
Output schema / properties / stats / descriptionAdded value: +"Aggregate counts over the whole cache, independent of the findings list." - added
Output schema / properties / stats / properties / danglingCount / descriptionAdded value: +"Of those refs, how many did not resolve." - added
Output schema / properties / stats / properties / entityCount / descriptionAdded value: +"Total cache keys in the input." - added
Output schema / properties / stats / properties / refCount / descriptionAdded value: +"Total `__ref` pointers encountered." - added
Output schema / properties / stats / properties / unreachableCount / descriptionAdded value: +"Entities no root reaches."
- Changed
patch_cache15 fields changed- added
Input schema / properties / cache / additionalProperties / descriptionAdded value: +"One normalized store entry: the raw field/value map Apollo keeps under a single cache key." - added
Input schema / properties / cache / descriptionAdded 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." - added
Input schema / properties / dryRun / descriptionAdded value: +"Validate `operations` and report what would happen without mutating the cache." - added
Input schema / properties / gc / descriptionAdded value: +"Run `cache.gc()` once after all operations land, to collect anything the patches orphaned." - added
Input schema / properties / operations / descriptionAdded value: +"One or more modify/evict operations to apply, in order." - changed
Input schema / properties / operations / items / oneOfPrevious 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" + } +] - added
Output schema / properties / cache / additionalProperties / descriptionAdded value: +"One normalized store entry: the raw field/value map Apollo keeps under a single cache key." - added
Output schema / properties / cache / descriptionAdded value: +"The store after the operations landed. Unchanged when `dryRun` is true." - added
Output schema / properties / collected / descriptionAdded value: +"Cache keys removed by the trailing `gc()`, when it ran." - added
Output schema / properties / dryRun / descriptionAdded value: +"Echoes the request's dryRun — true means the cache was not actually touched." - added
Output schema / properties / results / descriptionAdded value: +"One result per input operation, in the same order." - added
Output schema / properties / results / items / properties / changed / descriptionAdded value: +"Whether `cache.modify` / `cache.evict` actually changed anything." - added
Output schema / properties / results / items / properties / error / descriptionAdded value: +"Set when this one operation failed; the rest of the batch still ran." - added
Output schema / properties / results / items / properties / operation / descriptionAdded value: +"The operation this result is reporting on, echoed back." - changed
Output schema / properties / results / items / properties / operation / oneOfPrevious 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" + } +]
3 tool updates
v1.0.0- First observed
diagnose_cache_graph - First observed
inspect_dangling_refs - First observed
patch_cache
TDQS
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.
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.
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.
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
Related MCP Connectors
MCP server for Appcircle mobile CI/CD platform.
The official Planning Center MCP server for interacting with your ministry's data.
MCP server for Boson Protocol — on-chain agentic commerce for physical & digital goods.
Related MCP Servers
- AlicenseBqualityFmaintenanceAn MCP server that connects to your React Native application debugger22832MIT
- AlicenseNot gradedqualityAmaintenanceThis MCP server enables real-time debugging and inspection of running React Native apps, providing access to console logs, errors, network requests, navigation state, storage, and performance profiling.1MIT
- AlicenseAqualityCmaintenanceMCP server that gives AI coding agents hands, eyes and a mechanic's ear for React Native development.9142MIT
- AlicenseNot gradedqualityAmaintenanceA plugin-based MCP server for React Native runtime debugging, inspection, and automation via Chrome DevTools Protocol. Works with Expo, bare React Native, and any Metro + Hermes project without app code changes.59277MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/nihar777/apollo-cache-copilot'
If you have feedback or need assistance with the MCP directory API, please join our Discord server