Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# MCPorter 🧳 - Call MCPs from TypeScript or as CLI

<p align="center">
<img src="https://raw.githubusercontent.com/steipete/mcporter/main/mcporter.png" alt="MCPorter header banner" width="1100">
<img src="https://raw.githubusercontent.com/openclaw/mcporter/main/mcporter.png" alt="MCPorter header banner" width="1100">
</p>

<p align="center">
<a href="https://www.npmjs.com/package/mcporter"><img src="https://img.shields.io/npm/v/mcporter?style=for-the-badge&logo=npm&logoColor=white" alt="npm version"></a>
<a href="https://github.com/steipete/mcporter/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/steipete/mcporter/ci.yml?branch=main&style=for-the-badge&label=tests" alt="CI Status"></a>
<a href="https://github.com/steipete/mcporter"><img src="https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=for-the-badge" alt="Platforms"></a>
<a href="https://github.com/openclaw/mcporter/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/openclaw/mcporter/ci.yml?branch=main&style=for-the-badge&label=tests" alt="CI Status"></a>
<a href="https://github.com/openclaw/mcporter"><img src="https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=for-the-badge" alt="Platforms"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT License"></a>
</p>

Expand Down
6 changes: 3 additions & 3 deletions docs/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Global Options:
-h, --help Display help for mcporter config

Run `mcporter config help add` to see transport flags, ad-hoc persistence tips, and schema docs.
See https://github.com/sweetistics/mcporter/blob/main/docs/config.md for config anatomy, import precedence, and troubleshooting guidance.
See https://github.com/openclaw/mcporter/blob/main/docs/config.md for config anatomy, import precedence, and troubleshooting guidance.
```

# Configuration Guide
Expand All @@ -44,7 +44,7 @@ mcporter keeps three configuration buckets in sync: repository-scoped JSON (`con
1. Create `config/mcporter.json` at the repo root:
```jsonc
{
"$schema": "https://raw.githubusercontent.com/steipete/mcporter/main/mcporter.schema.json",
"$schema": "https://raw.githubusercontent.com/openclaw/mcporter/main/mcporter.schema.json",
"mcpServers": {
"linear": {
"description": "Linear issues",
Expand Down Expand Up @@ -190,7 +190,7 @@ mcporter provides a JSON Schema for config file validation and autocompletion. A

```jsonc
{
"$schema": "https://raw.githubusercontent.com/steipete/mcporter/main/mcporter.schema.json",
"$schema": "https://raw.githubusercontent.com/openclaw/mcporter/main/mcporter.schema.json",
"mcpServers": { ... }
}
```
Expand Down
25 changes: 12 additions & 13 deletions docs/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ summary: 'Five-minute walk through listing MCP servers, calling a tool, and emit

# Quickstart

This walkthrough assumes you already have an MCP server configured in Cursor, Claude Code/Desktop, Codex, Windsurf, OpenCode, or VS Code. If not, copy [`config/mcporter.example.json`](https://github.com/steipete/mcporter/blob/main/config/mcporter.example.json) into `~/.mcporter/mcporter.json` and edit it — see [Configuration](config.md) for the full schema.
This walkthrough uses the public Context7 server so you can follow the tool examples without existing MCP configuration. Add it with `npx mcporter config add context7 https://mcp.context7.com/mcp` if it is not already discovered from Cursor, Claude Code/Desktop, Codex, Windsurf, OpenCode, or VS Code. See [Configuration](config.md) for more options and the full schema.

## 1. List the servers mcporter sees

Expand All @@ -17,7 +17,7 @@ You get one row per server with auth status, transport type, and tool count. Add
## 2. Inspect a single server

```bash
npx mcporter list linear
npx mcporter list context7
```

Single-server output reads like a TypeScript header file: dimmed `/** … */` doc comments above each `function name(...)` signature, with optional parameters summarised so the screen stays scannable. Add flags to drill in:
Expand All @@ -34,22 +34,21 @@ Single-server output reads like a TypeScript header file: dimmed `/** … */` do

```bash
# Colon-delimited flags (shell-friendly).
npx mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!'
npx mcporter call context7.resolve-library-id query:'React hooks docs' libraryName:react

# Function-call style copy/pasted from `mcporter list`.
npx mcporter call 'linear.create_comment(issueId: "ENG-123", body: "Looks good!")'

# Anything after `--` is a literal positional value.
npx mcporter call docs.fetch -- --raw-string-with-leading-dashes
npx mcporter call 'context7.resolve-library-id(query: "React hooks docs", libraryName: "react")'
```

Pick the output format with `--output text|markdown|json|raw`. Use `--save-images <dir>` to persist binary content blocks. See [CLI reference](cli-reference.md) for the full flag list.

## 4. Read MCP resources
## 4. Read MCP resources (optional)

Context7 exposes tools but not resources. If another configured server exposes resources, list or read them with:

```bash
npx mcporter resource docs # list resources
npx mcporter resource docs file:///path/to/spec.md # read a resource
npx mcporter resource my-resource-server # list resources
npx mcporter resource my-resource-server file:///path/to/spec.md # read a resource
```

Output formatting is shared with `mcporter call` (`--output`, `--json`, `--raw`).
Expand All @@ -59,16 +58,16 @@ Output formatting is shared with `mcporter call` (`--output`, `--json`, `--raw`)
When you want to share a tool with someone who shouldn't have to learn `mcporter call`:

```bash
npx mcporter generate-cli linear --bundle dist/linear.js
node dist/linear.js create-comment --issue-id ENG-123 --body 'Looks good!'
npx mcporter generate-cli context7 --runtime node --bundler rolldown --bundle dist/context7.js
node dist/context7.js resolve-library-id --query 'React hooks docs' --library-name react
```

Add `--compile <path>` for a Bun-compiled binary, or `--include-tools a,b,c` to ship a subset. Full details in [CLI generator](cli-generator.md).

## 6. Emit typed clients for agents

```bash
npx mcporter emit-ts linear --mode client --out src/linear-client.ts
npx mcporter emit-ts context7 --mode client --out src/context7-client.ts
```

You get a `.d.ts` interface and a `createServerProxy()`-backed factory. Calls return `CallResult` objects with `.text()`, `.markdown()`, `.json()`, `.images()`, `.content()` helpers — see [Tool calling](tool-calling.md) for the proxy API and [emit-ts](emit-ts.md) for the generator.
Expand Down
2 changes: 1 addition & 1 deletion mcporter.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -388,5 +388,5 @@
"required": ["mcpServers"],
"additionalProperties": false,
"description": "mcporter configuration file schema",
"$id": "https://raw.githubusercontent.com/steipete/mcporter/main/mcporter.schema.json"
"$id": "https://raw.githubusercontent.com/openclaw/mcporter/main/mcporter.schema.json"
}
2 changes: 1 addition & 1 deletion scripts/generate-json-schema.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import { writeFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { RawConfigSchema } from '../src/config-schema.js';

export const CONFIG_SCHEMA_ID = 'https://raw.githubusercontent.com/steipete/mcporter/main/mcporter.schema.json';
export const CONFIG_SCHEMA_ID = 'https://raw.githubusercontent.com/openclaw/mcporter/main/mcporter.schema.json';
export const CONFIG_SCHEMA_DRAFT = 'https://json-schema.org/draft/2020-12/schema';

export function buildConfigJsonSchema(): Record<string, unknown> {
Expand Down