光标伙伴MCP
项目介绍
<div align="center">
</div>
</div>
<div align="center">
Cursor Buddy MCP
🤖 让AI代理保持上下文感知与一致性
将您的AI助手转变为一个理解项目标准、约定和历史的上下文感知编码伙伴。
</div>🎯 为什么选择 Cursor Buddy MCP？
<table> <tr> <td width="50%">🧠 上下文感知AI
您的AI助手立即了解您的编码标准、架构模式和项目约定。
📚 集中知识
所有项目文档和指南在一个可搜索的位置。
✅ 进度跟踪
自动待办事项管理和实现历史跟踪。
</td> <td width="50%">🔄 实时更新
文件监控确保您的AI始终拥有最新信息。
🚀 零设置摩擦
即插即用的Docker容器，立即集成MCP。
🔍 智能搜索
在整个项目上下文中快速找到相关结果。
</td> </tr> </table>📋 目录
🏗️ 架构
<div align="center">graph TB
A[AI助手] --> B[MCP客户端]
B --> C[Cursor Buddy MCP服务器]
C --> D[.buddy目录]
D --> E[规则]
D --> F[知识]
D --> G[待办事项]
D --> H[数据库]
D --> I[历史]
D --> J[备份]
C --> K[搜索引擎]
C --> L[文件监控]
C --> M[备份管理]
style A fill:#e1f5fe
style C fill:#f3e5f5
style K fill:#e8f5e8
基于模型上下文协议（MCP），使用来自mark3labs/mcp-go的Go SDK构建。通过JSON-RPC 2.0在标准输入/输出上进行通信，使其与像Claude Desktop这样的MCP客户端兼容。
🎨 特性
| 特性 | 描述 |
|---|---|
| 🔧 工具 | 6个用于管理项目上下文的交互式工具 |
| 📊 资源 | 包含完整项目状态的项目上下文资源 |
| 🔄 标准输入/输出传输 | 标准输入/输出通信 |
| ⚡ 实时更新 | 文件监控并自动重新加载 |
| 🔍 全文搜索 | 使用Bleve在整个内容中进行搜索 |
| 💾 自动备份 | 安全修改文件并具有回滚能力 |
🚀 快速开始
1️⃣ 从GitHub注册表拉取
docker pull ghcr.io/omar-haris/cursor-buddy-mcp:latest
2️⃣ 配置Cursor
添加到.cursor/mcp.json：
⚠️ 重要提示：将
/path/to/your/project/替换为您实际的项目目录路径！
{
"mcpServers": {
"cursor-buddy-mcp": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "/path/to/your/project/.buddy:/home/buddy/.buddy",
"-e", "BUDDY_PATH=/home/buddy/.buddy",
"ghcr.io/omar-haris/cursor-buddy-mcp:latest"
]
}
}
}
示例：
- Linux/macOS:
"/home/user/myproject/.buddy:/home/buddy/.buddy" - Windows:
"C:/Users/User/myproject/.buddy:/home/buddy/.buddy" - 当前目录:
"${PWD}/.buddy:/home/buddy/.buddy"
💡 如何找到您的项目路径：
# 导航到您的项目目录并运行：
pwd
# 复制输出并替换 /path/to/your/project/ 为：{output}/.buddy
3️⃣ 创建.buddy结构
导航到您的项目目录并运行：
mkdir -p .buddy/{rules,knowledge,todos,database,history,backups}
📁 这将创建：
your-project/
├── .buddy/
│ ├── rules/
│ ├── knowledge/
│ ├── todos/
│ ├── database/
│ ├── history/
│ └── backups/
4️⃣ 添加您的内容
根据下面的文档在.buddy/文件夹中创建文件。
🔧 可用工具
<table> <tr> <td width="50%">📋 buddy_get_rules
获取编码标准和指南
- 按类别或优先级过滤
- 支持多种规则类型
🔍 buddy_search_knowledge
搜索项目文档
- 在所有知识中进行全文搜索
- 类别和标签过滤
✅ buddy_manage_todos
列出/更新任务并跟踪进度
- 基于功能组织
- 进度跟踪和完成
🗄️ buddy_get_database_info
获取模式信息并验证查询
- 表模式信息
- 查询验证和示例
📚 buddy_history
跟踪实现更改并搜索历史记录
- 实现时间线
- 功能开发跟踪
💾 buddy_backup
创建和管理文件备份
- 自动创建备份
- 安全修改文件
💡 使用示例
向您的AI助手提问，例如：
<div align="center">| 🎯 类别 | 💬 示例问题 |
|---|---|
| 📋 编码标准 | "我们的错误处理编码标准是什么？" |
| ✅ 项目进度 | "显示当前身份验证功能的待办事项" |
| 📖 文档 | "搜索关于用户端点的API文档" |
| 🗄️ 数据库 | "用户的数据库模式是什么？" |
| 📚 历史 | "我们上个月是如何实现JWT认证的？" |
| 🔧 架构 | "我应该为此功能使用哪些设计模式？" |
📚 文档
📋 规则文件
位置：
.buddy/rules/
目的：定义编码标准、架构模式和指南
📝 格式要求
- ✅ 使用Markdown格式（
.md） - ✅ 包括元数据：
category和priority - ✅ 使用清晰的部分和子部分组织
🔧 示例：编码标准
<details> <summary>点击展开编码标准示例</summary># 编码标准
- category: 编码
- priority: 关键
## 概述
项目的编码标准和最佳实践。
## Go特定标准
- 遵循Go命名约定（驼峰式，帕斯卡式）
- 使用`gofmt`进行代码格式化
- 显式处理错误，不要忽略它们
- 使用接口进行抽象
## 错误处理
- 始终检查并处理错误
- 使用结构化的错误类型
- 使用`fmt.Errorf`包装错误并提供上下文
- 返回有意义的错误消息
## 测试
- 为所有公共函数编写单元测试
- 使用表格驱动测试多个测试用例
- 达到至少80%的代码覆盖率
🏗️ 示例：架构模式
<details> <summary>点击展开架构模式示例</summary># 架构模式
- category: 架构
- priority: 关键
## 设计原则
- **单一职责**：每个组件只有一个变更原因
- **依赖倒置**：依赖于抽象，而不是具体实现
## 推荐模式
### 仓库模式
- 封装数据访问逻辑
- 提供一致的数据操作接口
- 便于使用模拟实现进行轻松测试
### 层次架构
┌─────────────────────┐
│ 表现层 │ ← HTTP处理器，CLI
├─────────────────────┤
│ 业务逻辑 │ ← 领域模型，用例
├─────────────────────┤
│ 数据访问 │ ← 仓库，数据库
└─────────────────────┘
📖 知识文件
位置：
.buddy/knowledge/
目的：存储项目文档、API规范和技术信息
📝 格式要求
- ✅ 使用Markdown格式（
.md） - ✅ 包括元数据：
category和可选的tags - ✅ 使用清晰的标题和示例进行结构化
🌐 示例：API文档
<details> <summary>点击展开API文档示例</summary># API文档
- category: 架构
- tags: api, rest, 认证
## 认证端点
### POST /auth/login
**请求：**
```json
{
"email": "user@example.com",
"password": "secure_password"
}
响应：
{
"token": "jwt_token_here",
"user": {
"id": 123,
"email": "user@example.com",
"role": "user"
}
}
GET /auth/me
头信息：Authorization: Bearer <token>
响应：
{
"user": {
"id": 123,
"email": "user@example.com",
"role": "user"
}
}
错误处理
所有端点返回错误的格式如下：
{
"error": "错误代码",
"message": "人类可读的消息"
}
</details>
---
### ✅ 待办事项文件
> **位置**：`.buddy/todos/`
> **目的**：跟踪任务、功能和项目进度
#### 📝 格式要求
- ✅ 使用Markdown格式（`.md`）
- ✅ 使用复选框语法：`- [ ]`（未完成）或`- [x]`（已完成）
- ✅ 将相关任务分组在清晰的标题下
- ✅ 为每个任务提供上下文和详细信息
#### 🔐 示例：功能开发
<details>
<summary>点击展开功能开发示例</summary>
```markdown
# 认证功能
## 后端实现
- [x] 设置JWT库
- [x] 创建用户模型和数据库迁移
- [x] 使用bcrypt实现密码哈希
- [ ] 创建登录端点
- [ ] 创建注册端点
- [ ] 为受保护的路由添加中间件
- [ ] 为认证服务编写单元测试
- [ ] 为认证端点添加集成测试
## 前端实现
- [ ] 创建登录表单组件
- [ ] 创建注册表单组件
- [ ] 实现JWT令牌存储
- [ ] 添加认证上下文
- [ ] 创建受保护的路由包装器
- [ ] 处理令牌刷新逻辑
## 安全性和测试
- [ ] 为认证端点添加速率限制
- [ ] 实现在多次失败尝试后锁定账户
- [ ] 添加密码强度验证
- [ ] 对认证实现进行安全审计
- [ ] 对认证端点进行负载测试
🗄️ 数据库文件
位置：
.buddy/database/
目的：存储SQL模式定义、迁移和查询示例
📝 示例：模式定义
<details> <summary>点击展开数据库模式示例</summary>-- 用户表
CREATE TABLE users (
id SERIAL PRIMARY KEY,
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
role VARCHAR(50) DEFAULT 'user',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- 会话表用于JWT黑名单
CREATE TABLE sessions (
id SERIAL PRIMARY KEY,
user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
token_hash VARCHAR(255) UNIQUE NOT NULL,
expires_at TIMESTAMP NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- 性能索引
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_sessions_token_hash ON sessions(token_hash);
CREATE INDEX idx_sessions_expires_at ON sessions(expires_at);
💎 最佳实践
<div align="center">| 🎯 实践 | 📝 描述 |
|---|---|
| 🔍 具体明确 | 包含具体的示例和代码片段 |
| 🔄 定期审查 | 定期审查并更新您的文件 |
| 📐 一致格式 | 在相似文件中遵循相同的结构 |
| 💡 提供上下文 | 添加解释说明规则或模式存在的原因 |
| 🔗 链接信息 | 引用相关的文件或外部文档 |
| 📊 版本控制 | 将您的.buddy文件夹纳入版本控制 |
| 🔄 定期评审 | 定期安排对知识库的评审 |
🔧 高级功能
🔍 文件监控
服务器自动监控您的.buddy目录中的更改，并实时重新加载内容。
🔎 搜索集成
使用Bleve全文搜索，在整个项目上下文中快速找到相关结果。
💾 备份管理
在修改之前自动创建重要文件的备份。
🏗️ 可扩展架构
使用Go构建，以实现高性能和易于扩展的新工具和功能。
🤝 贡献
我们欢迎贡献！以下是一些您可以帮助的方式：
<div align="center">
🎉 准备开始了吗？
您的AI助手现在将深入了解您的代码库，并能够提供一致且有见地的回答。
由开发者为开发者制作 ❤️
</div>