Provimedia MCP

🚀 Chainguard - Claude Code的MCP服務器

Chainguard 是一個模型上下文協議（MCP）服務器，它通過任務跟蹤、語法驗證、長期記憶和智能上下文管理來增強Claude Code的功能。

🚀 快速開始

快速安裝（推薦）

curl -fsSL https://raw.githubusercontent.com/provimedia/chainguard/main/installer/install.sh | bash

安裝程序會在 ~/.chainguard/venv/ 創建一個Python虛擬環境，並將所有依賴項安裝到其中（符合PEP 668）。

手動安裝

1. 克隆倉庫：

git clone https://github.com/provimedia/chainguard.git
cd chainguard

2. 運行安裝程序：

./installer/install.sh

3. 重啟Claude Code

更新依賴項

~/.chainguard/venv/bin/pip install --upgrade fastembed numpy mcp aiofiles aiohttp aiomysql pyyaml

要求

• Python 3.9+
• Claude Code CLI
• 用於長期記憶的 fastembed 和 numpy（通過虛擬環境自動安裝）
• 可選：用於PHP靜態分析的 phpstan（在執行前捕獲運行時錯誤）

✨ 主要特性

核心特性

• 任務範圍管理 - 定義任務邊界、驗收標準並跟蹤進度
• 自動語法驗證 - 對文件更改進行PHP、JavaScript、JSON、Python、TypeScript驗證
• PHPStan集成（v6.3） - 靜態分析在執行前捕獲運行時錯誤（空訪問、類型錯誤）
• 智能上下文跟蹤 - 基於金絲雀的上下文刷新確保Claude不會丟失重要指令
• HTTP端點測試 - 支持會話的端點測試和自動認證檢測

長期記憶（v5.1+，v6.6重寫）

• 語義代碼搜索 - 支持自然語言查詢，如“身份驗證在哪裡處理？”
• 輕量級向量存儲 - fastembed（ONNX Runtime）+ numpy + sqlite3，約500 MB內存（取代ChromaDB）
• 多語言嵌入 - paraphrase-multilingual-MiniLM-L12-v2 支持包括德語在內的50多種語言
• 6個知識集合 - 代碼結構、函數、數據庫模式、架構、學習內容、代碼摘要
• RAG管道 - 混合檢索，語義相似度佔60%，關鍵字匹配佔25%，近期評分佔15%
• 自動上下文注入 - UserPromptSubmit 鉤子在每次LLM調用前注入相關的記憶上下文
• 自動刷新陳舊記憶（v6.8） - 在 set_scope 時檢測超過30天的記憶，並逐步重新索引更改的文件
• 項目隔離 - 經過安全驗證的隔離防止跨項目訪問
• 導出/導入 - 支持可移植的JSON/JSONL導出，可選gzip壓縮

注意：自v6.6起，長期記憶默認啟用（MEMORY_ENABLED=True），因為內存使用從約3.8 GB減少到約500 MB。

TOON編碼器（v6.0）

• 面向令牌的對象表示法 - 緊湊的數據格式，可節省30 - 60%的令牌
• 針對數組優化 - 最適合文件列表、表格、歷史記錄條目
• 自動格式化 - 像 chainguard_projects、chainguard_history 等工具默認使用TOON

幻覺預防（v6.1+）

• 符號驗證 - 通過置信度評分檢測幻覺函數/方法調用
• PHP內置數據庫 - 來自JetBrains phpstorm-stubs的11,000多個PHP函數/類/方法（v6.3.1）
• 拼寫錯誤檢測 - 捕獲拼寫錯誤的包名（例如，requets 而不是 requests）
• 7種語言支持 - PHP、JavaScript、TypeScript、Python、C#、Go、Rust
• 包註冊表驗證 - 根據 composer.json、package.json、requirements.txt 檢查導入
• 自適應模式 - 根據誤報率自動調整靈敏度

深度邏輯摘要（v5.4）

