### Test Fixture Setup (TypeScript)

Source: https://github.com/steipete/mcporter/blob/main/docs/import.md

This example demonstrates how to set up test fixtures for mcporter imports. It involves copying fixtures into a fake home directory and asserting the merged server order, a pattern recommended for adding new import kinds.

```typescript
import path from 'path';
import fs from 'fs-extra';

// ... inside a test function ...
const fakeHomeDir = path.join(__dirname, '..', '..', 'fake-home');
await fs.copy(path.join(__dirname, '..', 'fixtures', 'imports'), fakeHomeDir);
process.env.HOME = fakeHomeDir;

// Assertions about mcporter's behavior with these fixtures
// ...

// Clean up
delete process.env.HOME;
await fs.remove(fakeHomeDir);
```

--------------------------------

### Managing MCPorter Configuration with CLI (Bash)

Source: https://context7.com/steipete/mcporter/llms.txt

Provides examples of using the `mcporter config` CLI commands to manage MCPorter configuration files. It covers listing configurations, getting details, adding new servers with various options, removing servers, importing from editors, validating the config, and logging out of OAuth.

```bash
# List local config entries
npx mcporter config list

# List imported entries from editors
npx mcporter config list --source import

# Get details for a specific server
npx mcporter config get linear

# Add a new HTTP server
npx mcporter config add sentry https://mcp.sentry.dev/mcp

# Add with custom options
npx mcporter config add local-api https://localhost:3000/mcp \
  --allow-http \
  --header "Authorization: Bearer $API_KEY" \
  --description "Local API server"

# Add to home config instead of project
npx mcporter config add global-tool https://api.example.com/mcp --scope home

# Remove a server
npx mcporter config remove sentry

# Import entries from Cursor
npx mcporter config import cursor --copy

# Validate configuration
npx mcporter config doctor

# Clear OAuth credentials
npx mcporter config logout linear
```

--------------------------------

### mcporter Configuration File Example (JSONC)

Source: https://github.com/steipete/mcporter/blob/main/README.md

An example of a mcporter.jsonc configuration file, demonstrating how to define MCP servers, their descriptions, base URLs, headers, and import sources. Supports JSONC features like comments and trailing commas.

```jsonc
{
	"mcpServers": {
		"context7": {
			"description": "Context7 docs MCP",
			"baseUrl": "https://mcp.context7.com/mcp",
			"headers": {
				"Authorization": "$env:CONTEXT7_API_KEY"
			}
		},
		"chrome-devtools": {
			"command": "npx",
			"args": ["-y", "chrome-devtools-mcp@latest"],
			"env": { "npm_config_loglevel": "error" }
		}
	},
	"imports": ["cursor", "claude-code", "claude-desktop", "codex", "windsurf", "opencode", "vscode"]
}
```

--------------------------------

### Install MCPorter

Source: https://github.com/steipete/mcporter/blob/main/README.md

Provides instructions for installing MCPorter using npx, pnpm, or Homebrew. It includes commands for instant execution and adding the package to a project.

```bash
npx mcporter list

```

```bash
pnpm add mcporter

```

```bash
brew tap steipete/tap
brew install steipete/tap/mcporter

```

--------------------------------

### Homebrew Installation and Testing

Source: https://github.com/steipete/mcporter/blob/main/docs/RELEASE.md

Commands to manage the mcporter installation via Homebrew. This includes uninstalling previous versions, installing the new version from the tap, running basic tests, and uninstalling again to ensure a clean state before the final npm global install.

```bash
brew uninstall mcporter || true
npm uninstall -g mcporter || true
brew install steipete/tap/mcporter
# If you still have /opt/homebrew/bin/mcporter from npm, fix conflicts with:
# brew link --overwrite mcporter
mcporter list --help | head -n 5
brew uninstall mcporter
```

--------------------------------

### Generate Typed Clients

Source: https://github.com/steipete/mcporter/blob/main/README.md

Instructions and examples for generating strongly typed clients without shipping a full CLI.

```APIDOC
## Generate Typed Clients

Use `mcporter emit-ts` when you want strongly typed tooling without shipping a full CLI. It reuses the same signatures/doc blocks as `mcporter list`, so the generated headers stay in sync with what the CLI shows.

```bash
# Types-only interface (Promise signatures)
npx mcporter emit-ts linear --out types/linear-tools.d.ts

