MCPolly

MCPolly

面向 AI Agent 的 Agent 原生状态、可观测性和知识平台。MCPolly 是一个 MCP 服务，可让 AI Agent 实时报告进度、错误和状态，并为人类提供统一的 Web 仪表盘来监控一切。Agent 还可以索引并语义搜索产品文档，以保持信息同步。

使用 Rust、Axum、SQLite 和 HTMX 构建。专为在最低限度的硬件上自托管而设计。

架构

┌─────────────────┐   MCP Streamable HTTP   ┌──────────────────┐
│  AI Agent       │◄───────────────────────►│  MCPolly Server  │
│  (Cursor, etc.) │   JSON-RPC / SSE        │  (Axum + SQLite) │
└─────────────────┘   Bearer auth           └──────┬───────────┘
                                                   │
                                          ┌────────▼────────┐
                                          │   Web Dashboard  │
                                          │   (HTMX UI)      │
                                          └─────────────────┘
                                                   │
                                          ┌────────▼────────┐
                                          │  Ollama (local)  │
                                          │  all-MiniLM      │
                                          └─────────────────┘

MCPolly 提供一个 /mcp 端点，使用 MCP Streamable HTTP 协议（通过 SSE 流传输的 HTTP 上的 JSON-RPC）。Agent 平台可直接连接，无需子进程二进制文件。

• MCPolly Server — Axum HTTP 服务，用于将 Agent 数据存储在 SQLite 中、提供 Web UI、评估告警规则、管理向量嵌入，并托管 MCP 端点。
• Ollama — 本地大模型服务，使用 all-MiniLM 模型（384 维）生成向量嵌入。
• mcpolly_mcp （可选） — 轻量级 stdio 二进制文件，供不支持 HTTP MCP 传输的平台使用。它在 stdio 与 MCPolly HTTP API 之间进行桥接。

功能

Agent 可观测性

• Agent 注册和状态跟踪（starting、running、warning、error、completed、offline、paused、errored、stopping、stopped）
• 实时活动动态，条目按颜色区分
• 跨所有 Agent 的全局错误动态
• Webhook 告警（Discord、Slack、通用）及重试逻辑
• 可为任意状态变更配置告警——error、completed、running、starting、warning、paused、stopped、offline，或适用于所有状态的兜底规则
• 静默 Agent 检测（后台检查器）

Web 仪表盘

• 深色模式，并检测系统偏好设置
• 首次运行设置向导，支持自动登录和 MCP 配置片段
• 在登录页面重置实例（撤销所有密钥、生成新密钥并重新进入设置向导）
• 健康状态摘要条（Agent 总数、运行中、出错和离线数量）
• 状态筛选标签，便于快速筛选 Agent
• Agent 详情页，包含标签式内容（活动、错误、信息）
• 全局命令栏（Cmd+K），可搜索 Agent、错误和知识
• 告警规则管理和通知历史
• 带语义搜索 UI 的知识页面
• API 密钥管理
• 设置页面，包含服务信息和会话管理
• 每 10 秒通过 HTMX 轮询，获取实时更新

知识层（向量嵌入）

• 将 PRD、设计文档和自定义文档索引为向量嵌入
• 通过 MCP 工具和 Web UI 对所有已索引内容进行语义搜索
• 启动产品经理和产品设计师 Agent，并提供相关上下文
• 由 sqlite-vec（进程内）和 Ollama（本地，无需云 API 密钥）提供支持

安装

选项 1：安装脚本（推荐）

自动检测操作系统和架构，并从 GitHub Releases 下载对应的二进制文件：

curl -fsSL https://raw.githubusercontent.com/MCPolly/mcpolly/main/install.sh | bash

使用环境变量进行自定义：

# Install only the MCP stdio bridge
MCPOLLY_BINARY=mcp curl -fsSL https://raw.githubusercontent.com/MCPolly/mcpolly/main/install.sh | bash

# Install to a custom directory
MCPOLLY_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/MCPolly/mcpolly/main/install.sh | bash

# Install a specific version
MCPOLLY_VERSION=v0.2.0 curl -fsSL https://raw.githubusercontent.com/MCPolly/mcpolly/main/install.sh | bash

