内容
# 针垫 MCP 服务器
用于 AI 原生开发的实现上下文层。利益相关者可以在实时应用的任何页面上放置视觉图钉；您的 AI 编码代理通过 MCP 读取每个图钉并发送修复程序 — 在 Claude Code、Cursor、VS Code、Windsurf 或任何 MCP 客户端中。
## 什么使针垫图钉与众不同
图钉不是反馈项 — 它是一个**代理工作包**。每个包都包含代理实施更改所需的一切，无需反复沟通：
- **URL + 元素选择器** — 确切的内容，确切的位置
- **截图 + 视口 + DOM 片段** — 视觉和结构上下文
- **线程 + 项目上下文** — 对话和代码库
- **可能的 文件 + 验收标准** — 查找位置和确认完成
循环自动闭合：利益相关者放置图钉 → 代理通过 MCP 读取并在 IDE 中修复 → 解析记录提交、分支和 PR → 可选的部署后审查验证修复实际完成。
该服务器还用于 Pincushion AI 在实时页面上运行设计/复制/a11y 审查并直接将图钉写回页面。
## 安装
```bash
# npm
npm install -g pincushion-mcp
# pnpm
pnpm add -g pincushion-mcp
# yarn
yarn global add pincushion-mcp
```
或直接运行而无需安装：
```bash
# npm
npx pincushion-mcp --project-dir .
# pnpm
pnpm dlx pincushion-mcp --project-dir .
# yarn
yarn dlx pincushion-mcp --project-dir .
```
## 快速入门
### 1. 安装浏览器扩展
从 [pincushion.io/install/chrome](https://pincushion.io/install/chrome) 下载 Pincushion Chrome 扩展。
### 2. 配置您的代理
选择下面的 AI 代理并按照您的设置的配置进行操作。
### 3. 开始使用
配置完成后，您的代理可以：
- 查看所有反馈：`get_feedback_summary`
- 查找特定图钉：`search_annotations`
- 修复并标记为完成：`fix_and_resolve`
---
## 代理配置指南
### Cursor
**文件：** `.cursor/mcp.json`
```json
{
"mcpServers": {
"pincushion": {
"command": "npx",
"args": ["pincushion-mcp", "--project-dir", "."]
}
}
}
```
> **pnpm / yarn 用户：** 将 `"command": "npx"` 替换为 `"command": "pnpm"` 并添加 `"dlx"` 作为第一个参数，或使用 `"command": "yarn"` 并同样使用 `"dlx"`。
**使用 Supabase 同步：**
```json
{
"mcpServers": {
"pincushion": {
"command": "npx",
"args": [
"pincushion-mcp",
"--project-dir", ".",
"--sync-url", "https://your-supabase.com/api",
"--api-key", "YOUR_API_KEY"
]
}
}
}
```
### Claude Desktop
**文件：** `~/.config/Claude/claude_desktop_config.json` （Linux/Windows）
或 `~/Library/Application Support/Claude/claude_desktop_config.json` （macOS）
```json
{
"mcpServers": {
"pincushion": {
"command": "npx",
"args": ["pincushion-mcp", "--project-dir", "/path/to/your/project"]
}
}
}
```
**pnpm 用户：**
```json
{
"mcpServers": {
"pincushion": {
"command": "pnpm",
"args": ["dlx", "pincushion-mcp", "--project-dir", "/path/to/your/project"]
}
}
}
```
**yarn 用户：**
```json
{
"mcpServers": {
"pincushion": {
"command": "yarn",
"args": ["dlx", "pincushion-mcp", "--project-dir", "/path/to/your/project"]
}
}
}
```
**使用 Supabase 同步：**
```json
{
"mcpServers": {
"pincushion": {
"command": "npx",
"args": [
"pincushion-mcp",
"--project-dir", "/path/to/your/project",
"--sync-url", "https://your-supabase.com/api",
"--api-key", "YOUR_API_KEY"
]
}
}
}
```
### Claude Code (CLI)
运行此命令将 Pincushion 添加到 Claude Code：
```bash
claude mcp add pincushion -- npx pincushion-mcp --project-dir .
```
或使用 Supabase 同步：
```bash
claude mcp add pincushion -- npx pincushion-mcp --project-dir . --sync-url https://your-supabase.com/api --api-key YOUR_API_KEY
```
### VS Code (Copilot / Continue)
**文件：** `.vscode/settings.json`
```json
{
"mcp.servers": {
"pincushion": {
"command": "npx",
"args": ["pincushion-mcp", "--project-dir", "${workspaceFolder}"]
}
}
}
```
### Windsurf / Codeium Windsurf
**文件：** `~/.windsurf/mcp.json` 或 `~/.config/windsurf/mcp.json`
```json
{
"mcpServers": {
"pincushion": {
"command": "npx",
"args": ["pincushion-mcp", "--project-dir", "."]
}
}
}
```
### Antigravity
**文件：** `~/.antigravity/mcp.json`
```json
{
"mcpServers": {
"pincushion": {
"command": "npx",
"args": ["pincushion-mcp", "--project-dir", "."]
}
}
}
```
### OpenAI Codex / REST API 客户端
对于不支持 MCP 的工具，请使用 REST API 包装器：
```bash
npx pincushion-mcp --rest --port 3456
```
这会在 `localhost:3456` 启动一个 HTTP 服务器。 端点：
- `GET /health` — 检查服务器状态
- `POST /call-tool` — 调用工具
- 正文： `{ "toolName": "get_feedback_summary", "args": {} }`
使用 curl 的示例：
```bash
curl -X POST http://localhost:3456/call-tool \
-H "Content-Type: application/json" \
-d '{"toolName": "get_feedback_summary", "args": {}}'
```
---
## CLI 标志
```bash
npx pincushion-mcp [flags]
```
| 标志 | 描述 | 默认值 |
|------|-------------|---------|
| `--project-dir PATH` | 包含 `.feedback/` 的根目录 | 当前工作目录 |
| `--sync-url URL` | 用于远程同步的 Supabase API 端点 | 无（仅限本地） |
| `--api-key KEY` | 用于 Supabase 身份验证的 API 密钥 | 无 |
| `--license-key KEY` | 专业许可证密钥（可选） | 无 |
| `--rest` | 启用 REST API 模式 | 禁用（使用 MCP/stdio） |
| `--port PORT` | REST API 服务器的端口 | 3456 |
### 示例
**本地项目：**
```bash
npx pincushion-mcp --project-dir /path/to/project
```
**使用 Supabase 同步：**
```bash
npx pincushion-mcp \
--project-dir /path/to/project \
--sync-url https://abcd1234.supabase.co/api \
--api-key sb_project_key_abc123...
```
**REST API 服务器：**
```bash
npx pincushion-mcp --rest --port 8080
```
---
## 工具
### `get_annotations`
从 `.feedback/` 检索注释。 按页面、组件或状态过滤。
**参数：**
- `pageUrl` （字符串，可选） — 按页面 URL 过滤（部分匹配）
- `componentName` （字符串，可选） — 按 LWC 组件名称过滤
- `status` （字符串，可选） — 按 `open`、`in-progress` 或 `resolved` 过滤
**示例：**
```javascript
await mcp.callTool('get_annotations', {
componentName: 'wmlHomePage',
status: 'open'
});
```
### `search_annotations`
跨所有注释、评论、选择器和标签进行全文搜索。
**参数：**
- `query` （字符串，必填） — 搜索词
**示例：**
```javascript
await mcp.callTool('search_annotations', {
query: 'button label'
});
```
### `get_feedback_summary`
所有反馈的高级汇总：按状态、优先级、页面和组件进行统计。
**示例：**
```javascript
await mcp.callTool('get_feedback_summary', {});
```
### `get_component_feedback`
获取特定 LWC 组件的所有反馈，并附有纯语言摘要。
**参数：**
- `componentName` （字符串，必填） — LWC 组件名称
**示例：**
```javascript
await mcp.callTool('get_component_feedback', {
componentName: 'wmlHomePage'
});
```
### `resolve_annotation`
在修复问题后将注释标记为已解决。
**参数：**
- `annotationId` （字符串，必填） — 注释 ID
- `comment` （字符串，可选） — 解析消息
- `resolvedBy` （字符串，可选） — 归因于解析的姓名（默认：”AI 代理”）
**示例：**
```javascript
await mcp.callTool('resolve_annotation', {
annotationId: 'ann_abc123',
comment: '在 wmlHomePage.js 的第 42 行更新了按钮标签'
});
```
### `add_agent_reply`
向注释线程添加回复（例如，提出澄清问题）。
**参数：**
- `annotationId` （字符串，必填） — 注释 ID
- `body` （字符串，必填） — 回复消息
- `author` （字符串，可选） — 作者姓名（默认：”AI 代理”）
**示例：**
```javascript
await mcp.callTool('add_agent_reply', {
annotationId: 'ann_abc123',
body: '这个按钮在主导航还是侧边栏？'
});
```
### `fix_and_resolve`
结合修复代码和将注释标记为已解决在一个调用中。 可选地记录提交/分支/PR 元数据，以便仪表板可以链接到实际部署的内容。
**参数：**
- `annotationId` （字符串，必填） — 注释 ID
- `fixDescription` （字符串，必填） — 修复描述
- `filePath` （字符串，可选） — 应用修复的文件
- `lineNumber` （数字，可选） — 修复的行号
- `commitSha` （字符串，可选） — 提交 SHA
- `branchName` （字符串，可选） — 提交的分支
- `prUrl` （字符串，可选） — 拉取请求 URL（GitHub/GitLab/Bitbucket；形状验证）
**示例：**
```javascript
await mcp.callTool('fix_and_resolve', {
annotationId: 'ann_abc123',
fixDescription: '更新按钮标签以匹配设计规范',
filePath: 'src/components/wmlHomePage.js',
lineNumber: 42,
commitSha: 'abc123def456',
branchName: 'pincushion/checkout-fix',
prUrl: 'https://github.com/acme/app/pull/142'
});
```
### `get_implementation_packet`
获取单个实现包的页面 URL — 选择器列表、完整的图钉有效载荷、建议的分支名称和可追溯性配置。 当代理想要在单个分支中批量修复一个页面时使用。
```javascript
await mcp.callTool('get_implementation_packet', { pageUrl: '/checkout' });
```
### `assign_pin_to_agent`
直接将图钉派发到本地编码代理。 如果尚未，推广图钉到 `ready`，标记 `pending_implementation`，并写入 `.feedback/.agent-queue/<id>.json` 触发文件，`agent-loop.mjs` 读取并 shell 到 Cursor / Claude Code / Codex。
```javascript
await mcp.callTool('assign_pin_to_agent', { annotationId: 'ann_abc123' });
```
### `link_pin_deploy`
将部署 URL 附加到已解决的图钉。 通常由部署钩子边缘函数在生产包含修复后调用，但也可手动调用。
```javascript
await mcp.callTool('link_pin_deploy', {
annotationId: 'ann_abc123',
deployUrl: 'https://acme-app.vercel.app'
});
```
### `record_pin_verification`
写入 Pincushion AI 的部署后判决回图钉。 由批评者代理在 `/critique-latest-deploy` 在新鲜部署后运行调用。
```javascript
await mcp.callTool('record_pin_verification', {
annotationId: 'ann_abc123',
status: 'verified', // 或 'regressed' 或 'inconclusive'
notes: '按钮匹配主令牌。 邻近 CTAs 无回归。'
});
```
### `get_time_to_fix_metrics`
**专业/团队功能** — 免费调用者获取样本大小 + 升级提示。 中位数 + p25/p75 的图钉到解决时长，至少有 5 个图钉，因此指标永远不会有噪音。
```javascript
await mcp.callTool('get_time_to_fix_metrics', { scope: 'project', projectId: 'pc_proj_abc' });
// → { sampleSize, thresholdMet, median, p25, p75, medianHuman, ... }
```
### `get_setup_instructions` (NEW)
获取所有支持的代理的设置和配置说明。
**示例：```javascript
await mcp.callTool('get_setup_instructions', {});
```
### Slack 和 Microsoft Teams 集成
Pincushion 可以通过项目范围的传入 webhook 通知 Slack 或 Microsoft Teams。 默认设置是故意安静且受 Figma 启发的：仅在图钉准备好实施时通知，在有人 @mentioned 时通知，以及当协作者添加后续工作时通知。 每个新图钉和每个解析都是可选事件。
**推荐用例：**
- 开发者频道：`pin_ready` 和 `follow_up`
- 设计或 PM 频道：`mention` 和可选 `resolved`
- 发布或 QA 频道：`pageUrlPatterns` 加 `pin_ready`、`follow_up` 和 `resolved`
- 临时事件频道：启用有针对性的订阅，然后在发货窗口后暂停它
**示例：```javascript
await mcp.callTool('configure_collaboration_integration', {
projectId: 'my-project',
provider: 'slack',
webhookUrl: 'https://hooks.slack.com/services/...',
targetLabel: '#product-feedback',
events: ['pin_ready', 'mention', 'follow_up'],
pageUrlPatterns: ['staging.example.com/checkout'],
sendTest: true
});
```
对于 Slack，请使用 `create_slack_install_link`，当托管 Slack 应用秘密配置时，它会返回一个 Add-to-Slack URL；之后，Slack 返回传入的 webhook，Pincushion 自动存储它。
使用 `list_collaboration_integrations` 审计配置的目的地，`remove_collaboration_integration` 断开连接一个，`preview_collaboration_notification` 查看有效载体形状添加真实的 webhook URL。 Webhook URL 存储在服务器端，并仅作为掩码值返回。
---
## 自动代理循环（可选）
对于不监视文件系统（Claude Code、Cursor，通用）的代理，`agent-loop.mjs` 轮询 `.feedback/.agent-queue/` 并将新的图钉派发到配置的代理。
```bash
# 从 inside the pincushion-mcp 目录
npm run agent-loop -- --project-dir /path/to/your/project
# 或直接
node agent-loop.mjs --project-dir /path/to/your/project [--agent claude-code|cursor|generic] [--interval 3000]
```
桥（server.js）为批准的文件：
```bash
# from inside the pincushion-mcp directory
npm run agent-loop -- --project-dir /path/to/your/project
# or directly
node agent-loop.mjs --project-dir /path/to/your/project [--agent claude-code|cursor|generic] [--interval 3000]
```
Bridge（`server.js`）为每个已批准的图钉写入一个触发文件到 `.feedback/.agent-queue/`。循环读取它们，构建图钉的线程 + 元素选择器提示，并 shell 到所选代理。代理使用 MCP 工具（`claim_pin` → 修复 → `fix_and_resolve`）和队列文件在图钉关闭时被删除。
`detectAgent()` 自动检测 `claude` 或 `cursor` 在 `PATH` 上；否则，默认为 `generic`（将提示写入 `.feedback/.agent-prompt` 和 stdout）。运行 `--interval 3000` 以控制轮询节奏。
---
## 本地文件结构
服务器从项目中的 `.feedback/` 读取注释：
```
.feedback/
├── annotations/
│ ├── example-com-login.json
│ ├── example-com-dashboard.json
│ └── ...
└── index.json
```
每个注释文件包含：
```json
{
"pageUrl": "https://example.com/login",
"pageTitle": "登录",
"annotations": [
{
"id": "ann_abc123",
"status": "open",
"priority": "high",
"tags": ["design", "accessibility"],
"createdAt": "2026-03-19T10:30:00Z",
"element": {
"lwcComponent": "wmlLoginForm",
"selector": ".login-button",
"textContent": "登录"
},
"thread": [
{
"author": "设计团队",
"timestamp": "2026-流士-19T10:30:00Z",
"body": "按钮标签应为'Sign In'而不是'登录'",
"type": "comment"
}
]
}
]
}
```
---
## Supabase 同步
要与远程 Supabase 数据库同步注释：
1. 在 [supabase.com](https://supabase.com) 建立一个 Supabase 项目
2. 创建一个 `annotations` 表，包含与注释模式匹配的列
3. 从项目设置中生成一个 API 密钥
4. 使用 `--sync-url` 和 `--api-key` 配置服务器
**示例：**
```bash
npx pincushion-mcp \
--project-dir . \
--sync-url https://your-project.supabase.co/rest/v1 \
--api-key sb_project_key_abc123...
```
服务器将本地 `.feedback/` 文件与远程数据合并，远程数据在更新时间上具有更高的优先级。
---
## 专业许可证
Pincushion 专业版包含额外功能。 使用 `--license-key` 激活：
```bash
npx pincushion-mcp --project-dir . --license-key YOUR_PRO_KEY
```
---
## 故障排除
### “模块未找到”错误
确保您已安装 Node.js 18+：
```bash
node --version
```
安装依赖项：
```bash
npm install @modelcontextprotocol/sdk
```
### 注释未显示
检查 `.feedback/` 是否存在于您的项目目录中：
```bash
ls -la .feedback/
```
如果它不存在，请创建它并添加一些测试注释，否则扩展程序将在您固定第一个反馈时创建它。
### Supabase 同步不起作用
验证您的凭证：
```bash
curl -H "x-api-key: YOUR_API_KEY" \
https://your-project.supabase.co/rest/v1/annotations
```
### 代理找不到服务器
在您的代理配置中使用完整路径到 `pincushion-mcp`:
```bash
which pincushion-mcp
# 使用输出路径在您的配置中使用
```
或使用 `npx` 让它找到包：
```json
{
"command": "npx",
"args": ["pincushion-mcp", "--project-dir", "."]
}
```
---
## 开发
克隆存储库并安装依赖项：
```bash
git clone https://github.com/jcooley8/pincushion-plugin.git
cd pincushion-plugin
npm install
```
运行服务器：
```bash
npm start
```
或使用测试数据：
```bash
npm start -- --project-dir ./test-feedback
```
---
## 许可证
MIT 许可证。 有关详细信息，请参阅 LICENSE 文件。
---
## 支持
- **问题：** [GitHub Issues](https://github.com/jcooley8/pincushion-plugin/issues)
- **文档：** [Pincushion 文档](https://pincushion.io/docs)
---
## 更新日志
### v1.0.0（2026 年 3 月）
- 初始发布
- 支持 Cursor、Claude Desktop、Claude Code、VS Code、Windsurf、Antigravity
- 本地 `.feedback/` 文件支持
- Supabase 远程同步
- 非 MCP 客户端的 REST API 包装器
- 新工具：`fix_and_resolve`、`get_setup_instructions`
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器