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精心打造