Skip to main content
Glama
deenesjakoruzh
theYahia

claude-webcache

by theYahia
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

claude-webcache

npm license downloads

Claude Code를 위한 세션 간 WebFetch 캐시입니다.

Claude Code의 내장 WebFetch는 단일 세션 내에서 15분 동안 결과를 캐시합니다. claude-webcache는 이를 세션 간으로 확장하여 무기한(TTL 7일, 구성 가능) 유지합니다.

Open new session  ->  your past fetches are still there.
Cache hit         ->  instant.
Cache miss        ->  same as built-in WebFetch.

이유

세션 간에 동일한 URL(문서, API 참조, 연구 페이지 등)을 다시 가져올 때마다 매번 전체 가져오기 비용을 지불하게 됩니다. 15분짜리 세션 내 캐시는 다음 스프린트 전에 만료됩니다. claude-webcache는 가져온 데이터를 유지하여 두 번째 세션에서 캐시를 적중하도록 합니다.

CACHE_MISS 흐름: 첫 번째 세션의 WebFetch + cache_store CACHE_HIT 흐름: 즉시 적중, 두 번째 세션에서 WebFetch 없음

Related MCP server: ClaudeX

설치

옵션 1 -- Claude Code 플러그인 (권장)

터미널에서 한 줄로 실행:

claude plugin marketplace add theYahia/claude-webcache && claude plugin install claude-webcache@theyahia

그런 다음 ~/.claude/CLAUDE.md에 사용 패턴을 추가합니다(사용 패턴 참조).

💡 왜 TUI의 /plugin install이 아닌 CLI 하위 명령인가요? 현재 TUI 흐름은 Claude Code의 remoteMarketplaceClient 백엔드를 통과하는데, 여기에는 모든 타사 플러그인 소스를 Failed to install: This plugin uses a source type your Claude Code version does not support.라는 오류와 함께 거부하는 서버 측 버그가 있습니다. anthropics/claude-code#41653 및 약 20개의 관련 오픈 이슈를 참조하세요. 위의 CLI 하위 명령은 로컬에서 NativeMarketplaceReader를 사용하므로 영향을 받지 않습니다.

대체 방법 (설정에서 CLI 하위 명령조차 실패하는 경우):

git clone https://github.com/theYahia/claude-webcache && claude --plugin-dir ./claude-webcache/plugin

이 방법은 마켓플레이스 파이프라인을 완전히 우회합니다.

옵션 2 -- npm 전역 설치

npm i -g @theyahia/claude-webcache

Node.js **22.5+**가 필요합니다(내장 node:sqlite 사용 -- 네이티브 종속성 없음).

그런 다음 ~/.claude/settings.json에 수동으로 등록합니다(npm root -g의 결과로 경로를 대체하세요):

{
  "mcpServers": {
    "claude-webcache": {
      "command": "node",
      "args": ["/path/from/npm-root-g/claude-webcache/scripts/mcp-server.cjs"]
    }
  },
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|clear|compact",
        "hooks": [
          { "type": "command", "command": "node /path/from/npm-root-g/claude-webcache/scripts/hook-stats.cjs" }
        ]
      }
    ]
  }
}

옵션 3 -- 클론 (기여자)

CONTRIBUTING.md를 참조하세요.

사용 패턴

~/.claude/CLAUDE.md에 추가하여 Claude가 캐시를 통해 웹 가져오기를 수행하도록 합니다:

## WebFetch caching (claude-webcache)

Before calling WebFetch, call `cached_fetch(url, prompt)` first.
- If it returns text -> use that, do NOT call WebFetch.
- If it returns `[CACHE_MISS] <url>` -> call WebFetch as normal, then call `cache_store(url, prompt, output)` with the result.

이것으로 끝입니다. 향후 세션에서 동일한 URL + 동일한 프롬프트를 사용하면 즉시 캐시가 적중됩니다.

도구 (MCP)

도구

인수

반환값

cached_fetch

url, prompt

캐시된 텍스트 또는 [CACHE_MISS] <url>

cache_store

url, prompt, output

stored

cache_stats

--

{ total, hits, last }

cache_list

