mcpolly (Mc Polly)

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代理：

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

MCP工具

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

代理管理

矢量嵌入

特工产卵

环境变量

MCPolly服务器

MCP二进制(mcpolly_mcp)

API终点

JSON API(/api/v1/...，需要API密钥头）

警报条件

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

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

MCP端点

发展

本地开发服务器

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

构建MCP二进制文件

cargo build --bin mcpolly_mcp

发行的组建

cargo build --release

升级

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

./upgrade.sh

脚本将：

1. 从GitHub Release下载并验证新的二进制文件
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。

许可证

麻省理工学院