MCP and Plugins

🌐 English | 中文

MCP & Plugins

Two ways to extend what Philont can do: mount an external MCP server as native tools, or load a third-party plugin. The design principle is that new capabilities arrive through these extension points rather than by widening the trusted core — and they inherit the same permission model.

MCP bridge (agent-mcp)

The bridge mounts external MCP servers as native Philont tools — conceptually like FUSE mounting a filesystem.

Config

Two sources, in priority order (agent-mcp/src/loader.ts):

1. A config file at ~/.philont/mcp.json (or the path in PHILONT_MCP_CONFIG).
2. The convenience flag PHILONT_MCP_BROWSER=1, which auto-appends a Playwright (browser-automation) MCP server.

Each server entry (agent-mcp/src/config.ts) declares: name, transport (stdio / SSE), timeout, toolPrefix, a domain (local / network / system), and a capability (read / write / execute).

{
  "servers": [{
    "name": "browser",
    "transport": { "transport": "stdio", "command": "npx",
                   "args": ["-y", "@playwright/mcp@latest", "--headless", "--isolated"] },
    "domain": "network",
    "capability": "execute",
    "timeout": 60000
  }]
}

Why capability matters

The declared capability flows straight into the 3×4 matrix. A read+network MCP tool is auto-allowed; an execute tool (like the browser) requires explicit approval and does not auto-run. This is deliberate: marking the browser MCP execute prevents a side-effecting capability from being silently auto-approved.

Lifecycle

McpBridge (agent-mcp/src/bridge.ts) connects, calls tools/list to discover tools, wraps each (wrapper.ts — sanitises names so dots become underscores, normalises the JSON schema to a top-level object), and registers them into the tool registry. Multiple servers connect in parallel with failure isolation — one server failing to start doesn't take down the rest.

Vision

The vision capability is wired to reuse the Anthropic image block via ANTHROPIC_API_KEY (zero extra config), rather than a separate provider — so image understanding works out of the box on the default provider.

Plugins (agent-plugins)

For loading your own/third-party tool code.

Discovery

Scanned from <workDir>/.philont/plugins/ (priority 100) and ~/.philont/plugins/ (priority 50); each plugin is a subdirectory with a plugin.json manifest. Higher-priority sources override lower ones.

Manifest (plugin.json)

id (unique, used as the tool prefix), name, version, description, main (entry, default index.js), requiresEnv (env vars whitelisted into a worker sandbox), providesTools (documentation), and sandbox: direct (same process) or worker (a dedicated Worker thread, with env filtered to requiresEnv).

Loading

loadPlugins() (agent-plugins/src/loader.ts) parses the manifest, loads the entry, and calls its register(ctx). The context gives the plugin a registerTool() (auto-prefixes tool names by id) and registerHook() for lifecycle hooks (pre_tool_call, post_tool_call, on_session_start, on_session_end). Loading is error-isolated: one plugin failing doesn't affect the others.

MCP vs. plugin — which?

• MCP — you want to reuse an existing MCP server (browser, code execution, a vendor's API) without writing adapter code.
• Plugin — you want to add custom tool logic in TypeScript/JS, with the option of Worker-thread isolation and lifecycle hooks.

---

中文

English | 中文

MCP 与插件

扩展 Philont 能力的两种方式:把外部 MCP server 挂载为原生工具,或加载第三方插件。设计原则是:新能力经由这些扩展点接入,而非加宽可信内核 —— 并且它们继承同一套权限模型。

MCP 桥(agent-mcp)

该桥把外部 MCP server 挂载为原生 Philont 工具 —— 概念上像 FUSE 挂载文件系统。

配置

两个来源,按优先级(agent-mcp/src/loader.ts):

1. ~/.philont/mcp.json 配置文件(或 PHILONT_MCP_CONFIG 指定路径)。
2. 便捷开关 PHILONT_MCP_BROWSER=1,自动追加一个 Playwright(浏览器自动化)MCP server。

每个 server 条目(agent-mcp/src/config.ts)声明:name、transport(stdio / SSE)、timeout、toolPrefix、一个 domain(local / network / system)和一个 capability(read / write / execute)。

{
  "servers": [{
    "name": "browser",
    "transport": { "transport": "stdio", "command": "npx",
                   "args": ["-y", "@playwright/mcp@latest", "--headless", "--isolated"] },
    "domain": "network",
    "capability": "execute",
    "timeout": 60000
  }]
}

为何 capability 重要

声明的 capability 直接流入 3×4 矩阵。read+network 的 MCP 工具自动放行;execute 工具(如浏览器)需要显式授权,不会自动运行。这是刻意的:把浏览器 MCP 标为 execute,可防止一个有副作用的能力被悄悄自动放行。

生命周期

McpBridge(agent-mcp/src/bridge.ts)连接、调 tools/list 发现工具、逐个包装(wrapper.ts —— 清洗名称把点换成下划线、把 JSON schema 规范为顶层对象),并注册进工具注册表。多个 server 并行连接且失败隔离 —— 一个 server 启动失败不会拖垮其余。

Vision

vision 能力接线为复用 Anthropic 的 image block(经 ANTHROPIC_API_KEY,零额外配置),而非单独提供方 —— 因此在默认提供方上图像理解开箱即用。

插件(agent-plugins)

用于加载你自己/第三方的工具代码。

发现

从 <workDir>/.philont/plugins/(优先级 100)与 ~/.philont/plugins/(优先级 50)扫描;每个插件是一个带 plugin.json 清单的子目录。高优先级来源覆盖低优先级。

清单(plugin.json)

id(唯一,用作工具前缀)、name、version、description、main(入口,默认 index.js)、requiresEnv(白名单进 worker 沙箱的环境变量)、providesTools(文档)、以及 sandbox:direct(同进程)或 worker(独立 Worker 线程,环境按 requiresEnv 过滤)。

加载

loadPlugins()(agent-plugins/src/loader.ts)解析清单、加载入口、调用其 register(ctx)。上下文给插件一个 registerTool()(按 id 自动加工具名前缀)和 registerHook() 用于生命周期钩子(pre_tool_call、post_tool_call、on_session_start、on_session_end)。加载是错误隔离的:一个插件失败不影响其余。

MCP 还是插件 —— 选哪个?

• MCP —— 你想复用一个现成的 MCP server(浏览器、代码执行、某厂商 API)而不写适配代码。
• 插件 —— 你想用 TypeScript/JS 加自定义工具逻辑,可选 Worker 线程隔离与生命周期钩子。