MCPolly

人工智能代理的原生状态、可观察性和知识平台。MCPolly是一个MCP服务器，它允许AI代理实时报告他们的进度、错误和状态，并为人类提供一个统一的网络仪表板来监控一切。代理还可以对产品文档进行索引和语义搜索，以保持一致。

使用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流式HTTP协议（基于HTTP的JSON-RPC，带有SSE流式传输）的端点。代理平台直接连接——不需要子流程二进制文件。

MCPolly服务器 --Axum HTTP服务器将代理数据存储在SQLite中，为web UI提供服务，评估警报规则，管理向量嵌入，并托管MCP端点。
奥拉玛 --本地LLM服务器用于生成具有所有MiniLM模型（384维）的向量嵌入。
mcpolly_mcp *（可选）* --一个轻量级的stdio二进制文件，适用于不支持HTTP MCP传输的平台。它将stdio桥接到MCPolly HTTP API。

特性

Agent可观察性

代理注册和状态跟踪（启动、运行、警告、错误、完成、脱机、暂停、出错、停止、已停止）
带有颜色编码条目的实时活动提要
所有代理的全局错误反馈
带有重试逻辑的Webhook警报（Discord、Slack、通用）
可配置的警报 任何状态更改 --错误、完成、运行、启动、警告、暂停、停止、脱机或包罗万象的“任何状态”规则
无声代理检测（背景检查器）

Web仪表板

带系统偏好检测的暗模式
首次运行带有自动登录和MCP配置片段的安装向导
从登录页面重置实例（撤销所有密钥，生成新密钥，重新进入安装向导）
健康条摘要（总数/运行中/出错/脱机代理计数）
用于快速过滤试剂的状态过滤丸
带有标签内容（活动、错误、信息）的代理详细信息页面
全局命令栏（Cmd+K）搜索代理、错误和知识
具有通知历史记录的警报规则管理
具有语义搜索UI的知识页面
API密钥管理
包含服务器信息和会话管理的设置页面
实时更新的10秒HTMX轮询

知识层（向量嵌入）

将PRD、设计和自定义文档索引为向量嵌入
通过MCP工具和web UI对所有索引内容进行语义搜索
Spawn产品经理和产品设计师代理与相关背景
由sqlite-vec（进程内）和Ollama（本地，不需要云API密钥）提供支持

安装

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

检测您的操作系统和架构，从GitHub Release下载正确的二进制文件：

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_164、苹果Silicon）、Windows（x86\\u64）。

选项2：从源代码构建

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

Binaries将位于：

target/release/mcpolly （HTTP服务器）
target/release/mcpolly_mcp （MCP标准电桥）

选项3：货物安装

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的情况下工作，但语义搜索和基于上下文的代理生成将不可用。

2.启动MCPolly服务器

PORT=3000 RUST_LOG=mcpolly=info ./mcpolly

SQLite数据库(mcpolly.db)在第一次运行时自动创建。网络仪表板可在 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代理平台的MCP配置中。

游标（HTTP--推荐）

编辑 ~/.cursor/mcp.json:

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

这通过HTTP直接连接到MCPolly服务器的MCP端点。没有要安装的二进制文件。

光标（stdio--可选）

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

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

克劳德代码

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列出所有已注册的代理。”

通过CLAUDE.md自动集成代理

要让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.为所有代理会话启用MCPolly（全局设置）

要使所有项目中的每个Claude Code会话自动注册并向MCPolly报告状态，请全局配置MCP服务器和代理指令。

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

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

这使得MCPolly MCP工具在每个Claude Code会话中都可用，而无需针对每个项目 .mcp.json 文件夹。

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

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

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

这可以防止Claude Code每次调用MCPolly工具时都提示请求权限。

步骤3：将代理指令添加到全局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会话中。有了这个，任何项目中的每个代理都将向MCPolly注册自己，在工作时发布状态更新，并报告完成或错误。

6.验证

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

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

自动代理集成

MCPolly可以进行配置，使每个AI代理会话自动注册并发布状态更新，无需手动提示。

运作原理

将提供的游标规则文件复制到任何项目中：

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

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

注册在每个任务开始时使用MCPolly
发布状态更新 当它通过主要步骤工作时
报告完成 任务完成时
报告错误 如果出了什么问题

MCP工具

配置后，AI代理可以使用以下MCP工具：

代理管理

工具	说明
`register_agent`	注册新代理（名称+描述）。返回代理ID。标识名称。
`post_status`	发布状态更新（状态+消息）。国家： `starting`, `running`, `warning`, `error`, `completed`, `offline`, `paused`, `errored`.
`post_error`	报告严重错误(`error`, `warning`, `critical`).触发已配置的警报。
`list_agents`	列出所有注册代理人及其当前状态。
`get_agent_activity`	获取特定代理的最近活动时间线。

矢量嵌入

工具	说明
`update_prd_embeddings`	索引PRD文档以进行语义搜索（通过Ollama进行块标记，生成嵌入）。
`update_design_embeddings`	为设计文档建立索引以进行语义搜索。
`search_embeddings`	使用自然语言搜索索引文档。返回按相似性排序的结果。
`list_embedding_sources`	列出所有带有块计数和时间戳的索引嵌入源。
`delete_embeddings`	删除给定源名称的所有嵌入。

特工产卵

工具	说明
`spawn_product_manager`	从嵌入中生成具有相关上下文的产品经理代理。
`spawn_product_designer`	根据相关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`	列出所有代理
`POST`	`/api/v1/agents/register`	注册代理
`GET`	`/api/v1/agents/:id`	获取代理详细信息
`GET`	`/api/v1/agents/:id/activity`	获取代理活动
`GET`	`/api/v1/agents/:id/errors`	获取代理错误
`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`	服务器版本、正常运行时间、数据库大小

警报条件

可以为任何代理状态更改配置警报规则：

状况	发生火灾时
`any_status`	代理的任何状态更新
`agent_completed`	代理人职位 `completed` 国家
`agent_running`	代理人职位 `running` 国家
`agent_starting`	代理人职位 `starting` 国家
`agent_error`	代理人职位 `error` 或 `errored` 国家
`agent_warning`	代理人职位 `warning` 国家
`agent_paused`	代理人职位 `paused` 国家
`agent_stopped`	代理人职位 `stopped` 国家
`agent_stopping`	代理人职位 `stopping` 国家
`agent_offline`	代理静音（背景检查器）

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

MCP端点

路径	描述
`/mcp`	MCP流式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

脚本将：

从GitHub Release下载并验证新的二进制文件
备份SQLite数据库（保留最后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。

许可证

麻省理工学院

mcpolly (Mc Polly)

快速接入

详细介绍