• 代碼理解 - 提取代碼實際功能的人類可讀摘要
• 目的推斷 - 從文檔字符串、註釋和命名約定中識別模式
• 多語言支持 - Python、PHP、JavaScript、TypeScript

架構分析（v5.3+）

• 模式檢測 - MVC、MVVM、清潔架構、六邊形架構、分層架構、API優先
• 框架識別 - Laravel、Django、React、Vue、Angular、FastAPI等
• AST分析 - 基於Tree-sitter的代碼解析，支持正則表達式回退

PRD自動檢測（v6.7）

• 自動PRD發現 - 在 set_scope 時檢測PRD/需求文檔
• 16種文件名模式 - PRD.md、REQUIREMENTS.md、SPEC.md、SPECIFICATION.md 等
• 7個搜索目錄 - 根目錄、docs/、doc/、.claude/、requirements/、specs/、.github/
• 工作流提醒 - 提醒在實現前檢查PRD，並在 finish 時更新PRD

看板系統（v6.5）

• 持久任務管理 - 通過可視化看板跟蹤複雜的多日項目
• 智能看板建議 - 當滿足≥5個標準或複雜性關鍵字時自動推薦看板
• 7列預設 - 默認、編程、內容、DevOps、研究、敏捷、簡單
• 自定義列 - 通過LLM提示注入定義特定任務的列
• 依賴跟蹤 - 卡片可以依賴其他卡片，被阻塞的卡片會高亮顯示
• 鏈接詳細文件 - 每張卡片可以鏈接一個包含詳細說明的Markdown文件
• 存檔系統 - 完成的卡片可以存檔以保留歷史記錄
• 圖形看板視圖 - 帶有進度條的ASCII藝術可視化

任務模式

功能標誌

在 ~/.chainguard/chainguard/config.py 中配置：

💻 使用示例

基礎用法

# 1. 開始一個任務（必需）
chainguard_set_scope(
    description="Implement user login",
    mode="programming",
    acceptance_criteria=["Login works", "Tests pass"]
)

# 2. 跟蹤更改（自動驗證語法）
chainguard_track(file="src/AuthController.php", ctx="🔗")

# 3. 檢查狀態
chainguard_status(ctx="🔗")

# 4. 完成任務
chainguard_finish(confirmed=True)

長期記憶

# 初始化記憶（每個項目一次，在set_scope時自動刷新陳舊數據）
chainguard_memory_init()

# 語義搜索（支持50多種語言）
chainguard_memory_query(query="Where is authentication handled?")
chainguard_memory_query(query="Wo wird Validierung gemacht?")

# 按類型過濾：all, code, functions, database, architecture
chainguard_memory_query(query="user table", filter_type="database")

# 生成深度邏輯摘要
chainguard_memory_summarize()                    # 所有新文件
chainguard_memory_summarize(file="src/auth.py")  # 特定文件

# 為未來會話添加學習內容
chainguard_memory_update(action="add_learning", learning="Auth uses JWT with 24h expiry")

# 檢查記憶健康狀況
chainguard_memory_status()

# 導出/導入以進行備份或轉移
chainguard_memory_export(format="json", compress=True)
chainguard_memory_import(file="path/to/export.json")

數據庫模式檢查

# 連接到數據庫
chainguard_db_connect(
    host="localhost",
    user="root",
    password="...",
    database="myapp"
)

# 獲取模式（防止SQL字段名猜測）
chainguard_db_schema()

🔧 技術細節

RAG管道

當通過 chainguard_memory_query 進行查詢時，會運行以下管道：

查詢 → 關鍵字提取 → 關鍵字擴展 → 嵌入（384維）
  → 向量搜索（6個集合） → 評分 → 去重 → 格式化

1. 關鍵字提取 - 提取最多10個關鍵字，去除英語和德語停用詞
2. 關鍵字擴展 - 用30個同義詞組擴展（例如，login → auth, authentication, signin, session, jwt, token）
3. 嵌入 - 通過fastembed（ONNX Runtime）轉換為384維向量
4. 向量搜索 - 使用餘弦距離查詢所有6個集合
5. 評分 - 計算加權相關性得分：
   • 語義相似度：60%
   • 關鍵字匹配：25%
   • 近期獎勵：15%（最近24小時：1.0，上週：0.8，上月：0.5）
   • 任務類型獎勵：0 - 20%（例如，database 任務提升表/遷移結果）
   • 源類型權重：測試文件0.7倍，配置文件0.8倍，遷移文件0.85倍