# Client wrapper (creates a reusable proxy factory alongside the .d.ts)
npx mcporter emit-ts linear --mode client --out clients/linear.ts
```

- `--mode types` (default) produces a `.d.ts` interface you can import anywhere.
- `--mode client` emits the `.d.ts` **and** a `.ts` helper that wraps `createRuntime` / `createServerProxy` for you.
- Add `--include-optional` whenever you want every optional field spelled out (mirrors `mcporter list --all-parameters`).
- Add `--json` to emit a structured summary (mode plus output paths) instead of plain-text logs when scripting `emit-ts`.
- The `<server>` argument also understands HTTP URLs and selectors with `.tool` suffixes or missing protocols—mirroring the main CLI.

See [docs/emit-ts.md](docs/emit-ts.md) for the full flag reference plus inline snapshots of the emitted files.
```

--------------------------------

### Get Server Help with pnpm mcp call

Source: https://github.com/steipete/mcporter/blob/main/docs/shortcuts.md

This shortcut allows agents to get help for a specific MCP server. It aliases `pnpm mcporter:call <server>.help`. If a 'help' tool exists, it streams its content. Otherwise, it falls back to `mcporter list <server>` to provide server summaries and tool signatures. Supports `--output json` for machine-readable output.

```bash
pnpm mcp call <server>.help
pnpm mcp call <server>.help --output json
```

--------------------------------

### Example Proxy Tool Invocation

Source: https://github.com/steipete/mcporter/blob/main/docs/spec.md

Demonstrates the intended ergonomic method-style invocation for MCP tools via the McPorter proxy.

```typescript
const result = await context.getLibraryDocs("react");
console.log(result.markdown());
```

--------------------------------

### mcporter Configuration Patch Example

Source: https://github.com/steipete/mcporter/blob/main/docs/known-issues.md

This example illustrates a potential future improvement for mcporter: patching configuration to override or provide missing output schemas for specific tools. This would help features relying on schemas, like TypeScript signatures or generated CLIs, to function correctly even when the server provides incomplete schema information.

```bash
mcporter config patch --tool <tool-name> --schema-override <path-to-schema.json>
```

--------------------------------

### TypeScript Project Setup and Execution

Source: https://github.com/steipete/mcporter/blob/main/AGENTS.md

This snippet details the recommended practices for TypeScript projects within the workspace. It highlights using the declared package manager (e.g., `pnpm`, `bun`) and running commands through the provided wrapper. It also stresses the importance of running doc-index scripts, keeping watchers active, treating lint/typecheck/test commands as mandatory gates, and maintaining strict typing.

```typescript
// Use the package manager declared by the workspace (often `pnpm` or `bun`)
// Run every command through the same wrapper humans use; do not substitute `npm`/`yarn` or bypass the runner.

// Start each session by running the repo’s doc-index script (commonly a `docs:list` helper)
// Keep required watchers (`lint:watch`, `test:watch`, dev servers) running inside tmux unless told otherwise.

// Treat `lint`, `typecheck`, and `test` commands (e.g., `pnpm run check`, `bun run typecheck`) as mandatory gates before handing off work
// Surface any failures with their exact command output.

// Maintain strict typing—avoid `any`, prefer utility helpers already provided by the repo
// Keep shared guardrail scripts (runner, committer, browser helpers) consistent by syncing back to `agent-scripts` when they change.

// When editing UI code, follow the established component patterns (Tailwind via helper utilities, TanStack Query for data flow, etc.)
// Keep files under the preferred size limit by extracting helpers proactively.
```

--------------------------------

### Sync project to ext4 filesystem

Source: https://github.com/steipete/mcporter/blob/main/docs/windows.md

Synchronizes the project directory from the Windows NTFS drive to the WSL ext4 home directory to avoid futime errors during dependency installation.

```bash
rsync -a --delete --exclude node_modules /mnt/c/Projects/mcporter/ ~/mcporter-wsl/
```

--------------------------------

### Configure Ad-hoc Server Transports

Source: https://github.com/steipete/mcporter/blob/main/docs/adhoc.md

Examples of using command-line flags to specify HTTP or Stdio transports for MCP servers.

```bash
# Using HTTP transport with an explicit URL and optional name
mcporter list --http-url https://mcp.linear.app/mcp --name linear

# Using Stdio transport with a command string
mcporter call --stdio "bun run ./server.ts" --name local-tools
```

--------------------------------

### Start mcporter List Session in tmux (Bash)

Source: https://github.com/steipete/mcporter/blob/main/README.md

Command to start a new tmux session to run `pnpm mcporter:list`. This is useful for keeping long-running CLI sessions visible and manageable in the background.

```bash
tmux new-session -- pnpm mcporter:list
```

--------------------------------

### Execute MCP Tool Calls

Source: https://github.com/steipete/mcporter/blob/main/README.md

