🧠 设计缓存MCP服务器（Postgres+Psycopg 3）
模型上下文协议（MCP）服务器充当 共享、持久的设计内存 对于AI代理。它将设计对话存储在PostgreSQL支持的层次结构中，实现了对项目设计历史的跨会话上下文和语义搜索。
🚀 特性
- 跨会话持久性设计决策超越了单一的人工智能对话——几天或几周后从你离开的地方继续。
- 多代理共享：在具有共享设计上下文的同一项目上使用Claude Code、Cursor、Windsurf或任何与MCP兼容的工具。
- 分层缓存：用于高级项目目标和细粒度想法讨论的单独存储。
- 混合搜索：使用GIN索引的全文搜索（FTS）+使用局部嵌入的语义向量搜索(
sentence-transformers). - 设计安全：基于角色的访问控制（RBAC）、参数化查询和速率限制（60 RPM）。
- 现代后端：使用Python Asyncio和Psycopg 3构建。
🤔 何时使用此
合身：
- 你使用 多种人工智能工具 在同一个项目上（例如，Claude Code+Cursor+Windsurf），需要在它们之间共享设计上下文。
- 你在一家公司工作 团队 其中多个人的AI代理需要访问相同的设计决策。
- 你想要 语义搜索 在过去的设计讨论中——通过意义而不仅仅是关键字来寻找相关决策。
- 您的项目有 长时间运行的设计阶段 决策在数周/数月内累积。
在以下情况下可能不需要：
- 你使用a 单一人工智能工具 使用内置内存（例如，Claude Code的内存系统、Claude.md文件），内置的持久性可能满足您的需求。
- 您的项目足够小，一些markdown文件可以捕获完整的设计上下文。
⚠️ 诚实的笔记
此服务器最初被设计为“令牌保存”工具。在实践中：
- MCP工具定义使用令牌。 该服务器注册了大约18个工具，这些工具的模式随每个API调用一起发送，无论是否使用，都会增加开销。
- 检索到的内容仍会出现在对话上下文中 并且以与读取文件相同的方式消耗令牌。
- 然后搜索扩展模式 （首先250个字符摘要，按需提供完整内容）是一个合理的优化，但大多数人工智能工具已经通过文件读取自然地做到了这一点。
真正的价值是 坚持与分享，而不是象征性的减少。
______________________________________________________________________
🛠️ 先决条件
- Docker 桌面版 （推荐）
- Python 3.13+ （如果不使用Docker运行）
- PostgreSQL 18+ （如果不使用Docker运行）
______________________________________________________________________
📦 本地部署（推荐）
在本地运行Python服务器允许AI在本地读写您的本地文件系统（用于将markdown规范链接到缓存）。
- 运行安装脚本:
chmod +x setup_local.sh
./setup_local.sh*（这将启动Docker中的Postgres数据库，创建一个Python venv，并安装依赖项，包括 sentence-transformers.)*
- 运行服务器:
source venv/bin/activate
# Load environment variables from .env
export $(grep -v '^#' .env | xargs)
python server.py🤖 配置AI代理
- 克劳德代码（CLI）
将服务器添加到全局MCP配置中：
claude mcp add design-cache --command /path/to/venv/bin/python --args ["/path/to/server.py"]- 反重力/光标/风浪
- 首选 设置>功能>MCP. - 点击+ 添加新的MCP服务器. - 名字: design-cache | 类型: stdio. - 命令: /path/to/venv/bin/python /path/to/server.py
- 克劳德桌面（macOS/Windows）
编辑您的 claude_desktop_config.json 并将此条目添加到您的mcpServers列表中：
"design-cache": {
"command": "/path/to/venv/bin/python",
"args": ["/path/to/server.py"],
"env": {
"DB_HOST": "localhost",
"DB_READ_PASS": "your_password",
"DB_WRITE_PASS": "your_password"
}
}📖 使用示例
看看这个 示例/usage.md 查看AI代理在头脑风暴、上下文检索和决策形式化过程中如何和缓存交互。
🔧 可用工具
- 搜索设计：混合关键字+语义搜索。返回摘要以最小化上下文大小。
- expand_design_note：检索特定缓存想法的完整、未删节的文本。
- store_note：将新的设计决策或想法保存到缓存中。
- update_note：修改现有注释（如果内容更改，则自动重新嵌入）。
- delete_note：永久删除特定注释。
- 总结和清理：将多个想法合并到项目级摘要中，并删除原始想法。
- get_recent_activity：使用可选的标记筛选列出最近的笔记。
- get_project_context：自动检测项目来源
.design_cache文件并显示状态。 - 出口_项目_降价：将完整的设计历史导出为Markdown文档。
- generate_spec_from_cache：将缓存的想法转换为技术规范模板。
- generate_adr_from_cache：将缓存的想法转换为ADR模板。
- sync_doc_status：将物理文件链接到缓存条目并更新其状态。
- link_external_file_to_cache：将本地Markdown文件链接到缓存条目。
- set_retention_policy：为每个项目配置清理策略。
- 获取_保留_政策：显示活动保留策略。
- run_smart_cleanup：根据保留策略删除过期的笔记。
- 获取压缩机会：分析笔记密度并建议摘要目标。
- 健康检查：验证数据库连接健康状况和pgvector可用性。
🛡️ 安全说明
- 环境变量：敏感凭据（密码）通过环境变量严格管理，从不在存储库中硬编码。使用
.env.example作为模板。 - 最小权限：用途
design_readonly搜索和design_readwrite用于修改。 - 参数化查询：用途
psycopg3绑定以在不阻止有效markdown字符的情况下本机防止SQL注入。 - 速率限制：每分钟最多60个请求。
- 连接生命周期：通过Psycopg 3每5分钟回收一次连接。
📄 许可证
MIT许可证-请参阅 许可证 了解详情。