@ian-pascoe/pi-mcp-selector 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2026 Ian Pascoe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# Pi MCP Selector
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Point the model at MCP servers with `@server-name` anywhere in a user message.
+Type `@` to open Pi's native completion popup: your MCP servers are listed first,
+then the usual file results. Selecting a server leaves shorthand in the editor.
+Repeat to reference several servers.
+
+```bash
+pi install npm:@ian-pascoe/pi-mcp-selector
+```
+
+Requires Pi `>=1.1.0` and Node `>=22.19.0`. There are no settings or extra tools.
+Prose Span detection comes from
+[`@ian-pascoe/pi-utils/prose-references`](../pi-utils/README.md#prose-references).
+
+## Submission
+
+Typed, pasted, and selected references are equivalent. On submission:
+
+```text
+Check open issues with @github.
+→ Check open issues with [@github](mcp://github "MCP server mcp__github").
+```
+
+The link target is the configured server name and its title is the namespace
+Pi gives the server's tools. The model receives a link, not instructions or tool
+definitions, and chooses what to do with it. A reference only points: it does
+not connect, load, or expose anything, and it leaves tool exposure, the system
+prompt, and tool declarations unchanged. The submitted transcript stores the link
+rather than a separate raw shorthand message.
+
+Only exact known names in prose convert. Names are case-sensitive, and `-` and
+`_` are interchangeable, as they are in Pi's tool names (`@dev_radius` reaches
+`dev-radius`). These stay literal:
+
+- partial or unknown names, `foo@github`, `@@github`, and `\@github`
+- anything shaped like a path, address, or URI: `@github/x`, `@github.com`,
+  `@./github`, and `@github:resource` (a colon not followed by a space)
+- code, existing Markdown links, and HTML
+
+Sentence punctuation does not block a reference: `@github's`, `(@github)`,
+`@github.`, and `@github: list issues` all convert. Reuse of existing links
+is safe, so submitting converted text again changes nothing.
+
+## The MCP Server Catalogue
+
+Both the popup and conversion read Pi's current tools, fresh on every popup and
+every submission. A server is in the catalogue when it is enabled, connected, and
+has at least one tool that is not `hidden`, whether it comes from `mcp.json` or an
+extension's `registerMcpServer()`. Its exposure (`codemode`, `deferred`, `direct`)
+does not matter, and neither does whether `codemode` is active.
+
+- A disabled server re-registers its tools as hidden, so it is absent.
+- A server that is still connecting or needs sign-in has no tools yet, so it is
+  absent and its `@name` stays literal, silently. In `pi -p`, the first prompt's
+  reference usually stays literal while servers connect.
+- The popup describes each server as `MCP server · <description>`, using the
+  configured `description` or the first line of the server's instructions, or just
+  `MCP server` without either.
+
+## Sharing `@` with file paths
+
+Pi's native `@` completion lists files. Both appear in one popup, built here
+over whatever provider is already installed:
+
+- `@` alone lists every server by name, then the native files.
+- `@git` lists servers whose name contains `git` (case-insensitive, names that
+  start with it first), then the native files.
+- The popup only merges for an unquoted `@name` in prose while at least one server
+  is in the catalogue; otherwise native completion runs untouched. Servers are
+  listed only when they match the query, but a file named like a server is always
+  inserted as `@./name`, even for a fuzzy query such as `@ghb` that matches no
+  server, so selecting a file never produces a server link.
+
+If file search fails or finds nothing, the servers are still listed. Pi does not
+expand `@path` in submitted messages, so only the popup and the literal text are
+shared. See [ADR 0001](docs/adr/0001-share-at-with-file-mentions.md) for why `@`.
+
+## Integration
+
+Completion stacks over the current provider, retaining slash and file completion,
+keyboard controls, and custom editors. It runs in the interactive terminal only.
+Conversion applies to interactive, RPC, and print input, including steering and
+follow-ups, without changing attachments or message routing. Extension-generated
+input is unchanged. Direct RPC `steer` and `follow_up` commands run Pi's input hooks
+too.
+
+## Troubleshooting
+
+- **No server in the popup:** open `/mcp` and check the server is enabled and
+  connected, and has a tool that is not hidden. A server that needs sign-in or is
+  still connecting is not listed.
+- **No link:** check the exact case-sensitive name (`-` and `_` match either way),
+  and whether the reference is escaped, in code, inside a link, or followed by `/`,
+  `.name`, or `:text`.
+- **File popup missing:** a quoted `@"…` or a path such as `@src/` uses Pi's native
+  completion by design.
+- **Pi older than 1.2.0:** servers are named after their namespace (`dev_radius`),
+  not the configured name; `-` and `_` still match either way.
+- **The model did not use the server:** inspect the submitted user message first.
+  A correct link verifies conversion; using the server is the model's choice.

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@ian-pascoe/pi-mcp-selector",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "private": false,
+  "description": "Native MCP Server Reference autocomplete and link conversion for Pi user input.",
+  "keywords": [
+    "autocomplete",
+    "mcp",
+    "pi",
+    "pi-extension",
+    "pi-package"
+  ],
+  "homepage": "https://github.com/ian-pascoe/pi-extensions/tree/main/packages/pi-mcp-selector",
+  "bugs": {
+    "url": "https://github.com/ian-pascoe/pi-extensions/issues"
+  },
+  "license": "MIT",
+  "author": "Ian Pascoe <ian.g.pascoe@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ian-pascoe/pi-extensions.git",
+    "directory": "packages/pi-mcp-selector"
+  },
+  "files": [
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsrs --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@ian-pascoe/pi-utils": "^0.11.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=1.1.0",
+    "@earendil-works/pi-tui": ">=1.1.0"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/skills/pi-mcp-selector/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: pi-mcp-selector
+description: Diagnose Pi MCP Selector when `@server` autocomplete is missing or an MCP Server Reference does not convert to a link.
+license: MIT
+disable-model-invocation: true
+---
+
+# Pi MCP Selector
+
+1. Read [`../../README.md`](../../README.md) for the reference syntax, the MCP Server Catalogue rules, and how `@` is shared with file completion.
+2. For a missing server in the popup or a reference that stays literal, check the Catalogue first: `/mcp` must show the server enabled and connected with at least one tool that is not hidden. A server that is connecting, needs sign-in, or is disabled is absent by design. Finish when the server appears in the popup or this named state explains its absence.
+3. For a missing popup, confirm extension loading and interactive mode, then try bare `@` at a prose token boundary. Quoted `@"…` and path prefixes use Pi's native file completion by design.
+4. For a literal reference with the server present, compare the typed text with the submitted user message and check exact spelling and literal contexts: case, `@name/`, `@name.ext`, `@name:text`, escapes, code, and links. Finish when the link targets the configured server name or a named boundary explains the mismatch.
+5. If the link is correct but the model did not use the server, report conversion as working: the model controls tool use. Keep this extension configuration-free.

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from "./pi-mcp-selector-extension.js";

package/src/mcp-server-autocomplete.ts

@@ -0,0 +1,104 @@
+import type { AutocompleteItem, AutocompleteProvider } from "@earendil-works/pi-tui";
+import { findProseReferencePrefix } from "@ian-pascoe/pi-utils/prose-references";
+import {
+  MCP_SERVER_PARTIAL_NAME,
+  MCP_SERVER_SIGIL,
+  matchMcpServers,
+  nameKey,
+  type McpServer,
+} from "./mcp-server-references.js";
+
+const grammar = { sigil: MCP_SERVER_SIGIL, partialName: MCP_SERVER_PARTIAL_NAME };
+
+function prefixAt(lines: string[], cursorLine: number, cursorCol: number): string | null {
+  const cursorOffset = lines
+    .slice(0, cursorLine)
+    .reduce((offset, line) => offset + line.length + 1, cursorCol);
+  return findProseReferencePrefix(lines.join("\n"), cursorOffset, grammar);
+}
+
+function serverItem(server: McpServer): AutocompleteItem {
+  const value = `${MCP_SERVER_SIGIL}${server.name}`;
+  const description =
+    server.description === undefined ? "MCP server" : `MCP server · ${server.description}`;
+  return { value, label: value, description };
+}
+
+/**
+ * Pi's native `@` completion lists files, so a file named like a server would insert text that
+ * converts to a server link. Insert such a file as `@./name` instead.
+ */
+function withoutServerCollision(
+  item: AutocompleteItem,
+  servers: readonly McpServer[],
+): AutocompleteItem {
+  if (!item.value.startsWith(MCP_SERVER_SIGIL)) return item;
+  const name = item.value.slice(MCP_SERVER_SIGIL.length);
+  const key = nameKey(name);
+  if (!servers.some((server) => nameKey(server.name) === key)) return item;
+  return { ...item, value: `${MCP_SERVER_SIGIL}./${name}` };
+}
+
+/**
+ * Lists MCP servers above the files Pi's native `@` completion finds, in one popup. The
+ * returned provider engages only for an unquoted `@name` prefix in prose while the Catalogue is
+ * not empty, and delegates everything else, including applying native items, to `current`. Servers
+ * are listed only when they match; native files that collide with a server name are rewritten
+ * either way.
+ */
+export function stackMcpServerAutocomplete(
+  current: AutocompleteProvider,
+  getCatalogue: () => readonly McpServer[],
+): AutocompleteProvider {
+  // The editor hands an item back by identity, which is how a server item is told from a file.
+  const ownItems = new WeakSet<AutocompleteItem>();
+  return {
+    triggerCharacters: [...new Set([...(current.triggerCharacters ?? []), MCP_SERVER_SIGIL])],
+    async getSuggestions(lines, cursorLine, cursorCol, requestOptions) {
+      const delegate = () => current.getSuggestions(lines, cursorLine, cursorCol, requestOptions);
+      const prefix = prefixAt(lines, cursorLine, cursorCol);
+      if (prefix === null) return delegate();
+      const catalogue = getCatalogue();
+      if (catalogue.length === 0) return delegate();
+      const matches = matchMcpServers(catalogue, prefix.slice(MCP_SERVER_SIGIL.length));
+      if (requestOptions.signal.aborted) return null;
+      const items = matches.map(serverItem);
+      for (const item of items) ownItems.add(item);
+      let native: Awaited<ReturnType<AutocompleteProvider["getSuggestions"]>> = null;
+      try {
+        native = await delegate();
+      } catch {
+        // Servers still help when file search fails.
+      }
+      if (requestOptions.signal.aborted) return null;
+      if (native === null || native.items.length === 0) {
+        return items.length === 0 ? native : { prefix, items };
+      }
+      if (native.prefix !== prefix) return native;
+      // Native search is fuzzy, so a file named like a server can appear for a query that matches
+      // no server (`@ghb` finds `github`); it must still insert as `@./name`.
+      const files = native.items.map((item) => withoutServerCollision(item, catalogue));
+      if (items.length === 0 && files.every((file, index) => file === native.items[index])) {
+        return native;
+      }
+      return { prefix, items: [...items, ...files] };
+    },
+    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+      if (!ownItems.has(item)) {
+        return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+      }
+      const line = lines[cursorLine] ?? "";
+      const beforePrefix = line.slice(0, cursorCol - prefix.length);
+      const completed = [...lines];
+      completed[cursorLine] = `${beforePrefix}${item.value} ${line.slice(cursorCol)}`;
+      return {
+        lines: completed,
+        cursorLine,
+        cursorCol: beforePrefix.length + item.value.length + 1,
+      };
+    },
+    shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+      return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+    },
+  };
+}

