ByteNoteByteNote
字

字节笔记本

2026年2月22日

MCPorter：TypeScript MCP 运行时与 CLI 工具包

#开源工具

本文介绍 MCPorter，一个 TypeScript 运行时、CLI 和代码生成工具包，用于 Model Context Protocol (MCP)。MCPorter 帮助开发者发现已配置的 MCP 服务器、直接调用它们、在 TypeScript 中编写更丰富的自动化脚本，并在需要分享工具时生成单一用途的 CLI。

项目简介

MCPorter 是由 steipete 开发的开源项目，旨在简化 MCP (Model Context Protocol) 服务器的使用。截至目前，该项目在 GitHub 上已获得 2k+ stars，是一个活跃维护的 TypeScript 项目。

MCPorter 的核心价值在于让开发者能够：

  • 零配置发现已安装的 MCP 服务器
  • 一键生成 CLI 工具
  • 使用类型安全的 API 调用 MCP 工具
  • 支持 OAuth 和 stdio 传输协议

核心特性

  • 零配置发现：createRuntime() 自动合并 home 配置、项目配置以及 Cursor/Claude/Codex/Windsurf/OpenCode/VS Code 的导入配置，支持环境变量占位符展开
  • 一键 CLI 生成：mcporter generate-cli 将任何 MCP 服务器定义转换为可运行的 CLI，支持打包/编译
  • 类型化工具客户端：mcporter emit-ts 生成 .d.ts 接口或可直接运行的客户端包装器
  • 友好的可组合 API：createServerProxy() 将工具暴露为符合人体工程学的 camelCase 方法，自动应用 JSON Schema 默认值
  • OAuth 和 stdio 人机工程学：内置 OAuth 缓存、日志追踪和 stdio 包装器
  • 临时连接：无需修改配置即可指向任意 MCP 端点

技术栈

  • TypeScript - 主要开发语言
  • Bun/Node.js - 运行时支持
  • Model Context Protocol - 核心协议
  • OAuth 2.0 - 认证支持

安装指南

使用 npx（无需安装）

bash
npx mcporter list

添加到项目

bash
pnpm add mcporter

Homebrew 安装

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

快速开始

列出已配置的 MCP 服务器

bash
npx mcporter list
npx mcporter list context7 --schema
npx mcporter list https://mcp.linear.app/mcp --all-parameters

调用 MCP 工具

bash
# 使用冒号分隔的参数（shell 友好）
npx mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!'

# 使用函数调用风格
npx mcporter call 'linear.create_comment(issueId: "ENG-123", body: "Looks good!")'

Context7 示例（无需认证）

bash
npx mcporter call context7.resolve-library-id libraryName=react
npx mcporter call context7.get-library-docs context7CompatibleLibraryID=/websites/react_dev topic=hooks

Linear 示例（需要 LINEAR_API_KEY）

bash
LINEAR_API_KEY=sk_linear_example npx mcporter call linear.search_documentation query="automations"

使用示例

生成 CLI 工具

bash
npx mcporter generate-cli linear --output ./linear-cli

生成 TypeScript 类型

bash
npx mcporter emit-ts linear --output ./linear-types.d.ts

临时连接 MCP 服务器

bash
# 直接指向 HTTPS MCP 服务器
npx mcporter list --http-url https://mcp.linear.app/mcp --name linear

# 通过 Bun 运行本地 stdio MCP 服务器
npx mcporter call --stdio "bun run ./local-server.ts" --name local-tools

高级功能

守护进程模式

MCPorter 支持守护进程模式来保持 MCP 服务器常驻：

bash
# 检查守护进程状态
mcporter daemon status

# 启动守护进程
mcporter daemon start

# 停止守护进程
mcporter daemon stop

自动纠错

如果输入了错误的工具名称，MCPorter 会自动检查服务器的工具目录并提示正确的名称：

bash
$ mcporter call linear.creat_issue title="Bug"
Did you mean: create_issue?

丰富的输出格式

bash
# JSON 输出
npx mcporter list --json

# 原始输出
npx mcporter call linear.list_issues --raw

# 显示所有参数
npx mcporter list vercel --all-parameters

API 参考

createRuntime()

创建运行时实例，自动发现并配置 MCP 服务器：

typescript
import { createRuntime } from 'mcporter'

const runtime = await createRuntime()
const result = await runtime.call('linear.list_issues')

createServerProxy()

创建服务器代理，提供类型安全的工具调用：

typescript
import { createServerProxy } from 'mcporter'

const linear = await createServerProxy('linear')
const issues = await linear.list_issues({ assignee: 'me' })

CallResult 助手方法

typescript
const result = await runtime.call('some.tool')

// 获取不同格式的输出
const text = result.text()      // 纯文本
const markdown = result.markdown()  // Markdown
const json = result.json()      // JSON 对象
const content = result.content()    // 原始内容

配置说明

MCPorter 支持多级配置合并：

  1. ~/.mcporter/mcporter.json[c] - 用户级配置
  2. config/mcporter.json - 项目级配置
  3. Cursor/Claude/Codex/Windsurf/OpenCode/VS Code 导入

配置示例：

json
{
  "servers": {
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp",
      "auth": {
        "type": "bearer",
        "token": "${LINEAR_API_KEY}"
      }
    }
  }
}

注意事项

  • 使用 OAuth 保护的 MCP 服务器前，需要先运行 npx mcporter auth <server> 完成登录
  • 默认超时时间为 30 秒，可通过 MCPORTER_CALL_TIMEOUT 环境变量调整
  • OAuth 浏览器握手有 60 秒的宽限期，可通过 --oauth-timeout 调整
  • 临时连接（--stdio 或 --http-url）需要每次调用时重复指定参数，除非使用 --persist 保存配置

项目链接

开源工具
上一篇

bird - X/Twitter 高速 CLI 工具

下一篇

MCPorter：TypeScript MCP 运行时与 CLI 工具包

分享: