cachly MCP 服务器

Name: cachly-mcp-server
Author: cachly-dev

直接从 GitHub Copilot、Claude、Cursor、Windsurf 以及任何其他兼容 MCP 的 AI 助手管理您的 cachly.dev 缓存实例。

🚀 零配置设置 — 一条命令

防止您的 AI 每次都重新读取整个代码库。一条命令即可启用上下文记忆并自动配置您所有的编辑器：

CACHLY_JWT=your-jwt npx @cachly-dev/mcp-server setup

交互式向导将：

使用您的 cachly 账户进行身份验证（或提示输入 JWT）
让您选择要用作 AI 大脑的缓存实例
自动检测 Cursor、Windsurf、VS Code、Claude Code 和 Continue.dev
为每个检测到的编辑器写入正确的 MCP 配置
创建/更新 CLAUDE.md（幂等操作——可安全重复运行）

结果： 文件读取次数减少 60%，跨会话即时上下文，无需重新发现。

非交互式（CI / 脚本化设置）

CACHLY_JWT=your-jwt npx @cachly-dev/mcp-server init \
  --instance-id your-instance-id \
  --editor vscode

您可以做什么

连接后，只需与您的 AI 助手对话：

"Create a free cachly instance called my-app-cache"
"List all my cache instances"
"Get the connection string for instance abc-123"
"Delete my test-cache instance"

可用工具

🧠 AI 大脑 — 会话与记忆

工具	描述
`session_start`	单次调用，返回完整简报：上次会话、相关经验教训、未解决的故障、大脑健康状况。在每次会话开始时调用。
`session_end`	保存会话摘要、已更改的文件、持续时间。在每次会话结束时调用。
`learn_from_attempts`	在任何错误修复或部署后存储结构化的经验教训。支持严重性、文件路径、命令、标签。按主题去重。
`recall_best_solution`	检索某个主题的最佳已知解决方案（增加召回计数）。
`remember_context`	为未来的会话缓存任何分析或架构发现。
`recall_context`	通过精确键检索缓存的上下文（支持 glob：`"file:*"`）。
`smart_recall`	通过含义/关键词对所有缓存的上下文进行语义搜索。
`list_remembered`	列出所有缓存的上下文条目。
`forget_context`	删除过期的上下文。

⚙️ 实例管理

工具	描述
`list_instances`	列出您所有的缓存实例
`create_instance`	创建一个新实例（免费或付费层级）
`get_instance`	获取特定实例的详细信息
`get_connection_string`	获取 `redis://` 连接 URL
`delete_instance`	永久删除实例

🗄️ 缓存操作

工具	描述
`cache_get` / `cache_set` / `cache_delete`	实时缓存操作
`cache_exists` / `cache_ttl` / `cache_keys`	键检查
`cache_stats`	内存、命中率、每秒操作数
`cache_mget` / `cache_mset`	批量流水线操作
`cache_lock_acquire` / `cache_lock_release`	分布式锁 (Redlock-lite)
`cache_stream_set` / `cache_stream_get`	LLM token 流式缓存

🔍 语义与 AI

工具	描述
`semantic_search`	向量相似度搜索（速度/商业层级）
`detect_namespace`	自动将提示词分类到语义命名空间
`cache_warmup`	使用已知的问答对预热语义缓存
`index_project`	为 AI 语义搜索索引本地源文件
`get_api_status`	检查 API 健康状况 + JWT 认证信息

设置

推荐：通过 npx 进行零配置设置

CACHLY_JWT=your-jwt npx @cachly-dev/mcp-server setup

无需安装，无需构建步骤。向导会自动检测您的编辑器并写入所有配置文件。

手动配置

在 cachly.dev/settings → API Tokens 获取您的 JWT 令牌。

Claude Code / Claude Desktop

{
  "mcpServers": {
    "cachly": {
      "command": "npx",
      "args": ["-y", "@cachly-dev/mcp-server"],
      "env": { "CACHLY_JWT": "your-jwt-token-here" }
    }
  }
}

Claude Code: 添加到项目中的 .claude/mcp.json
Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json

GitHub Copilot (VS Code)

添加到 .vscode/mcp.json：

{
  "servers": {
    "cachly": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cachly-dev/mcp-server"],
      "env": { "CACHLY_JWT": "your-jwt-token-here" }
    }
  }
}

然后：Ctrl/Cmd+Shift+P → "MCP: List Servers" → 启动 cachly。

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "cachly": {
      "command": "npx",
      "args": ["-y", "@cachly-dev/mcp-server"],
      "env": { "CACHLY_JWT": "your-jwt-token-here" }
    }
  }
}

Windsurf / Continue.dev

使用相同的 stdio/mcpServers 格式 — 添加到它们各自的 MCP 配置文件中。

环境变量

