pi-profile-switch 0.10.0 → 0.12.0

package/README.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [中文](README.zh-CN.md)
 
-Named profiles for [Pi](https://github.com/badlogic/pi-mono). A profile is a named set of resources you define: skills, extensions, MCP servers, tools (including tools exposed by MCP servers and extensions), model defaults, and extra system-prompt instructions. Switch profiles inside a running Pi session — no restart.
+Named profiles for [Pi](https://github.com/badlogic/pi-mono). A profile is a named set of resources you define: skills, extensions, MCP servers, tools, per-server MCP tool selections (`mcp_tools`), model defaults, and extra system-prompt instructions. Switch profiles inside a running Pi session — no restart.
 
 ## Install
 
@@ -51,7 +51,7 @@ pi-profile-switch seeds the global `profiles/` directory with a starter **`ask`*
 }
 ```
 
-One profile can use every field at once. This example `impl` profile (`impl.json`) loads the TDD skill, the mcp-scripting skill (shipped by pi-mcp-adapter), and your internal skills; wires up two MCP servers; allows the built-in tools plus both servers' MCP tools by glob; and pins the model and standing instructions:
+One profile can use every field at once. This example `impl` profile (`impl.json`) loads the TDD skill, the mcp-scripting skill (shipped by pi-mcp-adapter), and your internal skills; wires up two MCP servers; allows the built-in tools; restricts GitHub MCP tools while denying Linear tools; and pins the model and standing instructions:
 
 ```json
 {
@@ -76,11 +76,15 @@ One profile can use every field at once. This example `impl` profile (`impl.json
     "ls",
     "bash",
     "edit",
-    "write",
-    "mcp__*",
-    "github_*",
-    "linear_*"
+    "write"
   ],
+  "mcp_tools": {
+    "github": [
+      "search",
+      "get_issue"
+    ],
+    "linear": []
+  },
   "defaultProvider": "anthropic",
   "defaultModel": "claude-sonnet-4-5",
   "defaultThinkingLevel": "high",
@@ -91,20 +95,15 @@ One profile can use every field at once. This example `impl` profile (`impl.json
 How fields resolve:
 
 - `skills`, `extensions`, `mcps`, `tools` take names or globs (e.g. `"internal-*"`) referencing resources you already installed or configured — profiles never copy them. Installed packages and files in standard locations are discovered automatically; no registration needed.
-- `tools` expands against Pi's live tool registry — built-ins, extension-provided tools, and tools exposed by MCP servers. MCP tools are registered as `mcp__<server>` (proxy) and `<server>_<tool>` (direct tools, the adapter's default `toolPrefix`), so globs like `mcp__*` and `github_*` cover them.
+- `tools` expands strictly against Pi's non-MCP tool registry — built-ins and extension-provided tools, attributed by registration ownership (`sourceInfo`). Available MCP tools remain usable independently of `tools`.
+- `mcp_tools` defines per-server MCP tool filtering: keys are literal configured server names and values are literal pi-mcp-adapter selectors (original or prefixed names; either form can select the same tool). Globs are not accepted. An omitted server keeps native access to all its tools; a nonempty array allows only matched tools; an empty array (`[]`) denies all tools for that server while leaving it enabled. Unmatched selectors remain restrictive and are not diagnosed, so confirm selectors with the adapter/server before writing them.
+- A nonempty `mcp_tools` requires `pi-mcp-adapter` even when `mcps` is omitted. Existing adapter `includeTools` filters are combined only when the profile uses identical selectors or the existing filter is `"*"`; otherwise activation fails before writing runtime files. Existing `excludeTools` restrictions continue to apply.
+- **Migration note:** Former MCP references in `tools` (e.g. `mcp__*`, `<server>_*`) no longer govern MCP access. Move desired MCP tool restrictions to `mcp_tools`.
 - `mcps` references servers from your pi-mcp-adapter configuration; connection details stay in the adapter's own config.
 - Any field you omit keeps plain Pi behavior.
 
 The files in [`examples/`](examples/) mirror the two profiles above: `ask.json` is the seeded starter, `example.json` the full-field demo.
 
-### Migrating from earlier versions
-
-If you used an earlier version that stored all profiles in a single `profiles.json` (`schemaVersion: 1`), migrate manually by creating a file for each profile under the `profiles/` directory:
-
-1. Create directory `~/.pi-profile-switch/profiles/` (or `<project>/.pi/profiles/`).
-2. For each key `<name>` in your old `profiles.json`'s `profiles` object, save its value directly as `<name>.json`.
-3. Drop the outer `schemaVersion` and `profiles` envelope.
-
 ## Commands
 
 The `/profile` command family manages everything in-session:
@@ -119,13 +118,6 @@ The `/profile` command family manages everything in-session:
 
 All forms work in every mode, including non-interactive ones (`--mode rpc|print|json`); the bare selector degrades to the profile list where no interactive UI exists. The overlay is a runtime-only narrowing: it is never written to a catalog file and never survives a restart. Tools follow the same disable/enable model as the other resource kinds: a tool `disable` entry narrows the profile's resolved tool references — or the runtime's full available tool set when the profile declares no `tools`.
 
-Removed subcommands and their replacements:
-
-| Removed | Replacement |
-| --- | --- |
-| `/profile create` / `/profile edit` / `/profile delete` / `/profile duplicate` | edit the catalog JSON files directly, or configure profiles conversationally with the [`profile-config`](skills/profile-config/SKILL.md) skill |
-| the `tools` replace-form of `/profile overlay` | `/profile overlay disable tool <name-or-glob>` (disable the complement, with globs) or declare the fixed set in the profile's `tools` field |
-
 ## Docs
 
 - [Architecture](docs/architecture/overview.md) · [ADRs](docs/adr/) · [Glossary](CONTEXT.md)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [中文](README.zh-CN.md)
 
-[Pi](https://github.com/badlogic/pi-mono) 的命名 profile 扩展。一个 profile 是你自定义的命名能力组合：skills、extensions、MCP server、tools（包括 MCP server 和 extension 提供的工具）、默认模型，以及追加到系统提示词的 instructions。在同一个运行中的 Pi 会话里切换这些组合，无需重启。
+[Pi](https://github.com/badlogic/pi-mono) 的命名 profile 扩展。一个 profile 是你自定义的命名能力组合：skills、extensions、MCP server、tools、按 server 细化的 MCP 工具控制（`mcp_tools`）、默认模型，以及追加到系统提示词的 instructions。在同一个运行中的 Pi 会话里切换这些组合，无需重启。
 
 ## 安装
 
@@ -51,7 +51,7 @@ pi-profile-switch 会向全局 `profiles/` 目录播种一个初始 **`ask`** pr
 }
 ```
 
-一个 profile 可以同时使用全部字段。下面这个 `impl` profile 示例（`impl.json`）加载 TDD skill、mcp-scripting skill（pi-mcp-adapter 自带）和你的内部 skills；接入两个 MCP server；tool 白名单用 glob 覆盖内建工具和这两个 server 的 MCP 工具；并钉住模型与常驻 instructions：
+一个 profile 可以同时使用全部字段。下面这个 `impl` profile 示例（`impl.json`）加载 TDD skill、mcp-scripting skill（pi-mcp-adapter 自带）和你的内部 skills；接入两个 MCP server；允许内建工具并按 server 细化 MCP 工具；同时钉住模型与常驻 instructions：
 
 ```json
 {
@@ -76,11 +76,15 @@ pi-profile-switch 会向全局 `profiles/` 目录播种一个初始 **`ask`** pr
     "ls",
     "bash",
     "edit",
-    "write",
-    "mcp__*",
-    "github_*",
-    "linear_*"
+    "write"
   ],
+  "mcp_tools": {
+    "github": [
+      "search",
+      "get_issue"
+    ],
+    "linear": []
+  },
   "defaultProvider": "anthropic",
   "defaultModel": "claude-sonnet-4-5",
   "defaultThinkingLevel": "high",
@@ -91,20 +95,15 @@ pi-profile-switch 会向全局 `profiles/` 目录播种一个初始 **`ask`** pr
 字段解析规则：
 
 - `skills`、`extensions`、`mcps`、`tools` 接受名称或 glob（如 `"internal-*"`），引用你已安装或已配置的资源——profile 从不复制资源。已安装的包和标准目录下的文件会被自动发现，无需注册。
-- `tools` 针对 Pi 的实时工具注册表展开——内建工具、extension 提供的工具，以及 MCP server 暴露的工具。MCP 工具注册为 `mcp__<server>`（代理）和 `<server>_<tool>`（直接工具，adapter 默认 `toolPrefix`），因此 `mcp__*`、`github_*` 这类 glob 可以覆盖它们。
+- `tools` 仅针对 Pi 的非 MCP 工具展开（内建工具与 extension 提供的工具，根据注册归属 `sourceInfo` 判定）。可用的 MCP 工具独立于 `tools` 保持可用。
+- `mcp_tools` 按 server 细化 MCP 工具策略：键为字面 MCP server 名称，值为 pi-mcp-adapter 的字面 selector（原始名或带前缀名；两种写法都可能选中同一个工具）。此字段不接受 glob。省略的 server 保留其全部原生工具访问；非空数组仅允许匹配到的工具；空数组（`[]`）禁用该 server 的全部工具，同时保持 server 处于启用状态。未匹配的 selector 仍保持限制且不会收到诊断，因此编写前请通过 adapter/server 确认可用写法。
+- 非空的 `mcp_tools` 即使在省略 `mcps` 时也需要 `pi-mcp-adapter`。只有当 profile selector 与已有的 `includeTools` 字面值完全相同，或已有列表是 `"*"` 时才能安全组合；否则会在写入 runtime 文件前报错。已有的 `excludeTools` 限制仍然生效。
+- **迁移提示**：旧 profile 中写入 `tools` 的 MCP 工具名称或 glob（如 `mcp__*`、`<server>_*`）不再控制 MCP 访问；如有需要请迁移至 `mcp_tools`。
 - `mcps` 引用 pi-mcp-adapter 配置中的 server；连接细节留在 adapter 自己的配置里。
 - 未写的字段保持原生 Pi 行为。
 
 [`examples/`](examples/) 中的两个文件与上面一一对应：`ask.json` 是播种的初始 profile，`example.json` 是全字段演示。
 
-### 从旧版本迁移
-
-如果你之前使用了把全部 profile 存在单个 `profiles.json`（含 `schemaVersion: 1`）的旧版本，请手动把每个 profile 拆分到 `profiles/` 目录：
-
-1. 创建 `~/.pi-profile-switch/profiles/`（或 `<项目>/.pi/profiles/`）目录。
-2. 将旧 `profiles.json` 中 `profiles` 下的每个 `<name>` 键值提取为独立的 `<name>.json` 文件。
-3. 去除外层的 `schemaVersion` 与 `profiles` 信封，文件顶层即为裸 profile 定义。
-
 ## 命令
 
 `/profile` 命令族完成所有会话内操作：
@@ -119,13 +118,6 @@ pi-profile-switch 会向全局 `profiles/` 目录播种一个初始 **`ask`** pr
 
 所有命令在非交互模式（`--mode rpc|print|json`）下同样生效；裸 `/profile` 在无交互界面时降级为 profile 列表。overlay 是会话级收窄：绝不写入 catalog 文件，也不会跨重启保留。tool 与其他资源类别使用相同的 disable/enable 模型：tool `disable` 条目收窄 profile 解析出的工具引用；profile 未声明 `tools` 时，则收窄运行时的全部可用工具集。
 
-已移除子命令及其替代：
-
-| 移除 | 替代 |
-| --- | --- |
-| `/profile create` / `/profile edit` / `/profile delete` / `/profile duplicate` | 直接编辑 catalog JSON 文件，或通过 [`profile-config`](skills/profile-config/SKILL.md) skill 对话式配置 |
-| `/profile overlay` 的 `tools` 替换式 | `/profile overlay disable tool <name-or-glob>`（用 glob 禁用其余工具），或在 profile 的 `tools` 字段中声明固定集合 |
-
 ## 文档
 
 - [架构设计](docs/architecture/overview.md) · [ADR](docs/adr/) · [术语表](CONTEXT.md)

package/examples/example.json

@@ -20,11 +20,15 @@
     "ls",
     "bash",
     "edit",
-    "write",
-    "mcp__*",
-    "github_*",
-    "linear_*"
+    "write"
   ],
+  "mcp_tools": {
+    "github": [
+      "github_search",
+      "get_issue"
+    ],
+    "linear": []
+  },
   "defaultProvider": "anthropic",
   "defaultModel": "claude-sonnet-4-5",
   "defaultThinkingLevel": "high",

package/extensions/pi-profile/index.ts

@@ -1,16 +1,20 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
+import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
+import { isRecord } from "../../src/json-file.ts";
 import { readTrustInputs } from "../../src/launcher/initial-profile.ts";
-import { discoverAdapterServerNames } from "../../src/mcp-config.ts";
+import { loadMergedMcpServers } from "../../src/mcp-config.ts";
 import { RuntimeStateStore } from "../../src/runtime-state-store.ts";
+import { runStartupNotifications, type NoticeSurface } from "../../src/startup-notifier.ts";
 import { applyLaunchPlan, readLaunchPlanFile } from "../../src/switching/apply-plan.ts";
 import { OVERLAY_USAGE, applyOverlayMutation, clearOverlay, parseOverlayArgs } from "../../src/switching/overlay.ts";
 import { formatProfileList, listProfiles } from "../../src/switching/list-profiles.ts";
 import { buildStatusReport, formatStatusMarkdown } from "../../src/switching/status.ts";
 import { switchProfile, type SwitchDeps } from "../../src/switching/switch-profile.ts";
-import { getGlobalStateDir } from "../../src/workspace.ts";
+import { getGlobalStateDir, getProfileSwitchDir } from "../../src/workspace.ts";
 
 /**
  * pi-profile extension entry.
@@ -38,6 +42,59 @@ import { getGlobalStateDir } from "../../src/workspace.ts";
  * exclusively through `session_start` — nothing stale survives.
  */
 
+/** The bundled package's own metadata: the notifier compares the RUNNING
+ *  package version (never Pi's version or a repository checkout). */
+const OWN_PACKAGE_JSON = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+
+async function readOwnVersion(): Promise<string | undefined> {
+	try {
+		const raw: unknown = JSON.parse(await readFile(OWN_PACKAGE_JSON, "utf8"));
+		if (isRecord(raw) && typeof raw.version === "string") return raw.version;
+	} catch {
+		// Unresolvable package metadata: startup notices are skipped quietly.
+	}
+	return undefined;
+}
+
+/** Notice presentation surface: the TUI notification channel when available,
+ *  stderr in every other mode (never stdout, never the agent's prompts). */
+function createNoticeSurface(ctx: unknown): NoticeSurface {
+	const context = ctx as {
+		hasUI?: boolean;
+		mode?: string;
+		ui?: { notify?: (message: string, level: "info" | "warning" | "error") => void };
+	};
+	if (context.hasUI === true && context.mode === "tui" && typeof context.ui?.notify === "function") {
+		return { display: (message, level) => context.ui!.notify!(message, level) };
+	}
+	return {
+		display: (message) => {
+			process.stderr.write(`${message}\n`);
+		},
+	};
+}
+
+/** Startup notices run once per Pi process on the initial session_start,
+ *  without awaiting remote IO, in an isolated failure domain: a notifier
+ *  problem can never block profile activation, change Pi's exit code, or
+ *  reach the activation/switch error path. Pi re-executes this module on
+ *  reload, and reload/new/resume/fork never pass reason "startup", so no
+ *  second check is possible within one process. */
+async function startStartupNotices(surface: NoticeSurface): Promise<void> {
+	try {
+		const version = await readOwnVersion();
+		if (version === undefined) return;
+		await runStartupNotifications({
+			installedVersion: version,
+			workspaceDir: getProfileSwitchDir(),
+			offline: process.env.PI_OFFLINE === "1",
+			surface,
+		});
+	} catch {
+		// Best-effort by contract: swallow everything the notifier missed.
+	}
+}
+
 function setProfileStatus(ui: unknown, profile: string | undefined): void {
 	if (profile && typeof (ui as { setStatus?: (k: string, v: string) => void })?.setStatus === "function") {
 		(ui as { setStatus: (k: string, v: string) => void }).setStatus("profile", `profile: ${profile}`);
@@ -51,6 +108,10 @@ export default function piProfileExtension(pi: ExtensionAPI): void {
 	let pendingSummary: string | undefined;
 
 	pi.on("session_start", async (event, ctx) => {
+		// Capture the notice surface synchronously: pi may replace the session
+		// right after this handler (one-shot modes), after which a captured
+		// ctx throws on access. The surface freezes the channel now.
+		const noticeSurface = createNoticeSurface(ctx);
 		const plan = await readLaunchPlanFile(runtimeDir);
 		setProfileStatus(ctx.ui, plan?.profile);
 		const result = await applyLaunchPlan({
@@ -64,6 +125,9 @@ export default function piProfileExtension(pi: ExtensionAPI): void {
 			},
 		});
 		pendingSummary = result.summary;
+		if (event.reason === "startup") {
+			void startStartupNotices(noticeSurface);
+		}
 	});
 
 	pi.on("before_agent_start", async (event) => {
@@ -157,13 +221,19 @@ export default function piProfileExtension(pi: ExtensionAPI): void {
 					const { projectTrusted } = await readTrustInputs({ agentDir: plan.agentDir, cwd: ctx.cwd });
 					const stateDir = plan.source === "project" ? path.join(ctx.cwd, ".pi") : getGlobalStateDir(plan.agentDir);
 					const state = await new RuntimeStateStore(stateDir).read();
+					const mcpDiscovery = await loadMergedMcpServers(
+						plan.agentDir,
+						projectTrusted ? ctx.cwd : undefined,
+					);
+					const discoveredMcpServers = Object.keys(mcpDiscovery.servers).sort();
+					const disabledMcpServers = discoveredMcpServers.filter(
+						(server) => mcpDiscovery.servers[server]?.disabled === true,
+					);
 					const report = buildStatusReport({
 						plan,
 						overlay: state.overlay,
-						discoveredMcpServers: await discoverAdapterServerNames(
-							plan.agentDir,
-							projectTrusted ? ctx.cwd : undefined,
-						),
+						discoveredMcpServers,
+						disabledMcpServers,
 						commands: pi.getCommands(),
 						tools: pi.getAllTools(),
 					});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-profile-switch",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Named profiles for Pi: reference skills, extensions, MCP servers, and tools per workflow, switched without restarting. Install: npm install -g pi-profile-switch (not pi install).",
   "type": "module",
   "keywords": [
@@ -36,6 +36,7 @@
     "@earendil-works/pi-coding-agent": "*",
     "@types/node": "^24.0.0",
     "ajv": "^8.20.0",
+    "pi-mcp-adapter": "^2.38.0",
     "typescript": "^5.8.0",
     "vitest": "^3.0.0"
   },

package/schemas/profiles.schema.json

@@ -38,7 +38,21 @@
       "items": {
         "type": "string"
       },
-      "description": "Tool names or globs expanded against Pi's live registry (including extension tools)."
+      "description": "Names or globs for non-MCP Pi built-ins and non-MCP extension tools; MCP tools are selected separately with mcp_tools."
+    },
+    "mcp_tools": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[^[*?\\]{}]+$"
+      },
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "pattern": "^[^[*?\\]{}]+$"
+        }
+      },
+      "description": "Per-server tool lists mapping literal MCP server names to arrays of literal pi-mcp-adapter tool selectors. Original and prefixed names can select the same tool; globs are not allowed. An omitted server allows all its tools; an empty list denies all its tools."
     },
     "defaultProvider": {
       "type": "string",

package/skills/profile-config/SKILL.md

@@ -54,8 +54,9 @@ All fields are optional. Undeclared fields keep native Pi behavior or current st
 | `description` | `string` | Short description of the profile (e.g. `"Read-only review profile"`). |
 | `skills` | `string[]` | Skill names or globs to reference. When undeclared, available skills are not narrowed. |
 | `extensions` | `string[]` | Extension identifiers or globs to reference. When undeclared, available extensions are not narrowed. |
-| `mcps` | `string[]` | MCP server names or globs to reference. When undeclared, there is no dependency on `pi-mcp-adapter`. |
-| `tools` | `string[]` | Whitelisted tool names or globs. When undeclared, tools are not narrowed and Pi's native tool set is kept. |
+| `mcps` | `string[]` | MCP server names or globs to reference. When undeclared, `mcps` itself adds no adapter requirement; a nonempty `mcp_tools` still requires `pi-mcp-adapter`. |
+| `tools` | `string[]` | Whitelisted non-MCP tool names or globs (built-in and extension tools only). Live MCP tools remain usable independently of `tools`. When undeclared, tools are not narrowed and Pi's native tool set is kept. |
+| `mcp_tools` | `Record<string, string[]>` | Per-server MCP tool selection: literal server names mapped to literal adapter selectors (original or prefixed names; both forms may select the same tool). Globs are rejected. An omitted server allows all tools; a nonempty array allows only matches; an empty array (`[]`) denies all tools while keeping the server enabled. An empty object (`{}`) behaves like omission. Nonempty declarations require `pi-mcp-adapter`, even when `mcps` is omitted. |
 | `defaultProvider` | `string` | Default model provider (e.g. `"anthropic"`, `"openai"`). Effective only when declared together with `defaultModel`. |
 | `defaultModel` | `string` | Default model name (e.g. `"claude-sonnet-4-5"`). Effective only when declared together with `defaultProvider`. |
 | `defaultThinkingLevel` | `string` | Default thinking level; allowed values: `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`. Effective only when the model declaration holds. |
@@ -105,12 +106,20 @@ When helping the user configure a profile, check or consult the following locati
 3. **MCP servers**:
    - Discovery locations: the standard configuration locations recognized by `pi-mcp-adapter` — on the global side `~/.config/mcp/mcp.json`, `~/.agents/mcp.json`, `~/.agents/mcp/mcp.json`, `<agentDir>/mcp.json`; trusted projects additionally have `<projectDir>/.mcp.json` and `<projectDir>/.pi/mcp.json`.
    - Reference identity: the server key names under the `mcpServers` object in those configuration files.
-   - A profile declaring `mcps` must also ensure the `pi-mcp-adapter` extension is available.
+   - A profile declaring nonempty `mcps` or nonempty `mcp_tools` must ensure the `pi-mcp-adapter` extension is available; omitting `mcps` does not remove the requirement for nonempty `mcp_tools`.
 4. **Tools**:
-   - Reference identity: tool names in Pi's live tool registry.
-   - Includes built-in tools (`read`, `write`, `edit`, `bash`, etc.), extension-contributed tools, and tools exposed by MCP servers (the proxy tool `mcp__<server>` and direct tools `<server>_<tool>`).
-   - Globs supported (e.g. `"mcp__*"`, `"github_*"`).
-5. **Narrowing boundary of project-level resources (important)**:
+   - Reference identity: non-MCP tool names in Pi's live tool registry.
+   - Includes built-in tools (`read`, `write`, `edit`, `bash`, etc.) and extension-contributed tools.
+   - MCP-owned tools are **not** controlled by `tools`; legacy references such as `"mcp__*"` or `"github_*"` in `tools` must be migrated to `mcp_tools`.
+5. **MCP Tools (`mcp_tools`)**:
+   - Reference identity: keys are literal configured MCP server names; values are literal pi-mcp-adapter selectors. Original and prefixed selectors can both match the same tool; globs are not accepted.
+   - Selectors are not checked against a live tool catalog. A selector matching no tool stays restrictive and produces no name diagnostic; verify selector forms with the adapter or MCP server before writing the profile.
+   - If the server already has nonempty `includeTools`, each requested selector must be identical to an existing literal or the existing list must include `"*"`; otherwise activation fails before runtime files are written. Existing `excludeTools` still applies.
+   - Omitting a server key preserves unrestricted access to that server's tools.
+   - An empty list (`[]`) denies all tools for that server while keeping the server enabled.
+   - A nonempty list (e.g. `["search", "get_issue"]`) allows only those tools across direct tools, gateway proxies, and scripts.
+   - Narrowing applies only to user-level MCP servers; project-level MCP servers cannot be narrowed by profiles.
+6. **Narrowing boundary of project-level resources (important)**:
    - A profile's resource selection (`skills`, `extensions`) **applies only to user-level resources** (the real agentDir and `~/.agents/skills`).
    - The visibility of project-level resources (project `.pi/skills`, project `.pi/extensions`, ancestor `.agents/skills`) is decided by Pi's project-trust determination: in a trusted project they are always visible under **any** profile; in an untrusted project they are never visible.
    - Therefore project-level resource visibility **does not narrow with profiles** — there is no need, and no guidance, to declare project-level resources in a profile.

package/src/launcher/initial-profile.ts

@@ -14,8 +14,7 @@
 import path from "node:path";
 
 import { isRecord, readJsonFile } from "../json-file.ts";
-import { discoverAdapterServerNames } from "../mcp-config.ts";
-import { isAdapterExtension, MissingMcpAdapterError } from "../mcp-config.ts";
+import { isAdapterExtension, loadMergedMcpServers, MissingMcpAdapterError } from "../mcp-config.ts";
 import { ProfileCatalog, type ResolvedProfile } from "../profile-catalog.ts";
 import { ActivationError, defaultPlan, resolveProfile, type ActivationPlan } from "../profile-resolver.ts";
 import { resolveProjectTrust } from "../project-trust.ts";
@@ -159,24 +158,38 @@ export async function resolveInitialProfile(
 		return { plan, discovery, projectDir, projectTrusted, warnings };
 	}
 
+	const mcpToolsDef = (profile.definition as { mcp_tools?: Record<string, string[]> }).mcp_tools;
+	const hasMcpTools = mcpToolsDef !== undefined && Object.keys(mcpToolsDef).length > 0;
+	const needsMcp = Boolean(
+		profile.definition.mcps?.length ||
+		hasMcpTools ||
+		(options?.overlay?.disabledMcps?.length ?? 0) > 0,
+	);
+	const mcpDiscovery = needsMcp
+		? await loadMergedMcpServers(context.agentDir, projectDir)
+		: undefined;
+
 	const discovery = await discoverLauncherResources({ ...context, projectTrusted });
 	const plan = await resolveProfile({
 		profile,
 		skills: discovery.skills,
 		extensions: discovery.extensions,
 		validateModel: (model) => checkDeclaredModel(context.agentDir, model),
-		discoveredMcpServers: profile.definition.mcps?.length
-			? await discoverAdapterServerNames(context.agentDir, projectDir)
-			: undefined,
+		discoveredMcpServers: mcpDiscovery ? Object.keys(mcpDiscovery.servers).sort() : undefined,
+		mcpDiscovery,
 		overlay: options?.overlay,
 		liveToolNames: options?.liveToolNames,
 	});
 	warnings.push(...discovery.extensions.warnings(), ...unmatchedWarnings(plan));
 	if (plan.mcps !== undefined && !plan.extensions.some(isAdapterExtension)) {
-		// Fail before spawn: without the adapter in the active extension set
-		// nobody applies the allowlist, and the declared servers would either
-		// silently do nothing or leak through unfiltered.
-		throw new MissingMcpAdapterError(plan.profile);
+		throw new MissingMcpAdapterError(plan.profile, "mcps");
+	}
+	if (
+		plan.mcpTools !== undefined &&
+		Object.keys(plan.mcpTools).length > 0 &&
+		!plan.extensions.some(isAdapterExtension)
+	) {
+		throw new MissingMcpAdapterError(plan.profile, "mcp_tools");
 	}
 	return { plan, discovery, projectDir, projectTrusted, warnings };
 }

package/src/mcp-config.ts

@@ -43,9 +43,16 @@ export interface MergedMcpResult {
 	/** Servers defined in a trusted project's own config (`.mcp.json`,
 	 *  `.pi/mcp.json`). They are not the profile's to narrow. */
 	projectServers: Set<string>;
+	/** Winning origin of each discovered server: "project" if defined or
+	 *  shadowed by project-level configuration, "user" otherwise. */
+	serverOwners: Record<string, "user" | "project">;
 	baseConfig?: Record<string, unknown>;
 }
 
+function setOwnRecordValue<T>(record: Record<string, T>, key: string, value: T): void {
+	Object.defineProperty(record, key, { value, enumerable: true, configurable: true, writable: true });
+}
+
 export interface McpConfigSource {
 	path: string;
 	isShared: boolean;
@@ -93,6 +100,7 @@ export async function loadMergedMcpServers(
 	const servers: Record<string, Record<string, unknown>> = {};
 	const sharedServers = new Set<string>();
 	const projectServers = new Set<string>();
+	const serverOwners: Record<string, "user" | "project"> = {};
 	let baseConfig: Record<string, unknown> | undefined;
 
 	for (const source of sources) {
@@ -116,21 +124,22 @@ export async function loadMergedMcpServers(
 			throw new McpConfigError(`"mcpServers" must be a JSON object: ${resolvedPath}`, resolvedPath);
 		}
 		for (const [name, def] of Object.entries(result.value.mcpServers)) {
+			// The real adapter copies server entries into an ordinary {} and
+			// cannot represent "__proto__" as a discoverable server name; align
+			// discovery so inherited prototype keys are never treated as servers.
+			if (name === "__proto__") continue;
 			if (source.isShared) {
 				sharedServers.add(name);
 			}
-			if (source.isProject === true) {
-				projectServers.add(name);
-			}
-			if (isRecord(def)) {
-				servers[name] = { ...(servers[name] ?? {}), ...def };
-			} else {
-				servers[name] = { ...(servers[name] ?? {}) };
-			}
+			if (source.isProject === true) projectServers.add(name);
+			setOwnRecordValue(serverOwners, name, source.isProject === true ? "project" : "user");
+			const previous = Object.hasOwn(servers, name) ? servers[name] : undefined;
+			const merged = isRecord(def) ? { ...(previous ?? {}), ...def } : { ...(previous ?? {}) };
+			setOwnRecordValue(servers, name, merged);
 		}
 	}
 
-	return { servers, sharedServers, projectServers, baseConfig };
+	return { servers, sharedServers, projectServers, serverOwners, baseConfig };
 }
 
 /** Server names the adapter would discover: standard global MCP configs,
@@ -146,10 +155,13 @@ export async function discoverAdapterServerNames(
 }
 
 export class MissingMcpAdapterError extends Error {
-	constructor(profile: string) {
+	constructor(profile: string, reason: "mcps" | "mcp_tools" = "mcps") {
 		super(
-			`profile "${profile}" declares MCP servers but pi-mcp-adapter is not active. ` +
-				`Select the adapter in the profile's extensions (e.g. via its npm package) or remove the "mcps" declaration.`,
+			reason === "mcp_tools"
+				? `profile "${profile}" declares MCP tools but pi-mcp-adapter is not active. ` +
+				  `Select the adapter in the profile's extensions (e.g. via its npm package) or remove the "mcp_tools" declaration.`
+				: `profile "${profile}" declares MCP servers but pi-mcp-adapter is not active. ` +
+				  `Select the adapter in the profile's extensions (e.g. via its npm package) or remove the "mcps" declaration.`,
 		);
 		this.name = "MissingMcpAdapterError";
 	}

package/src/profile-catalog.ts

@@ -44,6 +44,8 @@ export interface ProfileDefinition {
 	extensions?: string[];
 	mcps?: string[];
 	tools?: string[];
+	/** Literal adapter selectors (original or prefixed names); globs are rejected. */
+	mcp_tools?: Record<string, string[]>;
 	defaultProvider?: string;
 	defaultModel?: string;
 	defaultThinkingLevel?: string;
@@ -89,6 +91,49 @@ function readOptionalString(value: unknown, field: string, profileName: string,
 	return value;
 }
 
+function isGlobPattern(value: string): boolean {
+	return (
+		value.includes("*") ||
+		value.includes("?") ||
+		value.includes("[") ||
+		value.includes("]") ||
+		value.includes("{") ||
+		value.includes("}")
+	);
+}
+
+function readMcpTools(
+	value: unknown,
+	profileName: string,
+	filePath?: string,
+): Record<string, string[]> | undefined {
+	if (value === undefined) return undefined;
+	const prefix = filePath ? `${filePath}: ` : "";
+	if (!isRecord(value)) {
+		throw new CatalogError(`${prefix}profile "${profileName}": "mcp_tools" must be an object of string arrays`);
+	}
+	const entries: Array<[string, string[]]> = [];
+	for (const [server, tools] of Object.entries(value)) {
+		if (isGlobPattern(server)) {
+			throw new CatalogError(
+				`${prefix}profile "${profileName}": "mcp_tools" server "${server}" is a glob pattern; literal MCP server names are required`,
+			);
+		}
+		if (!Array.isArray(tools) || tools.some((entry) => typeof entry !== "string")) {
+			throw new CatalogError(`${prefix}profile "${profileName}": "mcp_tools" must be an object of string arrays`);
+		}
+		for (const tool of tools) {
+			if (isGlobPattern(tool)) {
+				throw new CatalogError(
+					`${prefix}profile "${profileName}": "mcp_tools" entry "${tool}" in server "${server}" is a glob pattern; literal adapter tool selectors are required`,
+				);
+			}
+		}
+		entries.push([server, [...tools]]);
+	}
+	return Object.fromEntries(entries);
+}
+
 /** Parses one raw profile definition; the single read-time validator so
  *  catalog files and any external writer stay loadable. */
 export function parseProfileDefinition(name: string, raw: unknown, filePath?: string): ProfileDefinition {
@@ -105,6 +150,8 @@ export function parseProfileDefinition(name: string, raw: unknown, filePath?: st
 		const entries = readStringArray(raw[field], field, name, filePath);
 		if (entries !== undefined) definition[field] = entries;
 	}
+	const mcpTools = readMcpTools(raw.mcp_tools, name, filePath);
+	if (mcpTools !== undefined) definition.mcp_tools = mcpTools;
 	const defaultProvider = readOptionalString(raw.defaultProvider, "defaultProvider", name, filePath);
 	if (defaultProvider !== undefined) definition.defaultProvider = defaultProvider;
 	const defaultModel = readOptionalString(raw.defaultModel, "defaultModel", name, filePath);