limit?

최근 URL (가장 최근 순)

저장소

~/.webcache/cache.db에 SQLite 사용 (WAL 모드, 동시성 안전). 캐시 키 = SHA256(url + "|" + prompt).

필드

유형

key

TEXT PRIMARY KEY

url

TEXT

prompt_hash

TEXT

output

TEXT

cached_at

INTEGER (ms epoch)

hit_count

INTEGER

last_hit_at

INTEGER

SessionStart 훅

새 세션이 시작될 때마다 훅이 한 줄의 통계를 삽입합니다:

webcache: 142 pages cached, 38 hits, last fetch 3h ago

캐시가 비어 있으면 삽입을 건너뜁니다.

TTL

기본값은 7일입니다. 만료된 항목은 동일한 키를 다음에 읽을 때 삭제됩니다. src/cache.js를 require하고 purgeExpired()를 호출하여 수동으로 삭제할 수 있습니다.

제한 사항

  • 캐시 키에 프롬프트가 포함되므로 동일한 URL이라도 프롬프트가 다르면 별도의 항목으로 처리됩니다. 적중률을 극대화하려면 일관된 프롬프트(예: 항상 "extract title and main content")를 선택하세요.

  • 출력은 WebFetch가 반환하는 그대로입니다(이미 모델에 의해 요약됨). 캐시는 이를 다시 처리하지 않습니다.

  • 의미론적 검색이나 임베딩은 없습니다. 정확히 (url, prompt)가 일치해야 합니다.

라이선스

MIT -- LICENSE를 참조하세요.

Available Tools

4 tools
cached_fetchA

Look up a URL+prompt pair in the local WebFetch cache. Returns cached output if present (instant), or "[CACHE_MISS] " if not. On CACHE_MISS, call WebFetch, then call cache_store with the result. Same URL+prompt across sessions hits the cache.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesThe URL to fetch
promptYesThe prompt/instruction for the WebFetch

TDQS

A4.7/5.0
Behavior5/5

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

Fully describes behavior: cache lookup, instant return on hit, cache miss string, and cross-session caching. Since no annotations are provided, the description carries the full burden and meets 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?

Three sentences, front-loaded with purpose, each sentence adds value without redundancy. Fits the required structure.

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?

Complete for a simple lookup tool: explains input, output, and fallback workflow. No output schema needed as return values are textual and explained.

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

Parameters4/5

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

Adds meaning beyond schema by explaining that url and prompt form a cache key and that prompt is an instruction for WebFetch. Schema coverage is 100%, but description enriches semantics.

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?

Description clearly states it looks up a URL+prompt pair in a local cache, returning cached output or a cache miss message. This distinguishes it from sibling tools like cache_list, cache_stats, and cache_store.

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?

Describes when to use (check cache) and provides a workflow on cache miss (call WebFetch then cache_store). However, it doesn't explicitly state when not to use or compare directly to siblings.

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

cache_listB

List recently cached URLs (most recent first).

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax entries to return (default 50)

TDQS

B3.3/5.0
Behavior2/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It only states the output ordering but does not explain what constitutes 'recently cached', whether the list is global or scoped, or if there are any side effects (e.g., consuming cache entries). No safety or rate-limit information is provided.

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 a single, front-loaded sentence that conveys the core purpose with no extraneous words. Every token is meaningful.

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

Completeness3/5

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

Given the tool's simplicity (1 optional param, no output schema, no nested objects), the description is minimally adequate. However, it could benefit from additional context such as whether the cache is global or per-user, or how 'recent' is defined, but the basic listing functionality is clear.

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 schema has 100% coverage for the single parameter 'limit', and the description adds no additional meaning beyond what the schema already provides. The baseline score of 3 is appropriate since the schema is sufficient.

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 uses a clear verb 'List' and specifies the resource 'recently cached URLs' with ordering 'most recent first'. It distinguishes this from sibling tools like cached_fetch (which likely fetches a specific URL) and cache_store (which stores).

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 provides no guidance on when to use this tool versus alternatives like cached_fetch or cache_stats. There is no mention of prerequisites, use cases, or exclusions. The user is left to infer from the name alone.

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