Examples of invoking specific tools on MCP servers using the call command with required parameters and environment variables.

```bash
npx mcporter call context7.resolve-library-id libraryName=react
npx mcporter call context7.get-library-docs context7CompatibleLibraryID=/websites/react_dev topic=hooks
LINEAR_API_KEY=sk_linear_example npx mcporter call linear.search_documentation query="automations"
```

--------------------------------

### mcporter Configuration Schema Example

Source: https://github.com/steipete/mcporter/blob/main/docs/config.md

A sample JSONC configuration file for mcporter. It defines MCP servers with environment variable interpolation and specifies external import sources.

```jsonc
{
  "$schema": "https://raw.githubusercontent.com/steipete/mcporter/main/mcporter.schema.json",
  "mcpServers": {
    "linear": {
      "description": "Linear issues",
      "baseUrl": "https://mcp.linear.app/mcp",
      "headers": { "Authorization": "Bearer ${LINEAR_API_KEY}" }
    }
  },
  "imports": ["cursor", "claude-code", "claude-desktop", "codex", "windsurf", "opencode", "vscode"]
}
```

--------------------------------

### Generate Standalone CLI

Source: https://github.com/steipete/mcporter/blob/main/README.md

Instructions and examples for generating a standalone CLI artifact from a server definition.

```APIDOC
## Generate a Standalone CLI

Turn any server definition into a shareable CLI artifact:

```bash
npx mcporter generate-cli \
  --command https://mcp.context7.com/mcp

# Outputs:
#   context7.ts        (TypeScript template with embedded schemas)
#   context7.js        (bundled CLI via Rolldown or Bun, depending on runtime)
```

> Convert the chrome-devtools MCP to a CLI via this one weird trick:
> 
> `npx mcporter generate-cli --command "npx -y chrome-devtools-mcp@latest"`

Tip: you can drop `--command` when the inline command is the first positional argument (e.g., `npx mcporter generate-cli "npx -y chrome-devtools-mcp@latest"`).

- `--name` overrides the inferred CLI name.
- Add `--description "..."` if you want a custom summary in the generated help output (otherwise mcporter asks the MCP server for its own description/title during generation).
- Generated CLIs inherit the same color-aware help layout as `mcporter` itself: invoking the binary with no arguments shows the embedded tool list + quick start, and each `--help` page uses bold titles + dimmed descriptions when stdout is a TTY.
- Add `--bundle [path]` to emit a bundle alongside the template (Rolldown when targeting Node, Bun automatically when the runtime resolves to Bun; override with `--bundler rolldown|bun`).
- `--output <path>` writes the template somewhere specific.
- `--runtime bun|node` picks the runtime for generated code (Bun required for `--compile`).
- Add `--compile` to emit a Bun-compiled binary; MCPorter cleans up intermediate bundles when you omit `--bundle`.
- Use `--include-tools a,b,c` or `--exclude-tools a,b,c` to generate a CLI for a subset of tools (mutually exclusive).
- Use `--from <artifact>` (optionally `--dry-run`) to regenerate an existing CLI using its embedded metadata.
- Prefer a positional shorthand if the server already lives in your config/imports:
  `npx mcporter generate-cli linear --bundle dist/linear.js`.
- `--server`/`--command` accept HTTP URLs, optional `.tool` suffixes, and even scheme-less hosts (`shadcn.io/api/mcp.getComponents`).

Every artifact embeds regeneration metadata (generator version, resolved server definition, invocation flags). Use:

```
npx mcporter inspect-cli dist/context7.js     # human-readable summary
npx mcporter generate-cli --from dist/context7.js  # replay with latest mcporter
```
```

--------------------------------

### Generate and Compile MCP CLI Tools

Source: https://github.com/steipete/mcporter/blob/main/docs/cli-generator.md

Examples of using the mcporter CLI to generate tools from URLs or inline commands. Includes options for minification, runtime selection, and native binary compilation.

```bash
npx mcporter generate-cli --command https://mcp.context7.com/mcp --minify

npx mcporter generate-cli --name context7 --command https://mcp.context7.com/mcp --description "Context7 docs MCP" --runtime bun --compile

chmod +x context7
./context7
```

--------------------------------

### GET /mcporter/config/list

Source: https://github.com/steipete/mcporter/blob/main/docs/config.md

Lists available configuration entries, optionally filtering by HTTP URL or source.