6. 去重 - 每個文件路徑只保留最佳結果
7. 集合平衡 - 遵守每個集合的限制（代碼結構：4，函數：3，架構：2等）
8. 過濾 - 僅返回得分 > 0.4的結果
9. 緩存 - 結果緩存5分鐘（TTLLRUCache，最大100個條目）

集合

自動上下文注入

chainguard_memory_inject.py 鉤子在每次 UserPromptSubmit 事件時運行：

• 從用戶提示中提取關鍵字（最多10個）
• 使用快速的基於關鍵字的 LIKE 查詢對sqlite3進行內存查詢（避免fastembed冷啟動）
• 返回按類型分組的相關代碼位置、函數和結構
• 3秒超時 以防止Claude Code掛起
• 基於文件的緩存，重複查詢的TTL為5分鐘
• 短於20個字符的提示將被跳過

多語言支持

模型：paraphrase-multilingual-MiniLM-L12-v2（384維） 支持包括德語、英語、西班牙語、法語、意大利語、荷蘭語、葡萄牙語、波蘭語、俄語、中文、日語、韓語等在內的50多種語言。查詢和索引內容可以使用任何支持的語言。 過濾英語和德語的停用詞（100多個單詞）。

自動刷新（v6.8）

當調用 chainguard_set_scope() 時：

1. 檢查記憶是否超過30天（STALE_MEMORY_THRESHOLD_DAYS）
2. 通過git日誌（快速）或mtime回退（最多1000個文件）查找更改的文件
3. 逐步重新索引最多30個更改的文件（STALE_MEMORY_MAX_FILES）
4. 僅在所有文件成功時保存元數據（錯誤保護）

向量存儲架構

輕量級向量存儲（vectorstore.py）取代了ChromaDB：

• 存儲：每個項目一個 vectors.sqlite3 文件（1700個文檔約3 MB）
• 內存中的向量：所有向量作為numpy數組加載，以實現快速餘弦相似度
• 線程安全：線程本地sqlite3連接，WAL模式支持併發讀取
• 與ChromaDB兼容的API：可直接替換（添加、更新、查詢、獲取、刪除、計數）
• WHERE過濾器：支持 $eq 和 $ne 運算符對元數據進行過濾

導出與導入

# 導出記憶（JSON或JSONL，可選gzip壓縮）
chainguard_memory_export(format="json", compress=True, include_embeddings=False)

# 導入記憶（合併或替換）
chainguard_memory_import(file="path/to/export.json", merge=True, skip_existing=True)

# 列出可用的導出
chainguard_list_exports()

• 每個導出文件最多10,000個文檔
• 格式：JSON（單個文件）或JSONL（流式傳輸，更適合大型數據集）
• 合併模式：與現有數據合併或清除並替換
• 導出文件存儲在 ~/.chainguard/exports/

記憶配置

~/.chainguard/chainguard/config.py 中的所有常量：

📚 詳細文檔

• 使用指南
• 測試指南
• 長期記憶概念
• 同步與安裝清單

🛠️ 可用工具

核心工具

記憶工具

分析工具

幻覺預防工具

數據庫工具

HTTP測試工具

看板工具

🏗️ 架構

