extrovert

让"内向"的 AI agent 变外向：一个本地常驻的 MCP 能力代理（capability broker）。agent 只需配置一次 extrovert，之后就能自己检索官方 MCP Registry、自动安装第三方 MCP 服务器、做冒烟验证，并把新工具热挂载进来——全程不需要用户介入，也不需要重启 agent。

它的触发点不是用户口令，而是任务规划阶段：agent 拆解任务时，对每个属于通用外部能力的子任务（图/视频/音频生成、文档解析、爬取、SaaS API 等），先走 extrovert 流程找现成能力，而不是从零手搓。

Make your "introverted" AI agent extroverted: a local MCP capability broker. Configure extrovert once, and the agent can search the official MCP Registry, install third-party MCP servers, smoke-verify them, and hot-mount their tools at runtime — no user intervention, no restarts. The trigger is the agent's task-planning phase, not a user password: while decomposing a task, the agent checks each generic-capability subtask against extrovert before building anything from scratch.

30 秒安装 / 30-second install

不用手动编辑任何配置：把 INSTALL.md 里的魔法提示词粘贴给任意 agent，它会自己执行 pip install → extrovert doctor → extrovert install 完成注册，然后让你重启会话。

No manual config editing: paste the magic prompt from INSTALL.md into any agent; it runs pip install → extrovert doctor → extrovert install itself, then asks you to restart the session.

Related MCP server: MCPfinder

架构 / Architecture

┌──────────────┐   MCP (stdio, 一次配置)   ┌───────────────────────────────┐
│  AI agent    │ ◄──────────────────────► │           extrovert           │
│ Claude Code  │                          │  capability_search / add /    │
│ Kimi Code …  │   ◄── notifications/     │  verify / list / remove       │
│              │      tools/list_changed  │                               │
└──────────────┘                          │  mounts:                      │
                                          │   fs__*  ──► npx -y <pkg>     │
                                          │   db__*  ──► uvx <pkg>        │
                                          │   echo__* ─► python3 s.py     │
                                          └───────┬───────────┬───────────┘
                                          HTTPS   ▼           ▼ 子进程 (stdio)
                              registry.modelcontextprotocol.io

工作原理 / How it works

1. 发现 Discover — capability_search(query) 检索官方 MCP Registry，返回结构化候选（名称、描述、版本、npm/pypi 包名）。/ searches the official MCP Registry and returns structured candidates.

2. 安装 Install — capability_add(identifier) 把注册表条目解析成启动命令（npm → npx -y <pkg>；pypi → uvx <pkg> 或 python3 -m <pkg>），以 scrub 过的环境变量启动子进程并完成 MCP 握手。也接受显式本地命令，如 python3 /path/to/server.py。/ resolves the entry into a launch command, spawns it with a scrubbed environment, and completes the MCP handshake. Explicit local commands are also accepted.

3. 验证 Verify — capability_verify(alias) 冒烟检查：ping + list_tools，若存在无参数的 echo/ping/hello/version 类安全工具则真实调用一次，证据写入信任库 ~/.extrovert/trust.json。/ smoke check: ping + list_tools + one safe zero-argument probe call; evidence goes to the trust store.

4. 挂载 Mount — 下游工具以 <alias>__<tool> 立即出现在工具列表中，并通过 notifications/tools/list_changed 通知客户端刷新；验证过的服务器会在下次启动时自动重挂载（~/.extrovert/config.json）。/ downstream tools appear immediately as <alias>__<tool>, the client is told via notifications/tools/list_changed, and verified servers auto-remount on next start.

规划期自检 / Planning-phase check

extrovert 的触发点是任务规划阶段，不是用户口令。agent 拆解任务后、动手之前：

任务 → 拆解 → 每个子任务问"这是通用能力吗" → capability_consider → 有则装验用，无则自己捏

capability_consider(task) 返回带本机验证状态的候选与建议措辞，结果有 10 分钟内存缓存；注册表不可达时优雅降级为"先自行实现"。自行实现的子任务应在总结里注明"已确认无现成能力"。这一行为由 skills/extrovert/SKILL.md（技能包）和 extrovert hint（hook 注入的一句话提醒）双重兜底。

安装 / Install

pip install extrovert-mcp        # 发布后 / once published
# 或从源码 / or from source:
pip install -e .

要求 Python ≥ 3.10。注册表里的 npm 服务器需要 npx；pypi 服务器优先用 uvx（未安装则回退 python3 -m，需该包已安装）。

CLI 子命令 / CLI subcommands

裸 extrovert（或 extrovert serve）运行 MCP 代理服务器；其余子命令用于安装与诊断：

• extrovert doctor — 自检：Python/mcp SDK 版本、npx/uvx 可用性、注册表连通性（3s 超时）、extrovert hint 可执行性、~/.extrovert 可写性；关键项失败时退出码为 1