```APIDOC
## GET /mcporter/config/list

### Description
Retrieves a list of all active configuration entries. Note that this command does not auto-run OAuth flows to ensure performance.

### Method
GET

### Endpoint
/mcporter/config/list

### Parameters
#### Query Parameters
- **http-url** (string) - Optional - Filter results by a specific HTTP URL.

### Request Example
GET /mcporter/config/list?http-url=https://api.example.com

### Response
#### Success Response (200)
- **entries** (array) - List of configured servers and their sources.

#### Response Example
{
  "entries": [
    {
      "name": "my-server",
      "source": "~/.mcporter/local.json"
    }
  ]
}
```

--------------------------------

### Generate Standalone CLI using Mcporter (Bash)

Source: https://github.com/steipete/mcporter/blob/main/README.md

Shows how to use the `mcporter generate-cli` command to convert a server definition into a shareable CLI artifact. It includes examples of basic usage, overriding names, adding descriptions, and specifying output paths and runtimes.

```bash
npx mcporter generate-cli \
  --command https://mcp.context7.com/mcp
```

```bash
npx mcporter generate-cli --command "npx -y chrome-devtools-mcp@latest"
```

```bash
npx mcporter generate-cli linear --bundle dist/linear.js
```

```bash
npx mcporter inspect-cli dist/context7.js
```

```bash
npx mcporter generate-cli --from dist/context7.js
```

--------------------------------

### Call MCP Tools

Source: https://github.com/steipete/mcporter/blob/main/README.md

Commands for calling specific tools exposed by MCP servers, including examples for context7 and Linear.

```APIDOC
## Call MCP Tools

### Description
Executes specific tools provided by MCP servers. Requires specifying the server and tool name, along with necessary parameters.

### Method
CLI Command

### Endpoint
N/A (CLI command)

### Parameters
#### CLI Arguments
- `SERVER_NAME.TOOL_NAME` (string) - The identifier for the tool to call.
- `parameter=value` (string) - Key-value pairs for tool parameters.
- `ENVIRONMENT_VARIABLE=value` (string) - Set environment variables for the command.

### Request Example
```bash
# Context7: fetch docs (no auth required)
npx mcporter call context7.resolve-library-id libraryName=react
npx mcporter call context7.get-library-docs context7CompatibleLibraryID=/websites/react_dev topic=hooks

# Linear: search documentation (requires LINEAR_API_KEY)
LINEAR_API_KEY=sk_linear_example npx mcporter call linear.search_documentation query="automations"
```

### Response
#### Success Response (CLI Output)
- The output from the executed tool, which can be text, JSON, or other data formats.

#### Response Example
(Output varies based on the tool called. For `linear.search_documentation`, it would be search results.)
```

--------------------------------

### Inspect MCP Server Tool Signatures

Source: https://github.com/steipete/mcporter/blob/main/README.md

Examples of how MCPorter displays tool signatures in a TypeScript-like format for easy integration into calls.

```typescript
/**
 * Create a comment on a specific Linear issue
 * @param issueId The issue ID
 * @param body The content of the comment as Markdown
 * @param parentId? A parent comment ID to reply to
 */
function create_comment(issueId: string, body: string, parentId?: string);

/**
 * Search the Vercel documentation.
 * @param topic Topic to focus the documentation search on.
 * @param tokens? Maximum number of tokens to include in the result.
 */
function search_vercel_documentation(topic: string, tokens?: number);
```

--------------------------------

### mcporter Configuration JSON Schema Reference

Source: https://github.com/steipete/mcporter/blob/main/docs/config.md

Provides JSON schema examples for IDE support, enabling autocompletion and validation of mcporter configuration files. It shows how to reference the schema from a remote URL or a local repository path.

```json
{
  "$schema": "https://raw.githubusercontent.com/steipete/mcporter/main/mcporter.schema.json",
  "mcpServers": { ... }
}
```

```json
{
  "$schema": "../mcporter.schema.json",
  "mcpServers": { ... }
}
```

--------------------------------

### Tool Signature Declaration Format

Source: https://github.com/steipete/mcporter/blob/main/docs/call-syntax.md

An example of how Mcporter displays tool signatures using TypeScript-like syntax, including parameter types, optionality, and documentation blocks.

```typescript
/**
 * Create a comment on a specific Linear issue.
 * @param issueId The issue ID
 * @param body The content of the comment as Markdown
 * @param parentId? A parent comment ID to reply to
 */
function create_comment(issueId: string, body: string, parentId?: string): Comment;
```

--------------------------------

### List MCP Server Details with pnpm

Source: https://github.com/steipete/mcporter/blob/main/docs/manual-testing.md

This command lists details for a specific MCP server, including metadata and transport information. It is executed within a detached tmux session, with output directed to a log file. Ensure 'pnpm install' has been run recently.