~/.chainguard/
├── venv/                 # Python虛擬環境（v6.6+）
├── chainguard/           # MCP服務器包（34個模塊）
│   ├── handlers.py       # 工具處理程序（224 KB）
│   ├── tools.py          # 工具定義
│   ├── models.py         # 數據模型
│   ├── config.py         # 配置和功能標誌
│   ├── kanban.py         # 看板系統（v6.5）
│   ├── memory.py         # 長期記憶
│   ├── vectorstore.py    # 輕量級向量存儲（sqlite3 + numpy）
│   ├── embeddings.py     # fastembed集成
│   ├── code_summarizer.py # 深度邏輯提取
│   ├── ast_analyzer.py   # AST分析
│   ├── architecture.py   # 模式檢測
│   ├── symbol_validator.py # 幻覺預防
│   ├── symbol_patterns.py  # 特定語言的模式
│   ├── package_validator.py # 拼寫錯誤檢測
│   ├── db_inspector.py   # 數據庫檢查器（MySQL/PG/SQLite）
│   ├── db_credentials.py # 持久數據庫憑證
│   ├── http_session.py   # HTTP會話管理
│   ├── test_runner.py    # 測試執行運行器
│   ├── history.py        # 錯誤/更改歷史記錄
│   ├── memory_export.py  # 記憶導入/導出
│   ├── toon.py           # TOON編碼器
│   └── ...
├── chainguard_mcp.py     # MCP入口點
├── hooks/                # Claude Code鉤子
│   ├── chainguard_enforcer.py      # PreToolUse：阻止編輯/寫入違規
│   ├── chainguard_memory_inject.py # UserPromptSubmit：記憶上下文注入
│   └── chainguard_scope_reminder.py # UserPromptSubmit：範圍提醒（v6.1）
├── projects/             # 項目狀態存儲
├── memory/               # sqlite3向量存儲
└── templates/            # CLAUDE.md模板

鉤子

Chainguard使用Claude Code鉤子進行自動強制執行：

🧪 開發

運行測試

cd src/mcp-server
python3 -m pytest tests/ -v

測試覆蓋率

🤝 貢獻

歡迎貢獻！請隨時提交拉取請求。

1. 分叉倉庫
2. 創建你的功能分支（git checkout -b feature/amazing-feature）
3. 提交你的更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打開拉取請求

📄 許可證

本項目採用 Polyform非商業許可證1.0.0。

你可以：

• 將此軟件用於任何非商業目的
• 修改並創建衍生作品
• 分享和分發軟件

你不可以：

• 出售此軟件或用於商業目的
• 只有Provimedia GmbH有權出售此軟件

詳情請參閱 LICENSE 文件。

第三方許可證

本項目包含來自以下開源項目的數據：

PHP內置數據庫（data/php_builtins.json）由phpstorm-stubs生成，用於符號驗證中的幻覺預防。

👏 致謝

由 Provimedia GmbH 創建和維護。

📝 更新日誌

v6.8.1

• 部分刷新時間戳保護 - 僅在所有文件成功（錯誤數為0）時保存記憶元數據
• PRD文件緩存 - 在 set_scope 時檢測到的PRD文件緩存在 ProjectState.prd_files 中
• mtime回退限制 - 為保護單倉庫，將 os.walk() 限制為1000個文件

v6.8.0

• 自動刷新陳舊記憶 - 在 set_scope 時檢測超過30天的記憶，並逐步重新索引更改的文件
  • 基於git日誌的發現（快速路徑），支持mtime回退
  • 新配置：AUTO_REFRESH_STALE_MEMORY、STALE_MEMORY_THRESHOLD_DAYS、STALE_MEMORY_MAX_FILES
• 新的 ProjectMemory.get_metadata() 方法用於讀取 metadata.json

v6.7.0

• PRD自動檢測 - 在 set_scope 時自動檢測PRD/需求文檔
  • 16種文件名模式：PRD.md、REQUIREMENTS.md、SPEC.md、SPECIFICATION.md 等
  • 搜索7個目錄：根目錄、docs/、doc/、.claude/、requirements/、specs/、.github/
  • 在 set_scope 時提醒檢查PRD，在 finish 時提醒更新PRD（如果更改文件數≥3）

v6.6.0