支持的平台：Linux（x86_64、aarch64、armv7）、macOS（x86_64、Apple Silicon）、Windows（x86_64）。

选项 2：从源代码构建

git clone https://github.com/MCPolly/mcpolly.git
cd mcpolly
cargo build --release

二进制文件位于：

• target/release/mcpolly（HTTP 服务）
• target/release/mcpolly_mcp（MCP stdio 桥接程序）

选项 3：Cargo 安装

cargo install mcpolly --bin mcpolly_mcp

设置

1. 安装 Ollama（用于向量嵌入）

# Install Ollama (https://ollama.ai)
curl -fsSL https://ollama.ai/install.sh | sh

# Pull the embedding model
ollama pull all-minilm

# Ollama runs on http://localhost:11434 by default

向量嵌入为可选功能——MCPolly 无需 Ollama 也能运行，但语义搜索和携带上下文启动 Agent 的功能将不可用。

2. 启动 MCPolly 服务

PORT=3000 RUST_LOG=mcpolly=info ./mcpolly

SQLite 数据库（mcpolly.db）会在首次运行时自动创建。Web 仪表盘可通过 http://localhost:3000 访问。

3. 获取 API 密钥

首次运行时，MCPolly 会生成一个默认 API 密钥，并在浏览器中打开设置向导。向导会显示密钥，并提供可直接复制的 MCP 配置片段。密钥也会输出到服务终端：

╔═══════════════════════════════════════════════════════════════╗
║  DEFAULT API KEY (save this — it will not be shown again!)   ║
║                                                               ║
║  mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx          ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

你可以通过 Web UI 的“设置”页面创建其他密钥（http://localhost:3000/settings）。

忘记了 API 密钥？ 点击登录页面上的“忘记 API 密钥？重置实例”。这会撤销所有现有密钥、生成新密钥，并带你重新完成设置向导。

4. 配置 MCP 客户端

将 MCPolly 添加到 AI Agent 平台的 MCP 配置中。

Cursor（HTTP — 推荐）

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "mcpolly": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

这会通过 HTTP 直接连接到 MCPolly 服务的 MCP 端点。无需安装二进制文件。

Cursor（stdio — 替代方案）

如果你的平台不支持 HTTP MCP 传输，请使用 stdio 二进制文件：

