@ian-pascoe/pi-mcp-selector 0.1.0 → 0.2.0

package/README.md

@@ -1,16 +1,16 @@
 # Pi MCP Selector
 
-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.
+Point the model at MCP servers with `&server-name` anywhere in a user message.
+Type `&` to open a completion popup listing your MCP servers. Selecting a server
+leaves shorthand in the editor. Repeat to reference several servers. `@` stays
+Pi's file completion and is not used.
 
 ```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
+Prose Span detection and the completion popup stack come from
 [`@ian-pascoe/pi-utils/prose-references`](../pi-utils/README.md#prose-references).
 
 ## Submission
@@ -18,8 +18,8 @@ Prose Span detection comes from
 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").
+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
@@ -30,55 +30,62 @@ prompt, and tool declarations unchanged. The submitted transcript stores the lin
 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
+`_` 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)
+- partial or unknown names, `foo&github`, `&&github`, and `\&github`
+- text that merely contains an ampersand: `R&D`, `Q&A`, `a && b`, `Q & A`, and
+  Rust's `&self` or `&str` when no server has that name
+- HTML entities, even when a server has the entity's name: `&`, ` `, and
+  `&github` stay literal for servers named `amp` or `nbsp` (a name directly
+  followed by `;` never converts)
+- 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
+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
+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
+  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.
+  configured `description` or the first line of the server's instructions
+  (without Markdown heading markers such as `# `), or just `MCP server`
+  without either.
 
-## Sharing `@` with file paths
+## Completion popup
 
-Pi's native `@` completion lists files. Both appear in one popup, built here
-over whatever provider is already installed:
+`&` has its own popup, like `$skill` and `#123` in the sibling selectors:
 
-- `@` 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.
+- `&` after a space or other token boundary, or alone at the start of a line, lists
+  every server by name.
+- `&git` lists servers whose name contains `git` (case-insensitive, names that
+  start with it first).
+- The popup appears only for an unquoted `&name` in prose, and only when a server
+  matches. `&` is plain text in Markdown, so a lone `&` at the start of a line
+  opens the popup too. While you type an HTML entity such as `&amp;` the popup
+  may list matching servers, and it closes at `;`; the entity never converts.
 
-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 `@`.
+Pi's editor opens the popup by itself only for `@`, `#`, and the characters the
+outermost autocomplete provider lists in `triggerCharacters`. If another extension
+wraps the provider without forwarding `triggerCharacters` (`@ff-labs/pi-fff` 0.11.0
+does not), press Tab after `&` to open it. See
+[ADR 0002](docs/adr/0002-reference-servers-with-ampersand.md) for why `&` and not `@`, `+`, or `$`.
 
 ## Integration
 
-Completion stacks over the current provider, retaining slash and file completion,
+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
@@ -87,14 +94,14 @@ too.
 
 ## Troubleshooting
 
-- **No server in the popup:** open `/mcp` and check the server is enabled and
+- **No server in the popup:** type `&` after a space, then 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.
+  `.name`, `:text`, or `;` (an HTML entity).
+- **`&` opens nothing:** press Tab after `&` (see Completion popup), and check the
+  server is in the Catalogue.
 - **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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-mcp-selector",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "description": "Native MCP Server Reference autocomplete and link conversion for Pi user input.",
   "keywords": [

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

@@ -1,14 +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.
+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.
+1. Read [`../../README.md`](../../README.md) for the reference syntax, the MCP Server Catalogue rules, and the completion popup.
 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.
+3. For a missing popup, confirm extension loading and interactive mode, then try `&` after a space, then `&gi`. If another extension wraps the autocomplete provider without forwarding `triggerCharacters` (pi-fff 0.11.0 does not), press Tab after `&` to open the popup. `@` is Pi's file completion and never lists servers.
+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`, `&name;` (an HTML entity), `R&D`, `a && b`, 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/mcp-server-references.ts

@@ -10,7 +10,7 @@ export interface McpServer {
   description?: string;
 }
 
-export const MCP_SERVER_SIGIL = "@";
+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_-]*";
@@ -21,12 +21,20 @@ 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 nameKey = (name: string): string => name.replaceAll("-", "_");
 
+/** An ATX heading line; group 1 is its text without the opening or closing `#`s. */
+const ATX_HEADING = /^#{1,6}(?:\s+(.*?))?(?:\s+#+)?$/u;
+
+/** The first non-empty line, without Markdown ATX heading markers (`# Executor`, `## Executor ##`). */
 const firstLine = (text: string | undefined): string | undefined =>
   text
     ?.split("\n")
-    .map((line) => line.trim())
+    .map((line) => {
+      const trimmed = line.trim();
+      const heading = ATX_HEADING.exec(trimmed);
+      return heading === null ? trimmed : (heading[1] ?? "").trim();
+    })
     .find((line) => line !== "");
 
 /**
@@ -75,9 +83,9 @@ export function matchMcpServers(servers: readonly McpServer[], query: string): M
 const escapeRegex = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
 /**
- * Converts `@server` shorthand for a catalogue server into `[@server](mcp://server "MCP server
+ * 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.
+ * domain, `name:text`, or `;` (an HTML entity such as `&amp;`) stay literal.
  */
 export function transformMcpServerReferences(text: string, servers: readonly McpServer[]): string {
   const catalogue = new Map(servers.map((server) => [nameKey(server.name), server]));
@@ -88,8 +96,9 @@ export function transformMcpServerReferences(text: string, servers: readonly Mcp
   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)`,
+    // A colon opens a reference only before a space (`&server: list`); `&server:resource` is a URI.
+    // A semicolon right after the name would make an HTML entity (`&amp;`), which stays literal.
+    name: `(?:${names.join("|")})(?!:\\S|;)`,
     resolve: (typed) => {
       const server = catalogue.get(nameKey(typed));
       if (server === undefined) return undefined;

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

@@ -1,14 +1,39 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { stackMcpServerAutocomplete } from "./mcp-server-autocomplete.js";
-import { getMcpServerCatalogue, transformMcpServerReferences } from "./mcp-server-references.js";
+import type { AutocompleteProvider } from "@earendil-works/pi-tui";
+import { stackProseReferenceAutocomplete } from "@ian-pascoe/pi-utils/prose-references";
+import {
+  getMcpServerCatalogue,
+  MCP_SERVER_PARTIAL_NAME,
+  MCP_SERVER_SIGIL,
+  matchMcpServers,
+  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());
 
+  const createAutocompleteProvider = (current: AutocompleteProvider): AutocompleteProvider =>
+    stackProseReferenceAutocomplete(current, {
+      sigil: MCP_SERVER_SIGIL,
+      partialName: MCP_SERVER_PARTIAL_NAME,
+      suggest: (query) =>
+        matchMcpServers(getCatalogue(), query).map((server) => {
+          const value = `${MCP_SERVER_SIGIL}${server.name}`;
+          return {
+            value,
+            label: value,
+            description:
+              server.description === undefined
+                ? "MCP server"
+                : `MCP server · ${server.description}`,
+          };
+        }),
+    });
+
   pi.on("session_start", (_event, ctx) => {
     if (ctx.mode !== "tui") return;
-    ctx.ui.addAutocompleteProvider((current) => stackMcpServerAutocomplete(current, getCatalogue));
+    ctx.ui.addAutocompleteProvider(createAutocompleteProvider);
   });
 
   pi.on("input", (event) => {

package/src/mcp-server-autocomplete.ts

@@ -1,104 +0,0 @@
-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;
-    },
-  };
-}