typeship-ax

面向 typeship（v0.1.0）的类型化、零依赖 TypeScript SDK + CLI + MCP 服务器。

由 typeship 根据 OpenAPI 规范生成——请勿手动编辑；请重新生成。

• 零运行时依赖 —— 基于平台 fetch（Node 18+、浏览器、边缘运行时）

• 类型化错误联合 —— 每次调用返回 ApiResult<T, E>，其中 E 列出了该操作所记录的每个错误

• 自动分页 —— 对任何列表调用使用 for await 即可流式获取每一页的所有条目

• 内置重试 —— 幂等请求使用指数退避和 Retry-After 支持进行重试

• 可选运行时验证 —— validate: true 根据规范对请求和响应体进行模式检查，仍然零依赖

• 可摇树优化 —— 按资源划分模块，sideEffects: false

安装

npm install typeship-ax

在首次发布之前，请从生成的文件夹安装：npm install ./typeship-ax。

Related MCP server: @typeship-ax/mcp

快速开始

import { TypeshipClient } from "typeship-ax";

const client = new TypeshipClient({ bearerToken: process.env.TYPESHIP_TOKEN! });

for await (const item of client.projects.list()) {
  console.log(item);
}

身份验证

• Bearer 令牌 —— bearerToken（字符串，或用于过期令牌的回调），作为 Authorization: Bearer <token> 发送。

defaultHeaders 为每个请求添加标头（API 版本标头、租户 ID）；onRequest 可以在请求发送前重写任何请求。

错误处理

HTTP 错误不会抛出异常。每次调用返回一个可辨识的结果，错误侧是该操作所记录的错误类的联合：

import { UnauthorizedError } from "typeship-ax";

const result = await client.projects.list();

if (!result.ok) {
  if (result.error instanceof UnauthorizedError) {
    // result.error.body is fully typed for this status
  }
  throw result.error; // every branch is an Error subclass
}

result.data; // typed success payload

更喜欢异常？unwrap(result) 返回数据或抛出类型化错误。

分页

for await (const item of client.projects.list()) {
  // every item from every page, fetched lazily
}

// or page manually:
const page = await client.projects.list();
if (page.ok) {
  page.data.items;
  await page.data.getNextPage();
}

CLI

该包附带一个命令行工具 typeship：每个操作都是一个命令，带有类型化标志，JSON 输出到 stdout，退出码为 0/1/2（成功 / 失败 / 用法错误）。全局安装，或从克隆运行（npm install && npm run build，然后 node dist/cli.js）。

npm install -g typeship-ax
typeship login                      # stores a credential (or set TYPESHIP_TOKEN)
typeship projects list
typeship projects create --name "<name>"
typeship projects list --all | jq -r '.id'   # every page, one item per line
typeship <resource> <command> --help     # flags, types, an example

路径参数是位置参数；其他所有内容都是按线上字段命名的标志（--name、--limit）。数组字段接受逗号列表或重复标志，对象字段接受 JSON，--data '<json>'（或 --data @file、--data -）设置整个请求体。--fields id,name 仅保留结果的这些字段。日期标志接受相对形式（-7d、"7 days ago"、today）以及 ISO 8601。分页命令打印一页，并附带获取下一页的命令；--all 以 NDJSON 流式输出每个条目。破坏性命令会询问，或接受 --force。错误在管道输出时以 JSON 信封形式输出到 stderr（{status, issues[{code}], next_steps}），在终端上则以散文形式输出。

身份验证：typeship login 将凭据存储在 ~/.config/typeship/ 下；环境变量（TYPESHIP_TOKEN）和标志（--token）优先于它。TYPESHIP_BASE_URL / --base-url 选择端点。

此外：typeship init 连接机器：凭据、为找到的代理客户端配置 MCP、AGENTS.md 块；typeship mcp install --all 将 MCP 服务器注册到 Claude Code、Cursor、Codex、VS Code 等；typeship docs <resource> <command> 打印完整参考，typeship docs search <term> 搜索它；typeship completion bash|zsh、typeship doctor、typeship upgrade、typeship agent-guide 和 typeship help --json 供代理使用。运行 typeship --help 查看地图。

MCP 服务器

一个零依赖的 stdio MCP 服务器，将每个操作暴露为工具。添加到您的 MCP 客户端配置：

{
  "mcpServers": {
    "typeship": {
      "command": "node",
      "args": [
        "<path-to>/typeship-ax/dist/mcp.js"
      ],
      "env": {
        "TYPESHIP_TOKEN": "…"
      }
    }
  }
}

工具输入模式源自规范，因此代理可以看到真实的参数类型和必填字段。参数在到达 API 之前会被检查（未知或类型错误的参数会作为一个 isError 结果返回，不会丢弃任何内容），每个工具都接受 fields 以仅保留所需的结果键，错误带有稳定的 code 和 next_steps。

在 args 中添加 --read-only（或设置 TYPESHIP_MCP_READ_ONLY=1）以使用无法写入的服务器，--tools accounts,reports（或 TYPESHIP_MCP_TOOLS）以暴露子集，TYPESHIP_MCP_MAX_RESULT_CHARS 更改结果大小上限（64,000）。typeship mcp install --claude --read-only 为您写入只读条目。

配置

new TypeshipClient({
  baseUrl: "https://typeship.dev/api/v1", // default
  timeoutMs: 30_000, // per attempt
  maxRetries: 2,     // retryable failures only
  fetch: globalThis.fetch, // or your own: proxies, tests, instrumentation
});

每次调用的覆盖项位于最后一个参数：{ timeoutMs, maxRetries, headers, signal }。