• extrovert install — 检测本机客户端并注册 extrovert：有 claude CLI 就走 claude mcp add -s user extrovert -- <启动命令> 并用 claude mcp list 验证；Kimi Code 优先写 ~/.kimi-code/mcp.json 的 mcpServers，或向已含 [mcp_servers] 段的 config.toml 追加条目（均先备份为 .bak）；格式不确定时不猜，打印片段让你手动粘贴。--dry-run 只看计划，--yes 跳过确认；--with-hook 额外把 extrovert hint 写进 Claude Code 的 ~/.claude/settings.json（UserPromptSubmit hook，备份且幂等）

• extrovert uninstall — 反向移除（--with-hook 时一并摘除 hook）

• extrovert hint — 打印一行规划期提醒，供客户端 hook 注入到用户消息上下文

Skill 触发包 / Skill pack

仓库自带 skills/extrovert/SKILL.md，让 agent 在规划阶段自发对每个子任务做通用能力自检（capability_consider），并可靠地走 add → verify → 调用流程（含失败必须如实报告、反模式清单等约束）。安装方式：软链或复制到 agent 的技能目录，例如 ln -s $PWD/skills/extrovert ~/.agents/skills/extrovert。

The repo ships skills/extrovert/SKILL.md so agents run a planning-phase capability check on every subtask and route through extrovert. Symlink or copy it into your agent's skills directory, e.g. ~/.agents/skills/extrovert.

客户端配置 / Client configuration

Claude Code

claude mcp add -s user extrovert -- extrovert

或写入 ~/.claude.json / 项目 .mcp.json：

{
  "mcpServers": {
    "extrovert": { "command": "extrovert" }
  }
}

Kimi Code

写入 ~/.kimi-code/mcp.json（或 $KIMI_CODE_HOME/mcp.json）：

{
  "mcpServers": {
    "extrovert": { "command": "extrovert" }
  }
}

之后 agent 自己完成其余事情："帮我找一个能操作文件系统的 MCP 服务器并装上" → capability_search → capability_add → capability_verify → 直接用 fs__* 工具。

工具 / Tools

数据文件 / State files

均在 ~/.extrovert/（可用环境变量 EXTROVERT_HOME 覆盖）：

• config.json — 已挂载服务器列表与 env_passthrough 白名单追加项

• trust.json — 验证记录（时间戳、通过与否、证据摘要）

• broker.log — JSON Lines 审计日志（安装/验证/移除/重挂载事件）

• logs/<alias>.stderr.log — 各下游子进程的 stderr

安全说明 / Security

威胁模型（请务必读）：

• capability_add 会执行第三方代码。 安装来源仅限官方注册表条目或显式给出的本地命令，且每次安装都会写审计日志——但注册表条目不等于安全。

• 子进程默认拿不到你的环境变量。 只透传 PATH/HOME/LANG 等白名单变量（API KEY、令牌之类默认不可见）；需要时可在 config.json 的 env_passthrough 里显式追加。

• 探针验证是活性检查，不是安全审计。 它只证明服务器能应答，不证明它 benign。

• 挂载的第三方服务器拥有其进程权限内的一切能力；请只安装你信任的发布者的服务器。

Threat model (please read): capability_add executes third-party code. Sources are restricted to official-registry entries or explicit local commands, and every install is audit-logged — but registry presence is not a safety guarantee. Subprocesses only see a whitelist of environment variables (API keys and tokens are withheld by default; opt in via env_passthrough). Probe verification is a liveness check, not a security audit. Only install servers from publishers you trust.

路线图 / Roadmap

• A2A Agent Card 发现 — 除 MCP Registry 外，支持发现 A2A 协议的 Agent Card 并桥接调用。

• 技能库沉淀 — 把验证过的用法、参数模板沉淀为可复用的技能描述，减少重复探索。

• 探针验证强化 — 更丰富的只读探针、输出模式校验、挂载前的静态启发式检查。

开发 / Development

pip install -e ".[dev]"
python3 -m pytest tests/ -x -q

测试覆盖：注册表响应解析（mock 数据）、本地 echo 服务器挂载与代理调用、verify/remove/remount、断线错误路径，以及一个真实拉起 extrovert 进程的端到端集成测试（网络可用时会真实检索官方注册表）。

已知限制 / Known limitations

• 仅支持 stdio 传输；registry 中仅提供 remote（streamable-http）端点的服务器暂不支持。

• 代理工具的入参 schema 由下游 JSON Schema 综合而成：嵌套 object/array 的内部结构在代理侧不展开（下游服务器仍做权威校验）。

• 可选参数未传时不会向下游发送显式 null。

• 首个挂载超时默认 90 秒（EXTROVERT_MOUNT_TIMEOUT 可调），npm 包首次下载可能较慢。

License

MIT © yourlarok