```bash
tmux new-session -d -s list-SERVER \
  'pnpm exec tsx src/cli.ts list SERVER --timeout 2000 > /tmp/list-SERVER.log 2>&1; sleep 5'
sleep 2
cat /tmp/list-SERVER.log
```

--------------------------------

### Discover Live MCP Servers with pnpm

Source: https://github.com/steipete/mcporter/blob/main/docs/manual-testing.md

This command discovers all configured MCP servers and lists their status (healthy, auth required, offline). It runs in a detached tmux session and saves the output to a log file for inspection. Prerequisites include having pnpm installed and recent dependencies.

```bash
tmux new-session -d -s list-all 'pnpm exec tsx src/cli.ts list --timeout 1000 > /tmp/list-all.log 2>&1; sleep 5'
sleep 2
cat /tmp/list-all.log
```

--------------------------------

### Install mcporter package

Source: https://github.com/steipete/mcporter/blob/main/docs/migration.md

Commands to install the mcporter package using various Node.js package managers.

```bash
pnpm add mcporter
yarn add mcporter
npm install mcporter
```

--------------------------------

### Final Mcporter Installation and Verification

Source: https://github.com/steipete/mcporter/blob/main/docs/RELEASE.md

Installs the mcporter package globally using npm and verifies the installation by checking the version. It also performs a final smoke test using npx from an empty directory to ensure it works without global dependencies.

```bash
npm install -g mcporter@<version>
mcporter --version
npx mcporter@<version>
```

--------------------------------

### Call Tools with MCPorter

Source: https://github.com/steipete/mcporter/blob/main/README.md

Demonstrates different ways to call tools using MCPorter, including function-call syntax, flag shorthand, and auto-correct for typos. It also covers how to list server details with richer output.

```bash
mcporter call 'linear.create_issue(title: "Bug", team: "ENG")'

```

```bash
mcporter 'context7.resolve-library-id("react")'

```

```bash
mcporter linear.create_issue title=value team=value

```

```bash
mcporter list <server>

```

```bash
mcporter list <server> --all-parameters

```

--------------------------------

### Invoking Tools via CLI

Source: https://github.com/steipete/mcporter/blob/main/docs/call-syntax.md

Demonstrates the two primary ways to call tools: using flag-based syntax for simple key-value pairs and function-call syntax for complex, schema-aligned arguments.

```bash
mcporter call linear.create_comment --issue-id LNR-123 --body "Hi"
mcporter call 'linear.create_comment(issueId: "LNR-123", body: "Hi")'
```

--------------------------------

### MCPorter Configuration File Structure (JSONC)

Source: https://context7.com/steipete/mcporter/llms.txt

Illustrates the structure of an MCPorter configuration file (JSONC), detailing how to define MCP servers with their descriptions, base URLs, headers, and other options. It also shows how to specify imported configurations.

```jsonc
{
  "$schema": "https://raw.githubusercontent.com/steipete/mcporter/main/mcporter.schema.json",
  "mcpServers": {
    "context7": {
      "description": "Context7 docs MCP",
      "baseUrl": "https://mcp.context7.com/mcp"
    },
    "linear": {
      "description": "Linear issues and projects",
      "baseUrl": "https://mcp.linear.app/mcp",
      "headers": {
        "Authorization": "Bearer ${LINEAR_API_KEY}"
      }
    },
    "chrome-devtools": {
      "description": "Chrome DevTools Protocol",
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "env": { "npm_config_loglevel": "error" },
      "lifecycle": "keep-alive"
    },
    "local-server": {
      "description": "Local development server",
      "command": "bun",
      "args": ["run", "./servers/local.ts"],
      "env": {
        "API_KEY": "${API_KEY:-default_key}",
        "DEBUG": "true"
      }
    },
    "vercel": {
      "description": "Vercel MCP (requires OAuth)",
      "baseUrl": "https://vercel.com/api/mcp",
      "auth": "oauth"
    }
  },
  "imports": ["cursor", "claude-code", "claude-desktop", "codex", "windsurf", "opencode", "vscode"]
}
```

--------------------------------

### POST /mcp/call/:server.help

Source: https://github.com/steipete/mcporter/blob/main/docs/shortcuts.md

Invokes the help tool on a specified MCP server, falling back to a list command if no help tool is defined.

