Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nicobailon/pi-mcp-adapter/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

This page documents the core TypeScript types used throughout the Pi MCP Adapter. These types are defined in types.ts and used across the extension.

​
Configuration Types

​
McpConfig

Root configuration object for mcp.json. 
interface McpConfig {
  mcpServers: Record<string, ServerEntry>;
  imports?: ImportKind[];
  settings?: McpSettings;
}
​
mcpServers
Record<string, ServerEntry>
required
Map of server names to their configurations. Each key is a server name, each value is a ServerEntry.
​
imports
ImportKind[]
List of external configurations to import. See ImportKind.
​
settings
McpSettings
Global settings. See McpSettings.

​
ServerEntry

Configuration for a single MCP server. 
interface ServerEntry {
  // Stdio transport
  command?: string;
  args?: string[];
  env?: Record<string, string>;
  cwd?: string;
  
  // HTTP transport
  url?: string;
  headers?: Record<string, string>;
  auth?: "oauth" | "bearer";
  bearerToken?: string;
  bearerTokenEnv?: string;
  
  // Lifecycle
  lifecycle?: "keep-alive" | "lazy" | "eager";
  idleTimeout?: number;
  
  // Features
  exposeResources?: boolean;
  directTools?: boolean | string[];
  debug?: boolean;
}
See Server Options for detailed field documentation.

​
McpSettings

Global settings for all MCP servers. 
interface McpSettings {
  toolPrefix?: "server" | "none" | "short";
  idleTimeout?: number;
  directTools?: boolean;
}
See Settings for detailed field documentation.

​
ImportKind

Supported external configuration sources. 
type ImportKind = 
  | "cursor" 
  | "claude-code" 
  | "claude-desktop" 
  | "codex" 
  | "windsurf" 
  | "vscode";

​
MCP Protocol Types

​
McpTool

Tool definition from an MCP server. 
interface McpTool {
  name: string;
  title?: string;
  description?: string;
  inputSchema?: unknown;  // JSON Schema
}
​
name
string
required
The tool’s identifier (e.g., "take_screenshot").
​
title
string
Human-readable title.
​
description
string
Tool description shown to the LLM.
​
inputSchema
unknown
JSON Schema object defining the tool’s parameters.

​
McpResource

Resource definition from an MCP server. 
interface McpResource {
  uri: string;
  name: string;
  description?: string;
  mimeType?: string;
}
​
uri
string
required
Resource URI (e.g., "file:///project/README.md").
​
name
string
required
Resource identifier.
​
description
string
Resource description.
​
mimeType
string
Content MIME type (e.g., "text/plain", "application/json").

​
McpContent

Content block returned by MCP tools. 
interface McpContent {
  type: "text" | "image" | "audio" | "resource" | "resource_link";
  text?: string;
  data?: string;
  mimeType?: string;
  resource?: {
    uri: string;
    text?: string;
    blob?: string;
  };
  uri?: string;
  name?: string;
  description?: string;
}
​
type
string
required
Content type discriminator.
​
text
string
Text content (for type: "text").
​
data
string
Base64-encoded data (for type: "image" or type: "audio").
​
mimeType
string
MIME type for binary content.
​
resource
object
Embedded resource content (for type: "resource").
​
uri
string
Resource URI (for type: "resource_link").

​
Internal Types

​
ToolMetadata

Internal representation of a tool with prefixed name and original name. 
interface ToolMetadata {
  name: string;          // Prefixed name (e.g., "chrome_devtools_take_screenshot")
  originalName: string;  // Original MCP name (e.g., "take_screenshot")
  description: string;
  resourceUri?: string;  // For resource tools
  inputSchema?: unknown; // JSON Schema
}
​
name
string
required
Tool name with server prefix applied (based on toolPrefix setting).
​
originalName
string
required
Original tool name from the MCP server (before prefixing).
​
description
string
required
Tool description.
​
resourceUri
string
If present, this tool reads from an MCP resource instead of calling a tool. The resourceUri is the URI to read.
​
inputSchema
unknown
JSON Schema for tool parameters. Stored for describe mode and error messages.

​
DirectToolSpec

Specification for a directly-registered Pi tool. 
interface DirectToolSpec {
  serverName: string;
  originalName: string;
  prefixedName: string;
  description: string;
  inputSchema?: unknown;
  resourceUri?: string;
}
​
serverName
string
required
The server this tool belongs to.
​
originalName
string
required
Original MCP tool name.
​
prefixedName
string
required
Prefixed name used for Pi tool registration.
​
description
string
required
Tool description.
​
inputSchema
unknown
JSON Schema for parameters.
​
resourceUri
string
If present, this is a resource tool.

​
Transport

Union of supported MCP transport types. 
type Transport = 
  | StdioClientTransport 
  | SSEClientTransport 
  | StreamableHTTPClientTransport;
Transports are from @modelcontextprotocol/sdk:
  • StdioClientTransport - Local process communication via stdin/stdout
  • SSEClientTransport - HTTP server-sent events
  • StreamableHTTPClientTransport - HTTP streaming (preferred for HTTP servers)

​
ContentBlock

Pi content block type (returned to the agent). 
type ContentBlock = TextContent | ImageContent;
From @mariozechner/pi-ai:
  • TextContent - { type: "text", text: string }
  • ImageContent - { type: "image", data: string, mimeType: string }

​
Utility Functions

​
getServerPrefix

Computes the prefix for a server name based on the prefix mode. 
function getServerPrefix(
  serverName: string,
  mode: "server" | "none" | "short"
): string
Examples: 
getServerPrefix("chrome-devtools", "server")  // → "chrome_devtools"
getServerPrefix("chrome-devtools", "short")   // → "chrome_devtools"
getServerPrefix("chrome-devtools-mcp", "short") // → "chrome_devtools"
getServerPrefix("chrome-devtools", "none")    // → ""

​
formatToolName

Formats a tool name with the server prefix. 
function formatToolName(
  toolName: string,
  serverName: string,
  prefix: "server" | "none" | "short"
): string
Examples: 
formatToolName("take_screenshot", "chrome-devtools", "server")
// → "chrome_devtools_take_screenshot"

formatToolName("take_screenshot", "chrome-devtools", "none")
// → "take_screenshot"

formatToolName("navigate", "chrome-devtools-mcp", "short")
// → "chrome_devtools_navigate"