MCP server · JSON API · Static JSON

Call CacheSphere from any agent or tool.

CacheSphere exposes MCP tools over stdin/stdout, a JSON API over HTTP, and static JSON files you can fetch directly. Select agent context for a task, get a decision brief, or generate a benchmark experiment context — all structured, all parseable without regex.

MCP tools HTTP API Proof status llms.txt
  • ✓MCP: 6 tools, structured JSON responses, no regex parsing.
  • ✓Decision Brief for humans + structured handoff for agents.
  • ✓Proof status links distinguish measured token evidence from reviewed engineering quality.
  • ✓Static JSON: fetch packs and indices directly — no server needed.

Quickstart

GET /api/agent-entrypoints.json

Machine-readable map of the recommended entrypoints for agents and tools.

GET /api/context-pack-index.json

Index of packs, token budgets, catalogue coverage, and intended use.

GET /api/context-pack-schema.json

Shape reference for the JSON your workflow is expected to consume.

GET /api/decision-kit-schema.json

Shape reference for the Decision Brief you can paste into an ADR, issue, or handoff.

MCP tools

Run the CacheSphere MCP server locally and connect it to Cursor, Claude Code, or any MCP client:

npx cachesphere-mcp # Or directly: node bin/cachesphere-mcp.mjs

Available tools (all return structured JSON):

search_context_packs

Keyword search against pack metadata.

get_context_pack

Fetch a full pack by ID.

select_context_packs

Advisor-driven pack selection for a task description.

get_decision_kit_context

Return a compact Decision Brief with recommendations and tradeoffs.

build_experiment_context

Generate benchmark task context for reproducible agent runs.

refresh_cachesphere_cache

Refresh the local static cache.

Example: call select_context_packs with {"input": "Build a CRUD API in TypeScript"} and receive scored packs with selection signals and a token budget.

HTTP API

If your agent or pipeline speaks HTTP instead of MCP, call these endpoints directly:

# Select packs for a task curl -X POST https://cachesphere.com/api/agent/select-context-packs \ -H "Content-Type: application/json" \ -d '{"input": "Build a CRUD API in TypeScript"}' # Get a decision kit curl -X POST https://cachesphere.com/api/agent/decision-kit \ -H "Content-Type: application/json" \ -d '{"input": "Port a Python parser to Go"}' # Build experiment context curl -X POST https://cachesphere.com/api/agent/experiment-context \ -H "Content-Type: application/json" \ -d '{"taskId": "crud-api-create-read", "mode": "compact-pack"}'

All endpoints return structured JSON with the same shape as the MCP tools.

What llms.txt is for

/llms.txt is the shortest human-readable agent handoff surface on the site. It gives an LLM the product identity, intended use, and key entrypoints without forcing it to scrape the full homepage.

  • Use it when you want a model to orient itself before fetching JSON.
  • Use it in wrappers and browser agents that already look for llms.txt.
  • Do not treat it as the full dataset; it is the routing layer, not the payload.

curl example

curl -s https://cachesphere.com/api/agent-entrypoints.json | jq curl -s https://cachesphere.com/api/context-pack-index.json | jq '.packs[] | {id, title, tokenBudget, languageIds, stackIds}' curl -s https://cachesphere.com/api/context-packs/agent-memory-compact.json | jq '{id, title, summary, tokenBudget, agentUse}'

Sample system prompt

You are helping with a software stack decision. Use the CacheSphere agent context below as grounding. Rules: - Prefer the pack's tradeoffs, gotchas, and evidence links over generic priors. - Keep recommendations consistent with the pack's tokenBudget and agentUse guidance. - If the pack is insufficient, say what is missing instead of inventing certainty. - Link humans back to the relevant CacheSphere detail page or docs_url when explaining the answer. Agent context: {context_pack_json}

Agent context schema: the fields that matter most

id

Stable pack identifier, e.g. agent-memory-compact.

version

Schema/content version so cached packs can be invalidated cleanly.

languageIds

Languages covered by the pack so the agent can select relevant material fast.

stackIds

Stack archetypes or build contexts the pack is tuned for.

tokenBudget

Declared compact/full target sizes for prompt planning.

agentUse.whenToUse

Explicit guidance for when the pack should be injected.

agentUse.avoidIf

Cases where the pack is too narrow or misleading for the task.

agentUse.systemPromptAddendum

Prewritten agent instruction you can merge into your runtime prompt.

idioms

Preferred conventions and implementation patterns to keep code on-style.

gotchas

Failure modes, hidden costs, and constraints worth carrying into generation.

examples

Short prompt/output exemplars for the target workflow.

evidenceLinks

URLs or references the model can cite back to a human reviewer.

token_estimate

Optional estimated prompt footprint for ranking packs before fetch.

recommended_for_agents

Optional convenience fields exposed in the schema for pack ranking and routing.

Decision Brief output

The companion human-facing artifact is a Decision Brief: recommendation, alternatives, warnings, confidence, and evidence links in a form you can paste into a ticket or ADR.

In practice: use the Decision Brief to explain the recommendation to a person, and the structured handoff to keep the agent's next step aligned with that reasoning.

Recommended flow

  • MCP (Cursor/Claude Code): Connect bin/cachesphere-mcp.mjs and call select_context_packs directly from your agent.
  • HTTP API: POST to /api/agent/select-context-packs from any pipeline or custom tool.
  • Static JSON: Fetch /api/context-pack-index.json, choose the smallest relevant pack, then fetch only that pack.
  • Use the schemas to validate shape before generation or storage.
  • Check proof status before treating token savings as proven engineering quality.
  • Return the Decision Brief plus source links when a human needs to review the recommendation.