```APIDOC
## POST /mcp/call/:server.help

### Description
Invokes the help tool for a given server. If the server does not expose a 'help' tool, the system automatically falls back to the 'list' command to provide server summary and tool signatures.

### Method
POST

### Endpoint
/mcp/call/:server.help

### Parameters
#### Path Parameters
- **server** (string) - Required - The name or identifier of the configured MCP server.

#### Query Parameters
- **output** (string) - Optional - Set to 'json' for machine-readable output.

### Request Example
`pnpm mcp call chrome-devtools.help`

### Response
#### Success Response (200)
- **content** (string/object) - The help documentation or the server/tool schema summary.

#### Response Example
{
  "status": "success",
  "data": "Server summary and tool signatures..."
}
```

--------------------------------

### Initialize mcporter runtime

Source: https://github.com/steipete/mcporter/blob/main/docs/migration.md

Demonstrates how to create a long-lived runtime instance to list and call tools programmatically.

```typescript
import { createRuntime } from "mcporter";

const runtime = await createRuntime({ configPath: "./config/mcporter.json" });
const tools = await runtime.listTools("chrome-devtools");
await runtime.callTool("chrome-devtools", "take_screenshot", { args: { url: "https://x.com" } });
await runtime.close();
```

--------------------------------

### GET /mcporter/describe/:server

Source: https://github.com/steipete/mcporter/blob/main/docs/shortcuts.md

Retrieves a schema-rich description of an MCP server, acting as a synonym for the list command.

```APIDOC
## GET /mcporter/describe/:server

### Description
Provides a detailed schema-rich output for the specified server. This is a hidden synonym for the 'list' command, designed for agents to discover server capabilities.

### Method
GET

### Endpoint
/mcporter/describe/:server

### Parameters
#### Path Parameters
- **server** (string) - Required - The name or URL of the MCP server.

#### Query Parameters
- **schema** (boolean) - Optional - Include full JSON Schema for every tool.
- **all-parameters** (boolean) - Optional - Include all parameter definitions.

### Request Example
`mcporter describe chrome-devtools --schema`

### Response
#### Success Response (200)
- **schema** (object) - The full schema definition of the server tools.

#### Response Example
{
  "server": "chrome-devtools",
  "tools": [ { "name": "navigate", "parameters": { ... } } ]
}
```

--------------------------------

### Xcode Project Management with `xcp`

Source: https://github.com/steipete/mcporter/blob/main/AGENTS.md

This snippet introduces `xcp`, a helper tool for managing Xcode projects and workspaces. It can list/set targets, manage groups and files, get/set build settings, and manage assets. Use `--help` for detailed usage.

```bash
# Use xcp for Xcode project and workspace management
# Example: xcp --help
```

--------------------------------

### Execute mcporter via Workspace Binaries

Source: https://github.com/steipete/mcporter/blob/main/docs/local.md

Use the installed workspace shim binaries to execute mcporter commands after the package has been added to the project.

```bash
pnpm mcporter:list
pnpm mcporter:call context7.get-library-docs topic=hooks
```

--------------------------------

### Publish Mcporter to npm

Source: https://github.com/steipete/mcporter/blob/main/docs/RELEASE.md

Command to publish the packaged mcporter to the npm registry. This makes the latest version available for global installation or use with npx.

```bash
pnpm publish --tag latest
```

--------------------------------

### Runtime API: callOnce

Source: https://context7.com/steipete/mcporter/llms.txt

The `callOnce` function provides a one-shot API for invoking a single tool without managing runtime lifecycle, automatically handling server discovery, OAuth, and connection closure.

```APIDOC
## Runtime API: callOnce

The `callOnce` function provides a one-shot API for invoking a single tool without managing runtime lifecycle. It automatically discovers the server, handles OAuth, and closes the connection after the call completes.

### Usage

```typescript
import { callOnce } from "mcporter";

// Simple one-shot call
const result = await callOnce({
  server: "firecrawl",
  toolName: "crawl",
  args: { url: "https://anthropic.com" },
});
console.log("Crawl result:", result);

// With explicit config path
const docs = await callOnce({
  server: "context7",
  toolName: "get-library-docs",
  args: {
    context7CompatibleLibraryID: "/websites/react_dev",
    topic: "hooks",
  },
  configPath: "./config/mcporter.json",
});
console.log("Documentation:", docs);
```
```

--------------------------------

### Running Ad-hoc MCP Servers

Source: https://github.com/steipete/mcporter/blob/main/README.md

Shows how to connect to MCP servers directly via CLI flags without modifying the main configuration file. This is useful for testing or one-off tasks.

```bash
# Point at an HTTPS MCP server directly
npx mcporter list --http-url https://mcp.linear.app/mcp --name linear

# Run a local stdio MCP server via Bun
npx mcporter call --stdio "bun run ./local-server.ts" --name local-tools
```

--------------------------------

### CLI: List MCP Servers

