pi-mcp-client 0.10.0 → 0.12.0

package/README.md

@@ -3,6 +3,38 @@
 Connect Pi to MCP servers so the model can use their tools and read their
 resources. You can also browse, preview, and use server-provided prompts.
 
+> [!NOTE]
+> On Pi **0.99.1 and later**, this extension is no longer needed for basic MCP
+> use: Pi has built-in support for server tools, resources, and OAuth. Keep this
+> extension if you need OS-backed credential storage or the additional features
+> below.
+
+## ⚖️ Do you need this extension?
+
+Comparison with [Pi 1.0.0](https://github.com/earendil-works/pi/releases/tag/v1.0.0).
+
+| Feature | Built-in MCP | Pi MCP Client |
+| --- | :---: | :---: |
+| HTTP and stdio server tools | ✅ | ✅ |
+| OAuth sign-in and token refresh | ✅ | ✅ |
+| Tool namespaces and codemode calls | ✅ | ✅ |
+| Resource listing, URI templates, and reads | ✅ | ✅ |
+| [Separate OAuth accounts at the same endpoint](docs/authentication.md#use-multiple-accounts) | ✅ | ✅ |
+| [OAuth credentials in the OS credential store](docs/authentication.md#sign-in-with-oauth) | ❌ | ✅ |
+| [DPoP-bound OAuth tokens](docs/authentication.md#use-dpop-bound-tokens) | ❌ | ✅ |
+| [Server prompts with preview before use](docs/commands.md#use-server-prompts) | ❌ | ✅ |
+| [Resource argument completion](docs/tool-reference.md#complete-resource-arguments) | ❌ | ✅ |
+| [Resource change watches](docs/commands.md#watch-resource-changes) | ❌ | ✅ |
+| [Server requests for user input (elicitation)](docs/behavior.md#server-requests-for-input) | ❌ | ✅ |
+| [Configuration imports with preview](docs/commands.md#import-server-definitions) | ❌ | ✅ |
+| OAuth clients requiring a client secret | ✅ | ❌ |
+| [OAuth authorization-server metadata override](https://github.com/earendil-works/pi/blob/v1.0.0/packages/coding-agent/docs/mcp.md#authenticate-with-oauth) | ✅ | ❌ |
+| HTTP authentication with a provider's `/login` token | ✅ | ❌ |
+
+Both read the same `mcp.json` files, but OAuth credentials don't transfer between
+implementations. See
+[switching to built-in MCP](docs/behavior.md#pis-built-in-mcp-support).
+
 ## 🚀 Installation
 
 ```sh
@@ -43,9 +75,9 @@ permissions. Tool activation isn't a per-call approval prompt. See
 ## ⚙️ Configuration
 
 Store server definitions in `~/.pi/agent/mcp.json` or a trusted project's
-`.mcp.json`. Project servers load only after an explicit
-[trust decision](docs/behavior.md#project-trust). Project definitions replace
-same-named global definitions in full.
+`.pi/mcp.json`, the same files and shape as Pi's built-in MCP support. Project
+servers load only in a project that Pi [trusts](docs/behavior.md#project-trust).
+Project definitions replace same-named global definitions in full.
 You can edit these files or use `/mcp add` and `/mcp remove`. To reuse a
 Claude/Cursor JSON or Codex TOML file, run `/mcp import --scope global <path>` and
 review the selected connections before saving.
@@ -65,9 +97,17 @@ Detailed guides:
 - [Troubleshooting](docs/troubleshooting.md): Error codes, recovery, and large
   results.
 
+## 🧬 Pi Durable
+
+Custom hosts can use the experimental `pi-mcp-client/durable` adapter for
+metadata discovery, native tool activation, resource reads, and template
+completion. It shares configuration and the MCP credential store with this
+extension. See [the durable host contract](docs/durable.md) for installation,
+restart ordering, trust, and UI requirements.
+
 ## 🧰 Requirements
 
-- Pi 0.85.1 or later.
+- Pi 0.99 or later.
 - Node.js 22 or later.
 - The server executable for stdio connections.
 - An available OS credential store for OAuth. Linux requires a working Secret

package/dist/auth.d.ts

@@ -0,0 +1,72 @@
+import { type OAuthClientProvider, type DpopSession, type OAuthClientInformationContext, type OAuthClientMetadata, type OAuthDiscoveryState, type StoredOAuthClientInformation, type StoredOAuthTokens } from "@modelcontextprotocol/client";
+import { type ServerConfig, type ClientOptions } from "./config.js";
+export type OAuthOptions = Pick<ClientOptions, "oauthScopes" | "oauthCallbackPort" | "oauthDpop">;
+export declare function callbackUrl(options?: OAuthOptions): string;
+/** Validate the full handoff URL before giving the response to the SDK. */
+export declare function parseCallback(value: string, redirect: string, state: string): URLSearchParams;
+export interface OAuthIdentity {
+    server: string;
+    url: string;
+    clientId?: string;
+}
+export interface SecretStore {
+    read(): string | null;
+    write(value: string): void;
+    remove(): void;
+}
+export type CredentialStoreFactory = (identity: OAuthIdentity) => Promise<SecretStore>;
+export declare function credentialKey({ server, url, clientId }: OAuthIdentity): string;
+export declare function credentialStore(identity: OAuthIdentity): Promise<SecretStore>;
+export declare class OAuthProvider implements OAuthClientProvider {
+    private readonly store;
+    private readonly redirect?;
+    private readonly options;
+    readonly redirectUrl: string;
+    readonly clientMetadata: OAuthClientMetadata;
+    private data;
+    private snapshot;
+    private readonly epoch;
+    private readonly key;
+    private verifier?;
+    private discovery?;
+    private requestedScope?;
+    private dpopSession?;
+    private resolvedDpopSession?;
+    readonly expectedState: `${string}-${string}-${string}-${string}-${string}`;
+    private readonly clientId?;
+    constructor(identity: OAuthIdentity, store: SecretStore, redirect?: ((url: URL) => void | Promise<void>) | undefined, options?: OAuthOptions);
+    private assertCurrent;
+    private save;
+    state(): `${string}-${string}-${string}-${string}-${string}`;
+    clientInformation(ctx?: OAuthClientInformationContext): ({
+        client_id: string;
+        client_secret?: string | undefined;
+        client_id_issued_at?: number | undefined;
+        client_secret_expires_at?: number | undefined;
+    } & {
+        issuer?: string;
+    }) | undefined;
+    private lookupClientInformation;
+    saveClientInformation(info: StoredOAuthClientInformation, ctx?: OAuthClientInformationContext): void;
+    tokens(ctx?: OAuthClientInformationContext): StoredOAuthTokens | undefined;
+    saveTokens(tokens: StoredOAuthTokens): void;
+    dpop(): Promise<DpopSession | undefined>;
+    saveCodeVerifier(value: string): void;
+    codeVerifier(): string;
+    saveDiscoveryState(value: OAuthDiscoveryState): void;
+    discoveryState(): OAuthDiscoveryState | undefined;
+    redirectToAuthorization(url: URL): Promise<void>;
+    invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier" | "discovery"): void;
+}
+/** Reuse stored tokens without requiring a working keyring for public servers.
+ * Only explicit login may register a client or open a browser; background
+ * authentication may reuse or refresh existing grants through the SDK.
+ */
+export declare function connectionAuthProvider(server: string, config: ServerConfig, storeFactory?: CredentialStoreFactory): Promise<OAuthClientProvider | undefined>;
+export type Revocation = "confirmed" | "unsupported" | "unconfirmed" | "not-needed";
+/** Local removal is unconditional; revocation is bounded, issuer-bound, and best effort. */
+export declare function logout(identity: OAuthIdentity, store: SecretStore, signal?: AbortSignal): Promise<Revocation>;
+/** Explicit user action only; OAuth never opens a browser during search or execution. */
+export declare function authenticate(identity: OAuthIdentity, open: (url: string) => Promise<void>, signal?: AbortSignal, store?: SecretStore, options?: OAuthOptions & {
+    handoff?: (authorizationUrl: string, signal: AbortSignal) => Promise<string | undefined>;
+}): Promise<void>;

package/dist/authorization-review.d.ts

@@ -0,0 +1,7 @@
+import type { ExtensionContext, KeybindingsManager, Theme } from "@earendil-works/pi-coding-agent";
+import { type Component } from "@earendil-works/pi-tui";
+export declare function reviewAuthorization(ctx: ExtensionContext, server: string, requested: string[], combined: string[], grantedScopesKnown: boolean, signal: AbortSignal): Promise<boolean>;
+/** Height-bounded plain-text review. Enter advances; only explicit 'a' on the
+ * last page approves. Resize reflows the body and resets review to its start.
+ */
+export declare function authorizationReview(server: string, text: string, rows: () => number, theme: Theme, keys: KeybindingsManager, done: (approved: boolean) => void, render: () => void): Component;

package/dist/authorization.d.ts

@@ -0,0 +1,14 @@
+import { type OAuthIdentity, type OAuthOptions, type SecretStore } from "./auth.js";
+/** Server scope names are data, not instructions. Keep their size and rendering bounded. */
+export declare function parseScopes(value: string | undefined): string[] | undefined;
+export declare function authorizationOptions(identity: OAuthIdentity, store: SecretStore, options: OAuthOptions, required: string[]): {
+    options: OAuthOptions;
+    grantedScopesKnown: boolean;
+};
+/** Scope names have already been reviewed; don't repeat an unbounded list in a loader. */
+export declare function loginSummary(options: OAuthOptions, reviewed: boolean): string;
+export interface ScopeChallenge {
+    scopes: string[];
+    identity: string;
+    expires: number;
+}

package/dist/catalog.d.ts

@@ -0,0 +1,42 @@
+import type { TSchema } from "typebox";
+/** The MCP tool annotation hints Pi forwards to permission extensions. */
+export interface ToolHints {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+/** Keep only boolean hints; everything else a server sends is untrusted noise. */
+export declare function toolHints(value: unknown): ToolHints | undefined;
+export interface CatalogTool {
+    server: string;
+    name: string;
+    nativeName: string;
+    description: string;
+    inputSchema: TSchema;
+    annotations?: ToolHints;
+    identity: string;
+    schemaHash: string;
+}
+export declare function plain(value: string): string;
+export declare function line(value: string): string;
+export declare function nativeName(server: string, name: string): string;
+export declare function prepareTool(server: string, identity: string, tool: {
+    name: string;
+    description?: string;
+    inputSchema: unknown;
+    annotations?: unknown;
+}): CatalogTool;
+/** Discovery exposes names, never a callable signature. */
+export declare function summarize(tool: CatalogTool, includeIdentifier?: boolean): string;
+/** Suggestions are informational only; resolution is case-sensitive and exact. */
+export declare function resolveTools(tools: CatalogTool[], identifiers: string[]): {
+    identifier: string;
+    tool: CatalogTool | undefined;
+    suggestions: string[];
+}[];
+export declare const DEFAULT_SEARCH_LIMIT = 5;
+export declare const MAX_SEARCH_LIMIT = 50;
+export declare function tokens(text: string): string[];
+/** Exact selectors win; ordinary retrieval weights names over descriptions. */
+export declare function searchTools(tools: CatalogTool[], query: string, server?: string, limit?: number): CatalogTool[];