• 記憶系統重構 - 用fastembed + numpy + sqlite3取代ChromaDB + sentence-transformers
  • 內存使用從約3.8 GB減少到約500 MB（減少7.6倍）
  • 新的 vectorstore.py 模塊：輕量級向量存儲，使用sqlite3後端和內存向量
  • 新的 embeddings.py 模塊：fastembed（ONNX Runtime）集成
  • 可直接替換，保持ChromaDB集合API
  • MEMORY_ENABLED 現在默認值為 True
• 多語言嵌入 - 從 all-MiniLM-L6-v2（僅英語）切換到 paraphrase-multilingual-MiniLM-L12-v2（50多種語言）
  • 相同的384維，無需存儲遷移
  • 模型更改時自動強制重新初始化
• Python虛擬環境安裝 - 用 ~/.chainguard/venv/ 中的專用虛擬環境取代 pip install --user
  • 修復現代macOS/Linux上的PEP 668兼容性問題
  • 更新安裝程序、驗證器和卸載程序
• 上下文注入質量 - 源類型加權（測試文件0.7倍），按文件去重，降低相關性閾值（0.5 -> 0.4）

v6.5.0

• 看板系統 - 用於複雜多日項目的持久任務管理
  • 新的 kanban.py 模塊，包含 KanbanCard、KanbanBoard、KanbanManager 類
  • 10個新工具，支持完整的看板工作流
  • 7列預設：默認、編程、內容、DevOps、研究、敏捷、簡單
  • 通過工具描述中的LLM提示注入自定義列
  • .claude/kanban.yaml 中的YAML持久化
  • .claude/cards/ 中卡片詳細信息的鏈接Markdown文件
  • 完成卡片的存檔系統
  • 帶有進度條和阻塞卡片高亮顯示的圖形看板視圖
  • 卡片之間的依賴跟蹤
  • 50個新單元測試
• 智能看板建議 - 當檢測到≥5個驗收標準或複雜性關鍵字（如“mehrtägig”、“komplex”、“pipeline”等）時自動推薦看板

v6.4.6

• 字符串內容剝離以防止誤報 - 防止字符串內文本的幻覺警告
  • HTML佔位符：placeholder="Max Mustermann (optional)" 不再觸發警告
  • 字符串中的SQL："SELECT * FROM table_name WHERE..." 不再將表名檢測為調用
  • 保留插值字符串（f字符串、$字符串、模板字面量），因為它們包含真實代碼
  • 9個新測試用於字符串內容誤報預防

v6.4.5

• 符號警告阻止完成 - 當存在符號警告時，chainguard_finish() 被阻止（除非 force=True）
• 跳過文檔字符串/多行註釋 - 文檔字符串和註釋中的函數調用不再被檢測
• Python標準庫擴展 - 添加 field、dataclass、Optional、Path、Any、List、Dict 等

v6.4.4

• 擴展內置函數：JS Web API + SQL函數 - 修復誤報
  • JavaScript：添加 IntersectionObserver、MutationObserver、ResizeObserver、FormData、AbortController、WebSocket、Worker 等30多個Web API
  • PHP：添加PHP代碼中出現的SQL函數：CURDATE、NOW、COALESCE、CONCAT、GROUP_CONCAT、SUM、AVG 等50多個
  • 10個新測試用於Web API和SQL函數

v6.4.3

• PHP不區分大小寫的內置檢查 - 修復大寫PHP函數的誤報
  • MAX()、DATE()、COUNT()、StrLen() 等現在正確識別為內置函數
  • PHP不區分大小寫，因此 is_builtin() 現在對PHP使用小寫比較
  • 減少PHP代碼中SQL函數的誤報
  • 4個新測試用於不區分大小寫

v6.4.2

• 需要操作的上下文注入 - 強制LLM主動檢查幻覺警告
  • <action-required> XML標籤在 chainguard_finish() 時包裝符號警告
  • 突出顯示“🔴 AKTION ERFORDERLICH”消息，而不是微妙的警告
  • 清晰的3步說明：檢查存在性 → 檢查導入 → 如果是誤報則忽略
  • 警告：“NICHT IGNORIEREN - Halluzinierte Funktionen führen zu Runtime-Fehlern!”
  • 防止在長時間會話和多個任務中忽略警告