Source: https://context7.com/steipete/mcporter/llms.txt

Discover and display configured MCP servers, their tools, and associated metadata.

```APIDOC
## CLI: List MCP Servers

### Description
Discovers and displays all configured MCP servers with their available tools. Supports filtering, schema inspection, and machine-readable output.

### Method
CLI Command

### Endpoint
`npx mcporter list [server_name | url] [options]`

### Parameters
#### Options
- **--schema** (boolean) - Optional - Display full JSON schema for each tool.
- **--all-parameters** (boolean) - Optional - Show all parameters including optional ones.
- **--stdio** (string) - Optional - List tools from an ad-hoc STDIO server command.
- **--env** (string) - Optional - Set environment variables for STDIO servers.
- **--json** (boolean) - Optional - Output results in machine-readable JSON format.

### Request Example
`npx mcporter list linear --schema`

### Response
#### Success Response (stdout)
- **List** (array) - A list of available tools with their TypeScript-style signatures.
```

--------------------------------

### Start Ralph Supervisor Manually

Source: https://github.com/steipete/mcporter/blob/main/docs/subagent.md

Initiates the Ralph supervisor loop manually, specifying a goal and optionally a markdown file for progress tracking. Ralph manages Claude instances for automated tasks.

```bash
bun scripts/ralph.ts start --goal "Your goal here" [--markdown path/to/progress.md]
```

--------------------------------

### Swift Project Build and Validation

Source: https://github.com/steipete/mcporter/blob/main/AGENTS.md

This snippet covers the recommended approach for building and validating Swift projects. It emphasizes using the workspace's build daemon and wrapper scripts for automatic rebuilding, validating changes with `swift build` and filtered test suites, and maintaining accurate concurrency annotations. It also advises against direct editing of derived artifacts.

```swift
// Kick off the workspace’s build daemon or helper before running any Swift CLI or app
// Rely on the provided wrapper to rebuild targets automatically instead of launching stale binaries.

// Validate changes with `swift build` and the relevant filtered test suites
// Document any compiler crashes and rewrite problematic constructs immediately so the suite can keep running.

// Keep concurrency annotations (`Sendable`, actors, structured tasks) accurate
// Prefer static imports over dynamic runtime lookups that break ahead-of-time compilation.

// Avoid editing derived artifacts or generated bundles directly—adjust the sources and let the build pipeline regenerate outputs.

// When encountering toolchain instability, capture the repro steps in the designated troubleshooting doc and note any required cache cleans (DerivedData, SwiftPM caches) you perform.
```

--------------------------------

### Runtime API: createServerProxy

Source: https://context7.com/steipete/mcporter/llms.txt

The `createServerProxy` function creates an ergonomic proxy that maps camelCase method calls to MCP tool invocations, with automatic argument validation and JSON-schema default application.

```APIDOC
## Runtime API: createServerProxy

The `createServerProxy` function creates an ergonomic proxy that maps camelCase method calls to MCP tool invocations, with automatic argument validation and JSON-schema default application.

### Usage

```typescript
import { createRuntime, createServerProxy } from "mcporter";

const runtime = await createRuntime();

// Create typed proxies for servers
const chrome = createServerProxy(runtime, "chrome-devtools");
const linear = createServerProxy(runtime, "linear");
const context7 = createServerProxy(runtime, "context7");

// Call tools as methods (camelCase maps to kebab-case)
const snapshot = await chrome.takeSnapshot();
console.log("Page content:", snapshot.text());

// Pass arguments as object
const docs = await linear.searchDocumentation({
  query: "automations",
  page: 0,
});
console.log("Search results:", docs.json());

// Use positional arguments (maps to required schema fields)
const libraryId = await context7.resolveLibraryId("react");
console.log("Library ID:", libraryId.json());

// Access raw MCP response
const issues = await linear.listIssues({ assignee: "me" });
console.log("Raw response:", issues.raw);

// Extract images from response
const screenshot = await chrome.takeScreenshot();
const images = screenshot.images();
if (images) {
  console.log(`Got ${images.length} images`);
}

await runtime.close();
```
```

--------------------------------

### Manage MCPorter Daemon

Source: https://github.com/steipete/mcporter/blob/main/README.md

Commands to control the MCPorter daemon, which keeps stateful servers warm. It allows checking status, starting, stopping, and restarting the daemon. Configuration can be applied to manage ephemeral servers.

```bash
mcporter daemon status

```

```bash
mcporter daemon stop

```

```bash
mcporter daemon start

```

```bash
mcporter daemon restart

```

```bash
mcporter daemon start --log

```

```bash
mcporter daemon start --log-file /tmp/daemon.log

```