package/src/mcp-server-references.ts

@@ -0,0 +1,99 @@
+import type { ToolInfo } from "@earendil-works/pi-coding-agent";
+import { replaceProseReferences } from "@ian-pascoe/pi-utils/prose-references";
+
+/** An MCP server the session can reach, as the model's namespace for its tools names it. */
+export interface McpServer {
+  /** The configured server name; the target of its `mcp://` links and what users type. */
+  name: string;
+  /** Pi's tool namespace for the server, such as `mcp__github`. */
+  namespace: string;
+  description?: string;
+}
+
+export const MCP_SERVER_SIGIL = "@";
+
+/** Characters a partially typed server name may hold; Pi allows letters, digits, `_`, and `-`. */
+export const MCP_SERVER_PARTIAL_NAME = "[A-Za-z0-9_-]*";
+
+const NAMESPACE_PREFIX = "mcp__";
+const SERVER_NAME = /^[A-Za-z0-9_-]+$/u;
+
+type CatalogueTool = Pick<ToolInfo, "exposure" | "namespace">;
+
+/** Hyphen and underscore name the same server, since Pi's namespace folds them together. */
+export const nameKey = (name: string): string => name.replaceAll("-", "_");
+
+const firstLine = (text: string | undefined): string | undefined =>
+  text
+    ?.split("\n")
+    .map((line) => line.trim())
+    .find((line) => line !== "");
+
+/**
+ * The MCP Server Catalogue: each `mcp__` namespace that has a tool Pi has not hidden, so disabled
+ * servers and servers without tools yet (connecting, or needing sign-in) are absent. A server is
+ * named by its first namespace alias, which Pi sets to the configured name, else by the
+ * namespace without its prefix. Sorted by name.
+ */
+export function getMcpServerCatalogue(tools: readonly CatalogueTool[]): McpServer[] {
+  const servers = new Map<string, McpServer>();
+  for (const { exposure, namespace } of tools) {
+    if (namespace === undefined || exposure === "hidden" || servers.has(namespace.name)) continue;
+    if (!namespace.name.startsWith(NAMESPACE_PREFIX)) continue;
+    const alias = namespace.aliases?.[0];
+    const name =
+      alias !== undefined && SERVER_NAME.test(alias)
+        ? alias
+        : namespace.name.slice(NAMESPACE_PREFIX.length);
+    if (!SERVER_NAME.test(name)) continue;
+    const server: McpServer = { name, namespace: namespace.name };
+    const description = firstLine(namespace.description) ?? firstLine(namespace.instructions);
+    if (description !== undefined) server.description = description;
+    servers.set(namespace.name, server);
+  }
+  return [...servers.values()].sort((left, right) => left.name.localeCompare(right.name, "en"));
+}
+
+/**
+ * The servers whose name contains `query` (case-insensitive), names that start with it first, each
+ * group sorted by name. An empty query lists every server.
+ */
+export function matchMcpServers(servers: readonly McpServer[], query: string): McpServer[] {
+  const wanted = nameKey(query).toLowerCase();
+  const matches = servers
+    .map((server) => ({ server, index: nameKey(server.name).toLowerCase().indexOf(wanted) }))
+    .filter(({ index }) => index >= 0);
+  const rank = ({ index }: { index: number }): number => (index === 0 ? 0 : 1);
+  return matches
+    .sort(
+      (left, right) =>
+        rank(left) - rank(right) || left.server.name.localeCompare(right.server.name, "en"),
+    )
+    .map(({ server }) => server);
+}
+
+const escapeRegex = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * Converts `@server` shorthand for a catalogue server into `[@server](mcp://server "MCP server
+ * mcp__server")` inside Prose Spans. Unknown names, code, links, and names that run into a path,
+ * domain, or `name:text` stay literal.
+ */
+export function transformMcpServerReferences(text: string, servers: readonly McpServer[]): string {
+  const catalogue = new Map(servers.map((server) => [nameKey(server.name), server]));
+  const names = [...catalogue.keys()]
+    .sort((left, right) => right.length - left.length)
+    // The catalogue key folds `-` into `_`; a typed name may use either.
+    .map((key) => escapeRegex(key).replaceAll("_", "[-_]"));
+  if (names.length === 0) return text;
+  return replaceProseReferences(text, {
+    sigil: MCP_SERVER_SIGIL,
+    // A colon opens a reference only before a space (`@server: list`); `@server:resource` is a URI.
+    name: `(?:${names.join("|")})(?!:\\S)`,
+    resolve: (typed) => {
+      const server = catalogue.get(nameKey(typed));
+      if (server === undefined) return undefined;
+      return `[${MCP_SERVER_SIGIL}${typed}](mcp://${server.name} "MCP server ${server.namespace}")`;
+    },
+  });
+}

package/src/pi-mcp-selector-extension.ts

@@ -0,0 +1,22 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { stackMcpServerAutocomplete } from "./mcp-server-autocomplete.js";
+import { getMcpServerCatalogue, transformMcpServerReferences } from "./mcp-server-references.js";
+
+export default function mcpSelectorExtension(pi: ExtensionAPI): void {
+  // Read fresh on every use: servers connect, disconnect, and change exposure during a session.
+  const getCatalogue = () => getMcpServerCatalogue(pi.getAllTools());
+
+  pi.on("session_start", (_event, ctx) => {
+    if (ctx.mode !== "tui") return;
+    ctx.ui.addAutocompleteProvider((current) => stackMcpServerAutocomplete(current, getCatalogue));
+  });
+
+  pi.on("input", (event) => {
+    if (event.source === "extension") return { action: "continue" };
+    const text = transformMcpServerReferences(event.text, getCatalogue());
+    if (text === event.text) return { action: "continue" };
+    return event.images === undefined
+      ? { action: "transform", text }
+      : { action: "transform", text, images: event.images };
+  });
+}