v6.4.1

• 符號警告聚合 - 幻覺警告現在在會話期間收集
  • 警告存儲在 state.symbol_warnings 中，而不是隻顯示一次
  • 所有收集的警告在 chainguard_finish() 時顯示 - 防止警告丟失
  • 對於有40多個任務的長時間會話很有用，否則警告會被忽略
• 提高潛在幻覺函數調用的可見性

v6.4.0

• 持久數據庫憑證 - 每個項目保存數據庫憑證（混淆）
  • 調用 chainguard_db_connect() 時無需參數即可使用保存的憑證
  • 憑證使用XOR + Base64混淆（特定於機器的密鑰）
  • 成功連接後自動保存，失敗時自動刪除
  • 新的 chainguard_db_forget 工具用於刪除保存的憑證
  • 新的 db_credentials.py 模塊，包含 CredentialStore 類
  • 30個新測試用於憑證處理
• chainguard_db_connect 的新 remember 參數（默認：True）

v6.3.1

• PHP內置數據庫 - 來自JetBrains phpstorm-stubs的11,000多個PHP函數/類/方法
  • 顯著減少符號驗證中的誤報（從170多個減少到接近零）
  • 包括：核心函數（5,028個）、類（1,035個）、方法（10,039個）
  • 首次PHP驗證時懶加載，啟動成本為零
  • 生成腳本可從最新的phpstorm-stubs更新
• 新的 generate_php_builtins.py 腳本用於更新數據庫

v6.3.0

• PHPStan集成 - 對PHP文件進行靜態分析，在執行前捕獲運行時錯誤
  • 檢測空訪問錯誤（$user['id'] 對空值）
  • 類型不匹配（字符串與整數）
  • 未定義的方法和屬性
  • 可配置的分析級別（0 - 9，默認：8）
  • 智能項目根檢測（composer.json、vendor/、phpstan.neon）
• 自動檢測PHPStan（全局、vendor/bin或composer全局）
• 新的配置標誌：PHPSTAN_ENABLED、PHPSTAN_LEVEL

v6.1.0

• 幻覺預防 - 檢測LLM幻覺的函數調用和包導入
  • chainguard_validate_symbols - 根據代碼庫驗證函數/方法調用
  • chainguard_validate_packages - 檢測拼寫錯誤的包名
  • 7種語言支持：PHP、JavaScript、TypeScript、Python、C#、Go、Rust
  • 自適應模式根據誤報率自動調整
• 範圍提醒鉤子 - 新的 UserPromptSubmit 鉤子，提醒設置範圍
• 修復純分析任務（Task/Explore）可能繞過範圍強制的問題
• 30分鐘冷卻時間，防止垃圾信息
• 118個新測試（符號驗證：47個，包驗證器：71個）

v6.0.0

• TOON編碼器 - 面向令牌的對象表示法，節省30 - 60%的令牌
• 新的 toon.py 模塊，包含 encode_toon、toon_array、toon_object 函數
• 集成到 chainguard_projects 和 chainguard_history 中
• 默認禁用記憶 - 防止低內存系統出現RAM問題
• 功能標誌：TOON_ENABLED=True、MEMORY_ENABLED=False、XML_RESPONSES_ENABLED=False
• 63個新測試用於TOON編碼器，總計764+個測試

v5.4.0

• 使用 code_summarizer.py 生成深度邏輯摘要
• 新的 chainguard_memory_summarize 工具
• code_summaries 集合用於語義代碼理解
• 45個新測試用於代碼摘要器

v5.3.0

• 基於Tree-sitter的AST分析
• 架構模式檢測
• 框架識別
• 記憶導出/導入

v5.2.0

• 智能上下文注入
• 跟蹤/完成時自動更新記憶

v5.1.0

• 使用ChromaDB的長期記憶
• 語義代碼搜索
• 項目隔離

v5.0.0

• 任務模式系統（編程、內容、DevOps、研究）
• 特定模式的工具

由Provimedia GmbH精心打造