--------------------------------

### Launch and Attach to Claude Tmux Session

Source: https://github.com/steipete/mcporter/blob/main/docs/subagent.md

Starts a new detached tmux session for a Claude agent and then attaches to it. This is the recommended way to run subagents to ensure sessions persist and bypass runner timeouts.

```bash
tmux new-session -d -s claude-haiku 'claude --model haiku'
tmux attach -t claude-haiku
```

--------------------------------

### Perform Ad-hoc HTTP Operations

Source: https://github.com/steipete/mcporter/blob/main/docs/adhoc.md

Demonstrates how to list resources and call tools on an MCP server directly via its URL without needing a pre-existing configuration entry.

```bash
# Inspect the server directly via URL (no config entry needed)
mcporter list 'https://mcp.sentry.dev/mcp?agent=1'

# Call a tool by repeating the same URL + tool suffix
mcporter call 'https://mcp.sentry.dev/mcp?agent=1.use_sentry(request: "yo whats up")'
```

--------------------------------

### Supabase OAuth Error Response

Source: https://github.com/steipete/mcporter/blob/main/docs/supabase-auth-issue.md

An example of the JSON error payload returned by the Supabase hosted MCP server when an invalid scope is requested. This illustrates the mismatch between standard MCP scopes and provider-specific requirements.

```json
{"message":"scope.0: Invalid enum value. Expected 'organizations:read' | 'projects:read' | 'projects:write' | 'database:write' | 'database:read' | 'analytics:read' | 'secrets:read' | 'edge_functions:read' | 'edge_functions:write' | 'environment:read' | 'environment:write' | 'storage:read', received 'mcp:tools'"}
```

--------------------------------

### Handling Environment Variable Placeholders

Source: https://github.com/steipete/mcporter/blob/main/docs/config.md

Syntax for using environment variables in configuration files, including support for default fallback values.

```json
"api_key": "${LINEAR_API_KEY}"
"port": "${PORT:-8080}"
```

--------------------------------

### Inspect Daemon Logs and Status

Source: https://github.com/steipete/mcporter/blob/main/docs/logging.md

Commands to check the status of the mcporter daemon, which includes the log file path if logging is enabled. The format of log entries for call start, success, and error events is also shown.

```bash
mcporter daemon status
tail -f ~/.mcporter/daemon/daemon-<config-hash>.log
```

```log
[daemon] 2025-11-10T15:08:21.123Z callTool start server=chrome-devtools tool=take_snapshot
[daemon] 2025-11-10T15:08:22.004Z callTool success server=chrome-devtools tool=take_snapshot
[daemon] 2025-11-10T15:08:23.005Z callTool error server=chrome-devtools tool=take_snapshot err=Error: Something went wrong
```

--------------------------------

### Run Claude for Help or Delegation

Source: https://github.com/steipete/mcporter/blob/main/docs/subagent.md

Demonstrates two ways to invoke Claude: using the repo wrapper for help commands and launching directly within tmux for actual task delegation.

```bash
# For help
./runner claude --help

# For delegation (inside tmux)
claude --model haiku --dangerously-skip-permissions
```

--------------------------------

### Generate TypeScript Types (.d.ts)

Source: https://github.com/steipete/mcporter/blob/main/docs/emit-ts.md

Example of using mcporter emit-ts to generate only the TypeScript definition file (`.d.ts`). This file provides type checking for server methods and their parameters, improving code quality and developer experience.

```bash
mcporter emit-ts linear --out types/linear-tools.d.ts
```

```typescript
import type { CallResult } from 'mcporter';

export interface LinearTools {
  /**
   * List comments for a specific Linear issue.
   *
   * @param issueId The issue ID
   */
  list_comments(params: { issueId: string }): Promise<CallResult>;
}
```

--------------------------------

### Interact with Tools using Mcporter Runtime API (TypeScript)

Source: https://github.com/steipete/mcporter/blob/main/README.md

Demonstrates how to use the `mcporter` library to create a runtime, proxy to tools like Chrome DevTools and Linear, and call their functions. It shows how to handle results using helper methods like `.text()` and `.json()`, and mentions the option to use `runtime.callTool()` for explicit control.

```typescript
import { createRuntime, createServerProxy } from "mcporter";

const runtime = await createRuntime();
const chrome = createServerProxy(runtime, "chrome-devtools");
const linear = createServerProxy(runtime, "linear");

const snapshot = await chrome.takeSnapshot();
console.log(snapshot.text());

const docs = await linear.searchDocumentation({
	query: "automations",
	page: 0,
});
console.log(docs.json());
```