{
  "mcpServers": {
    "mcpolly": {
      "command": "/path/to/mcpolly_mcp",
      "env": {
        "MCPOLLY_URL": "http://localhost:3000",
        "MCPOLLY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code

MCPolly 通过 HTTP 传输连接到 Claude Code。有两种配置方式。

选项 A：CLI（用户级，在所有项目中可用）

claude mcp add mcpolly --transport http http://localhost:3000/mcp \
  --header "Authorization: Bearer your-api-key-here"

选项 B：项目级 .mcp.json（提交到代码库）

在项目根目录中创建 .mcp.json：

{
  "mcpServers": {
    "mcpolly": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

这样，MCPolly 会自动用于该项目中的每个 Claude Code 会话，无需为每位用户单独设置。

自动批准 MCPolly 工具（不显示权限提示）：

将 mcp__mcpolly__* 添加到项目或用户设置中的允许列表：

# Project-level (.claude/settings.json — shared with team)
# or user-level (~/.claude/settings.json — personal)

{
  "permissions": {
    "allow": [
      "mcp__mcpolly__*"
    ]
  }
}

这样，Claude Code 就可以在后台调用所有 MCPolly 工具，无需每次都请求确认。

验证连接：

claude mcp list

MCPolly 应显示为 connected 状态。你也可以在 Claude Code 会话中进行测试：

“使用 mcpolly 列出所有已注册的 Agent。”

通过 CLAUDE.md 自动集成 Agent

若要让 Claude Code 自动注册自身，并在每项任务中发布状态更新，请将以下内容添加到项目的 CLAUDE.md：

## Agent Observability

At the start of every task:
1. Call `register_agent` with your agent name and a brief description.
2. Call `post_status` with state `starting` and a summary of the task.

As you work, call `post_status` at major milestones (state: `running`).

On completion, call `post_status` with state `completed`.

If you encounter an unrecoverable error, call `post_error` before stopping.

5. 为所有 Agent 会话启用 MCPolly（全局设置）

若要让所有 Claude Code 会话（跨所有项目）自动注册并向 MCPolly 报告状态，请全局配置 MCP 服务和 Agent 指令。

步骤 1：将 MCPolly 添加为全局 MCP 服务

claude mcp add mcpolly --transport http http://localhost:3000/mcp \
  --header "Authorization: Bearer your-api-key-here"

这样，无需为每个项目单独创建 .mcp.json 文件，即可在所有 Claude Code 会话中使用 MCPolly MCP 工具。

步骤 2：在全局范围内自动批准 MCPolly 工具

编辑 ~/.claude/settings.json（如果文件不存在，请创建）：

{
  "permissions": {
    "allow": [
      "mcp__mcpolly__*"
    ]
  }
}

这样，Claude Code 每次调用 MCPolly 工具时都不会提示请求权限。

步骤 3：将 Agent 指令添加到全局 CLAUDE.md

将 GLOBAL_CLAUDE.md 的内容追加到 ~/.claude/CLAUDE.md（如果文件不存在，请创建）：

cat /path/to/mcpolly/GLOBAL_CLAUDE.md >> ~/.claude/CLAUDE.md

或者手动添加：

## Agent Observability

At the start of every task:
1. Call `register_agent` with your agent name and a brief description.
2. Call `post_status` with state `starting` and a summary of the task.

As you work, call `post_status` at major milestones (state: `running`).

On completion, call `post_status` with state `completed`.

If you encounter an unrecoverable error, call `post_error` before stopping.

全局 ~/.claude/CLAUDE.md 文件会自动加载到每个 Claude Code 会话中。完成此设置后，任何项目中的每个 Agent 都会向 MCPolly 注册自身，在工作过程中发布状态更新，并报告完成情况或错误。

6. 验证

打开一个新的 Cursor Agent 会话，并要求它列出 Agent：

“使用 mcpolly 列出所有已注册的 Agent。”

自动集成 Agent

你可以配置 MCPolly，让每个 AI Agent 会话都自动注册自身并发布状态更新，无需手动提示。

工作原理

将提供的 Cursor 规则文件复制到任意项目中：

mkdir -p .cursor/rules
cp /path/to/mcpolly/.cursor/rules/mcpolly.mdc .cursor/rules/

此规则文件会指示该项目中的每个 Cursor Agent：

1. 注册：在每项任务开始时向 MCPolly 注册自身
2. 发布状态更新：在完成重要步骤的过程中发布状态更新
3. 报告完成情况：在任务结束时报告完成情况
4. 报告错误：出现问题时报告错误

MCP 工具

完成配置后，AI Agent 即可使用以下 MCP 工具：

Agent 管理

工具	描述
register_agent	注册新的 Agent（名称 + 描述）。返回 Agent ID。名称相同时具有幂等性。
post_status	发布状态更新（状态 + 消息）。状态：starting、running、warning、error、completed、offline、paused、errored。
post_error	报告错误并指定严重程度（error、warning、critical）。触发已配置的警报。
list_agents	列出所有已注册 Agent 及其当前状态。
get_agent_activity	获取特定 Agent 最近的活动时间线。

向量嵌入

工具	描述
update_prd_embeddings	为 PRD 文档建立索引以支持语义搜索（将 Markdown 拆分为多个块，并通过 Ollama 生成嵌入）。
update_design_embeddings	为设计文档建立索引以支持语义搜索。
search_embeddings	使用自然语言搜索已建立索引的文档。按相似度返回排序后的结果。
list_embedding_sources	列出所有已建立索引的嵌入来源及其块数和时间戳。
delete_embeddings	删除指定来源名称的所有嵌入。

Agent 生成

工具	描述
spawn_product_manager	生成产品经理 Agent，并提供嵌入中的相关上下文。
spawn_product_designer	生成产品设计师 Agent，并提供相关 PRD 和设计上下文。

环境变量

MCPolly 服务

变量	默认值	描述
PORT	3000	HTTP 服务端口
DATABASE_URL	mcpolly.db	SQLite 数据库文件路径
RUST_LOG	info	日志级别（trace、debug、info、warn、error）
OLLAMA_URL	http://localhost:11434	Ollama API 的基础 URL
OLLAMA_EMBEDDING_MODEL	all-minilm	嵌入模型名称

MCP 二进制文件（mcpolly_mcp）

变量	必需	描述
MCPOLLY_URL	是	MCPolly HTTP 服务的基础 URL
MCPOLLY_API_KEY	是	用于身份验证的 API 密钥

API 端点

JSON API（/api/v1/...，需要 API 密钥请求头）

方法	路径	描述
GET	/api/v1/agents	列出所有 Agent
POST	/api/v1/agents/register	注册 Agent
GET	/api/v1/agents/:id	获取 Agent 详情
GET	/api/v1/agents/:id/activity	获取 Agent 活动
GET	/api/v1/agents/:id/errors	获取 Agent 错误
POST	/api/v1/status	发布状态更新
POST	/api/v1/errors	发布错误
GET/POST	/api/v1/alerts	列出/创建警报规则
GET	/api/v1/alerts/history	警报通知历史记录
DELETE	/api/v1/alerts/:id	删除警报规则
GET/POST	/api/v1/keys	列出/创建 API 密钥
DELETE	/api/v1/keys/:id	撤销 API 密钥
POST	/api/v1/embeddings/index	为文档建立索引
GET	/api/v1/embeddings/search	语义搜索
GET	/api/v1/embeddings/sources	列出嵌入来源
DELETE	/api/v1/embeddings/sources/:name	删除嵌入
GET	/api/v1/server/info	服务版本、运行时间、数据库大小

警报条件

可为任何 Agent 状态变化配置警报规则：

条件	触发时机
any_status	Agent 的任何状态更新
agent_completed	Agent 发布 completed 状态
agent_running	Agent 发布 running 状态
agent_starting	Agent 发布 starting 状态
agent_error	Agent 发布 error 或 errored 状态
agent_warning	Agent 发布 warning 状态
agent_paused	Agent 发布 paused 状态
agent_stopped	Agent 发布 stopped 状态
agent_stopping	Agent 发布 stopping 状态
agent_offline	Agent 不再发送消息（后台检查器）

支持的渠道：Discord、Slack 和通用 webhook（纯 JSON POST）。

MCP 端点

路径	描述
/mcp	MCP Streamable HTTP 端点（JSON-RPC + SSE）

开发

本地开发服务器

PORT=3000 RUST_LOG=mcpolly=info cargo run --bin mcpolly

构建 MCP 二进制文件

cargo build --bin mcpolly_mcp

发布构建

cargo build --release

升级

使用升级脚本安全地更新正在运行的 MCPolly 实例：

./upgrade.sh

脚本将：

1. 从 GitHub Releases 下载并验证新的二进制文件
2. 备份 SQLite 数据库（保留最近 5 个备份）
3. 平稳停止服务
4. 替换二进制文件
5. 重启并进行运行状况检查——如果新版本无法启动，则自动回滚

选项：

# Upgrade to a specific version
MCPOLLY_VERSION=v0.3.0 ./upgrade.sh

# Dry run (see what would happen without changing anything)
MCPOLLY_DRY_RUN=1 ./upgrade.sh

# Skip database backup
MCPOLLY_SKIP_BACKUP=1 ./upgrade.sh

升级脚本会自动检测安装位置、systemd 服务类型（用户级或系统级）和数据库路径。

部署

MCPolly 专为在最低配置的硬件上运行而设计。每月 4 美元的 VPS 即可满足需求。

先决条件

• 已安装并运行 Ollama，且已拉取 all-minilm 模型（用于嵌入）
• 端口 3000（或配置的端口）可用

systemd 服务

创建 /etc/systemd/system/mcpolly.service：

[Unit]
Description=MCPolly Agent Observability Server
After=network.target

[Service]
Type=simple
User=mcpolly
WorkingDirectory=/opt/mcpolly
ExecStart=/opt/mcpolly/mcpolly
Environment=PORT=3000
Environment=RUST_LOG=mcpolly=info
Environment=DATABASE_URL=/opt/mcpolly/data/mcpolly.db
Environment=OLLAMA_URL=http://localhost:11434
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now mcpolly

反向代理（Caddy）

mcpolly.example.com {
    reverse_proxy localhost:3000
}

Caddy 会通过 Let's Encrypt 自动处理 TLS。

许可证

MIT