变量	必需	默认	描述
`CACHLY_JWT`	✅	–	您来自 cachly.dev/settings 的 Keycloak JWT
`CACHLY_API_URL`	❌	`https://api.cachly.dev`	本地开发的覆盖地址

会话示例

User: Create a free cache instance for my OpenAI project

Copilot: I'll create a free cachly instance for you.
[calls create_instance(name="openai-cache", tier="free")]

✅ Instance **openai-cache** (FREE) created and provisioning started!
   ID: `a1b2c3d4-...`
   Status: provisioning

Use `get_connection_string` to get your Redis URL in ~30 seconds.

User: Get the connection string

Copilot: [calls get_connection_string(instance_id="a1b2c3d4-...")]

Connection string for openai-cache:
  redis://:password@my-node.cachly.dev:30101

Environment variable:
  REDIS_URL="redis://:password@my-node.cachly.dev:30101"

本地开发

# Run against local API
CACHLY_JWT=your-token CACHLY_API_URL=http://localhost:3001 npm run dev

实际应用场景

🧠 停止重新读取您的代码库 — “思维缓存”

问题： 每次您向 Copilot 询问有关代码库的问题时，它都会运行“我正在查看代码库”并重新读取数百个文件。

解决方案： 缓存您 AI 的“思维”结果：

You: "Analyze the authentication architecture"
AI:  [reads 47 files, takes 30 seconds]
     The auth uses Keycloak with JWT tokens. The flow is:
     1. User hits /sign-in → NextAuth redirect
     2. Keycloak validates credentials
     3. JWT returned, stored in session
     
     [calls remember_context("auth_architecture", "The auth uses Keycloak...")]
     🧠 Context saved for future sessions.

--- Next day, new session ---

You: "How does auth work?"
AI:  [calls smart_recall("auth")]
     🧠 Found cached context:
     The auth uses Keycloak with JWT tokens...
     
     (No file reading needed — instant answer!)

setup 向导（见本 README 顶部）会自动将这些会话指令写入您的 CLAUDE.md / .github/copilot-instructions.md — 无需手动编辑。 只需运行一次 npx @cachly-dev/mcp-server setup，您的 AI 助手就会在每次会话开始时自动调用 session_start。

1. AI 辅助开发 — “我正在使用哪些缓存？”

您正在构建一个使用多个 cachly 实例的微服务。直接询问您的 AI 助手：

You: "List all my cachly instances and their status"
AI:  Using cachly_list_instances...
     
     You have 3 instances:
     1. prod-api (Pro, running) — redis://:***@prod.cachly.dev:30101
     2. staging (Dev, running) — redis://:***@staging.cachly.dev:30102  
     3. ml-pipeline (Speed, running) — redis://:***@ml.cachly.dev:30103
     
     Total MRR: €72/month

2. 缓存调试 — “为什么我的命中率在下降？”

您的语义缓存命中率在一夜之间下降了。无需离开编辑器即可调试它：

You: "Check the analytics for my prod-api instance"
AI:  Using cachly_semantic_stats...
     
     ⚠️ Hit rate dropped 23% in the last 24h (82% → 63%)
     
     Anomaly detected: near-miss spike (+140%)
     → 47 queries are hitting similarity 0.80-0.84 (just below your 0.85 threshold)
     
     Recommendation: Lower threshold to 0.82 to capture these near-misses.
     
You: "Do it"
AI:  Using cachly_set_threshold... ✅ Threshold set to 0.82 for namespace cachly:sem

3. 部署缓存预热 — “为新版本预填充缓存”

部署新版本后，使用常见查询预热语义缓存：

You: "Warm up the staging cache with our top 50 support questions"
AI:  Using cachly_batch_index with your FAQ embeddings...
     
     ✅ Indexed 50 entries in 340ms (batch pipeline)
     Namespace: cachly:sem:qa
     
     Your cache is ready — first users will get instant responses.

4. 成本监控 — “我节省了多少钱？”

直接在您的 IDE 中跟踪您的 LLM 成本节省情况：

You: "How much has cachly saved me this month?"
AI:  Using cachly_semantic_stats...
     
     📊 This month's savings:
     - Total cache hits: 12,847
     - Estimated savings: $384.21 (vs. direct LLM calls)
     - Efficiency score: 84/100 (Grade: A)
     - Best namespace: cachly:sem:qa (94% hit rate)

5. CI 流水线集成 — “部署前检查缓存健康状况”

将缓存健康检查添加到您的部署工作流中：

You: "Check if any cache anomalies would block a deploy"
AI:  Using cachly_analytics_anomalies...
     
     ✅ No critical anomalies detected.
     1 info-level notice: stale cache in namespace "translations" 
     (12 near-misses/24h, 0 new entries)
     
     Recommendation: Run warmup after deploy for translations namespace.
     Deploy is safe to proceed.

cachly-mcp-server