cache_statsA

Return cache statistics: total entries, total hits, last cached timestamp.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.8/5.0
Behavior3/5

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

The description indicates a read-only operation (returning statistics) with no explicit destructive behavior. However, it lacks disclosure of potential side effects, authentication requirements, or rate limits. Since no annotations are provided, the description carries the full burden, and it only partially meets that need.

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 a single, concise sentence that front-loads the purpose ('Return cache statistics') and lists the specific outputs. Every word is necessary and there is no redundancy.

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 tool's simplicity (no parameters, no output schema), the description is sufficiently complete. It clearly lists the three statistics returned. It could optionally mention that the tool is safe to call at any time, but this is not required for basic completeness.

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

Parameters4/5

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

The tool has zero parameters, so the description adds no parameter-specific information. According to guidelines, baseline score is 4 when there are 0 parameters, as no compensation is needed.

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 explicitly states the tool returns cache statistics including total entries, total hits, and last cached timestamp. It uses a specific verb ('Return') and resource ('cache statistics'), and clearly distinguishes from sibling tools like 'cache_list' (which likely returns key listings) and 'cache_store' (which stores items).

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?

No guidance is provided on when to use this tool versus its siblings ('cached_fetch', 'cache_list', 'cache_store'). The description only states what it returns, leaving the agent to infer appropriate usage without explicit context or exclusions.

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

cache_storeA

Store a WebFetch result in the cache after a CACHE_MISS. Pass the original url, prompt, and the output text returned by WebFetch.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
outputYesThe output text returned by WebFetch
promptYes

TDQS

A3.9/5.0
Behavior2/5

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

With no annotations, the description must disclose behavioral traits. It only states the storage action but does not mention what happens if the URL already exists (overwrite?), error cases, or authorization needs. This leaves significant ambiguity.

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 concise, consisting of two sentences. The first sentence front-loads the purpose and trigger, and the second lists the parameters. No unnecessary words.

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

Completeness3/5

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

Given the lack of annotations and output schema, the description provides an adequate but minimal explanation. It identifies the tool's role in caching but omits details about idempotency, error handling, or response format, which would be helpful for a complete understanding.

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

Parameters4/5

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

Schema description coverage is low (33%), but the description adds meaning by associating each parameter with its role: 'original url, prompt, and the output text returned by WebFetch.' This helps clarify the purpose of the url and prompt parameters beyond the schema.

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's action ('Store a WebFetch result in the cache'), the resource ('cache'), and the trigger condition ('after a CACHE_MISS'). It effectively distinguishes from sibling tools like cached_fetch, cache_list, and cache_stats by specifying its role in the caching workflow.

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 explicitly specifies when to use the tool (after a CACHE_MISS), providing clear context. However, it does not mention when not to use it or offer alternatives (e.g., using cached_fetch for a subsequent lookup).

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. 4 tool updatesv0.1.5
    • First observedcache_list
    • First observedcache_stats
    • First observedcache_store
    • First observedcached_fetch
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a distinct function: lookup, list, stats, store. No overlap in purpose.

Naming Consistency4/5

All tools use 'cache_' prefix, but 'cached_fetch' uses past participle while others use 'cache_' as noun, a minor inconsistency.

Tool Count5/5

4 tools is well-scoped for a caching utility, covering essential operations.

Completeness4/5

Covers lookup, storage, listing, and stats, but lacks a clear operation to clear or invalidate cache entries.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • ClaudeX

    kunwar-shah
    A
    license
    A
    quality
    C
    maintenance
    Persistent memory + FTS5 full-text search for Claude Code conversation history. Indexes ~/.claude/projects/ JSONL into SQLite, exposes 10 MCP tools (store/recall/search memories, browse sessions, get summaries) plus prompts. Includes a web UI for visual exploration
    10
    42 npm
    93
    MIT

  • sqlite-memory-mcp

    miles990
    A
    license
    B
    quality
    D
    maintenance
    Provides persistent memory, skill tracking, failure indexing, and context sharing for Claude Code using SQLite with FTS5 full-text search.
    23
    6 npm
    1
    MIT