内容
# OpenCode Agentation MCP 集成
通过MCP（模型上下文协议）将OpenCode代理连接到Agentation UI注释系统。
## 概述
该MCP服务器通过将Agentation的注释系统与OpenCode的AI代理集成，实现无缝的 **UI反馈 → AI代理 → 代码修复** 工作流程。
### 功能特点
- 🔗 **MCP协议支持** - 原生模型上下文协议集成
- 📝 **实时注释** - 处理UI反馈时实时创建
- 🤖 **AI代理就绪** - 连接到Claude Code、Cursor和其他AI工具
- 🔧 **多种模式** - 手动、无人值守、批评和自动驾驶模式
- 📊 **丰富上下文** - CSS选择器、React组件、辅助功能信息
- 💬 **双向通信** - 代理可以询问澄清问题
## 安装
### 前提条件
- Node.js 18+
- npm 或 pnpm
### 快速安装
```bash
# 全局安装
npm install -g agentation-mcp
# 或克隆此仓库
git clone https://github.com/YOUR_USERNAME/opencode-agentation-mcp.git
cd opencode-agentation-mcp
npm install
```
### 启动服务器
```bash
npm start
```
或在后台运行:
```bash
npm start > /tmp/agentation-mcp.log 2>&1 &
```
## 快速入门
### 1. 验证服务器正在运行
```bash
curl http://localhost:4747/health
```
预期响应：
```json
{
"status": "ok",
"mode": "local"
}
```
### 2. 连接到OpenCode
将以下内容添加到您的OpenCode MCP配置中：
```json
{
"mcpServers": {
"agentation": {
"command": "npx",
"args": ["agentation-mcp", "server", "--port", "4747"]
}
}
}
```
## 可用工具
### 查询工具
| 工具 | 描述 |
|------|-------------|
| `agentation_list_sessions` | 列出所有活动注释会话 |
| `agentation_get_session` | 获取具有所有注释的会话 |
| `agentation_get_pending` | 获取会话的待处理注释 |
| `agentation_get_all_pending` | 获取跨会话的所有待处理注释 |
### 操作工具
| 工具 | 描述 |
|------|-------------|
| `agentation_acknowledge` | 标记注释为已确认 |
| `agentation_resolve` | 标记注释为已解决 |
| `agentation_dismiss` | 驳回注释并附上原因 |
| `agentation_reply` | 添加回复到注释线程 |
### 监视模式
| 工具 | 描述 |
|------|-------------|
| `agentation_watch_annotations` | 阻塞直到出现新注释 |
## 使用示例
### 基本工作流程
```typescript
import { agentationTools } from './tools.js';
// 检查待处理注释
const pending = await agentationTools.agentation_get_all_pending();
if (pending.count > 0) {
console.log(`发现 ${pending.count} 个待处理注释`);
// 处理每个注释
for (const annotation of pending.annotations) {
// 确认
await agentationTools.agentation_acknowledge(annotation.id);
// 修复问题
await coderAgent.fixIssue(annotation);
// 解析
await agentationTools.agentation_resolve(
annotation.id,
"已修复填充问题"
);
}
}
```
### 无人值守模式
```typescript
// 自动处理注释
while (true) {
const batch = await agentationTools.agentation_watch_annotations({
batchWindowSeconds: 10,
timeoutSeconds: 120,
});
for (const annotation of batch.annotations) {
await agentationTools.agentation_acknowledge(annotation.id);
await coderAgent.fixIssue(annotation);
await agentationTools.agentation_resolve(annotation.id, "问题已修复");
}
}
```
### 基于优先级的处理
```typescript
const pending = await agentationTools.agentation_get_all_pending();
// 按优先级排序（阻塞 > 重要 > 建议）
const sorted = agentationTools.agentation_sort_by_priority(pending.annotations);
// 首先处理阻塞问题
for (const annotation of sorted) {
await agentationTools.agentation_acknowledge(annotation.id);
await coderAgent.fixIssue(annotation);
await agentationTools.agentation_resolve(annotation.id, "问题已修复");
}
```
## API 端点
### 健康检查和状态
- `GET /health` - 服务器健康检查
- `GET /status` - 服务器状态和正常运行时间
### 会话
- `GET /sessions` - 列出所有会话
- `POST /sessions` - 创建新会话
- `GET /sessions/:id` - 获取具有注释的会话
### 注释
- `GET /pending` - 获取所有待处理注释
- `GET /sessions/:id/pending` - 获取会话的待处理注释
- `POST /sessions/:id/annotations` - 创建注释
- `POST /annotations/:id/acknowledge` - 确认
- `POST /annotations/:id/resolve` - 解析
- `POST /annotations/:id/dismiss` - 驳回
- `POST /annotations/:id/thread` - 回复
### 事件
- `GET /events` - 全局事件流（SSE）
- `GET /sessions/:id/events` - 会话事件流（SSE）
## 注释对象
```typescript
{
id: string; // 唯一标识符
comment: string; // 用户反馈
elementPath: string; // CSS选择器路径
timestamp: number; // Unix时间戳（毫秒）
x: number; // 视口宽度的百分比（0-100）
y: number; // 距文档顶部的像素
element: string; // 标签名称（“button”，“div”）
url?: string; // 页面URL
boundingBox?: { // 元素尺寸
x: number;
y: number;
width: number;
height: number;
};
reactComponents?: string; // 组件树
cssClasses?: string; // 类列表
computedStyles?: string; // 关键CSS属性
accessibility?: string; // ARIA属性
nearbyText?: string; // 可见文本
selectedText?: string; // 高亮文本
intent?: "fix" | "change" | "question" | "approve";
severity?: "blocking" | "important" | "suggestion";
status?: "pending" | "acknowledged" | "resolved" | "dismissed";
thread?: ThreadMessage[]; // 对话线程
}
```
## 架构
```
用户（浏览器）→ Agentation 工具栏 → Agentation MCP 服务器（localhost:4747）
↓
OpenCode 代理
↓
代码更改
↓
注释已解决
```
## 项目结构
```
opencode-agentation-mcp/
├── types.ts # TypeScript 类型定义
├── client.ts # Agentation API 的 HTTP 客户端
├── tools.ts # MCP 工具实现
├── test.ts # 测试套件
├── demo.ts # 演示脚本
├── package.json # 包配置
├── LICENSE # MIT 许可证
├── .gitignore # Git 忽略文件
└── README.md # 文档
```
## 脚本
```bash
npm install # 安装依赖
npm run test # 运行测试套件
npm run demo # 运行演示脚本
npm run type-check # TypeScript 类型检查
npm start # 启动 MCP 服务器
```
## 测试
### 手动测试
```bash
# 健康检查
curl http://localhost:4747/health
# 列出会话
curl http://localhost:4747/sessions
# 获取待处理注释
curl http://localhost:4747/pending
```
### 自动测试
```bash
npm test
```
## 故障排除
### 服务器未运行
```bash
# 检查服务器是否运行
curl http://localhost:4747/health
# 启动服务器
npm start
# 检查日志
tail -f /tmp/agentation-mcp.log
```
### 未找到注释
```bash
# 检查会话
curl http://localhost:4747/sessions
# 检查待处理注释
curl http://localhost:4747/pending
```
### 连接问题
```bash
# 验证服务器是否可访问
npx agentation-mcp doctor
# 检查服务器日志
tail -f /tmp/agentation-mcp.log
```
## 资源
- [Agentation 文档](https://www.agentation.com/)
- [MCP 协议](https://modelcontextprotocol.io/)
- [Agentation GitHub](https://github.com/benjitaylor/agentation)
## 许可证
MIT 许可证 - 参见 LICENSE 文件了解详情。
## 支持
如有问题或疑问：
1. 检查服务器是否运行：`curl http://localhost:4747/health`
2. 运行诊断：`npx agentation-mcp doctor`
3. 查看本文档
4. 在 GitHub 上提出问题
## 贡献
欢迎贡献！请在 GitHub 上提出问题或提交拉取请求。
---
**版本：** 1.0.0
**最后更新：** 2026-03-16
**状态：** ✅ 生产就绪
