ClaudeCode SDK

A standalone TypeScript SDK for Claude Code — decoupled from Claude Code runtime.

ClaudeCode SDK 将 Claude Code 的核心能力封装为独立的 TypeScript 库，不依赖 Claude Code 运行时（React / Ink / Bun）。你可以将它集成到任何 Node.js 应用中，直接调用 Claude 的对话、工具执行和 MCP 集成能力。

---

特性

• 4 种 LLM Provider — Anthropic Direct / AWS Bedrock / Google Vertex / Azure Foundry
• 14 个内置工具 — Bash、文件读写编辑、Glob、Grep、WebFetch、WebSearch、Task 系列（6 个）
• MCP 协议集成 — 连接任何 MCP 兼容的工具服务器（stdio / HTTP）
• 流式 + 非流式双 API — send() 和 stream() 两种模式
• ask / askStream 高层 API — 自动工具调用循环，一行代码完成"提问→执行→结果"
• 权限系统 — auto / manual / plan / bypass 四种模式
• 工具调用循环 — 自动多轮工具调用，最大深度可配置
• 对话管理 — 消息历史、Token 追踪、自动压缩
• 零运行时依赖 — 不依赖 Claude Code 的 React/Ink/Bun 运行时
• 完整 TypeScript 类型 — 所有 API 都有完整类型声明

---

安装

npm install claude-code-sdk-ts
Copy

依赖

• @anthropic-ai/sdk — Anthropic Direct API
• @modelcontextprotocol/sdk — MCP 协议支持（可选模块）
• zod — 工具输入校验

---

快速开始

Anthropic Direct API

import { ClaudeCodeSDK, registerAllBuiltInTools } from 'claude-code-sdk-ts'

// 创建 SDK 实例
const sdk = ClaudeCodeSDK.create({
  llm: {
    provider: 'anthropic',
    model: 'claude-sonnet-4-6',
    apiKey: process.env.ANTHROPIC_API_KEY,
  },
})

// 注册内置工具
registerAllBuiltInTools(sdk.getTools())

// 发送消息
const response = await sdk.send('Hello, what can you do?')
console.log(response.content)
Copy

流式响应

const stream = sdk.stream('Tell me a story about a cat')
for await (const event of stream) {
  if (event.type === 'text') {
    process.stdout.write(event.text)
  }
}
Copy

send() 返回值

sdk.send() 返回的 SessionResponse 包含三个字段：

interface SessionResponse {
  content: string          // 模型最终回复文本
  usage: TokenUsage        // Token 用量（inputTokens / outputTokens）
  toolCalls: Array<{       // 本轮执行的工具调用记录
    toolName: string
    input: Record<string, unknown>
    output: unknown
  }>
}
Copy

---

配置

环境变量

变量	用途
ANTHROPIC_API_KEY	Anthropic Direct API Key
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY	AWS Bedrock 凭证
AWS_REGION	Bedrock 区域（默认 us-east-1）
GOOGLE_APPLICATION_CREDENTIALS	Google Vertex 凭据路径
VERTEX_PROJECT_ID	Vertex 项目 ID
AZURE_FOUNDRY_API_KEY	Azure Foundry API Key
AZURE_FOUNDRY_RESOURCE_NAME	Azure Foundry 资源名

Provider 配置

Anthropic Direct:

{
  provider: 'anthropic',
  model: 'claude-sonnet-4-6',
  apiKey: 'sk-ant-...',
  baseUrl?: 'https://api.anthropic.com',  // 可选
}
Copy

AWS Bedrock:

{
  provider: 'bedrock',
  model: 'anthropic.claude-sonnet-4-20250514',
  region?: 'us-east-1',
  accessKeyId?: '...',  // 可选，默认从环境变量读取
  secretAccessKey?: '...',  // 可选
}
Copy

Google Vertex:

{
  provider: 'vertex',
  model: 'claude-sonnet-4-20250514',
  projectId: 'my-gcp-project',
  region?: 'us-east5',
}
Copy

Azure Foundry:

{
  provider: 'foundry',
  model: 'claude-sonnet-4-20250514',
  resourceName: 'my-resource',
  apiKey: '...',
}
Copy

---

内置工具

所有内置工具可通过 registerAllBuiltInTools() 一键注册，也可单独使用。

基础工具（8 个）

工具	说明
BashTool	执行 Shell 命令
FileReadTool	读取文件（支持文本、PDF、图片、Notebook）
FileWriteTool	创建/覆写文件
FileEditTool	字符串替换式编辑 + diff 追踪
GlobTool	文件模式匹配搜索
GrepTool	文件内容正则搜索
WebFetchTool	URL 抓取 → Markdown
WebSearchTool	DuckDuckGo 网页搜索

Task 工具（6 个）

可通过 registerAllTaskTools() 单独注册。

工具	说明
TaskCreateTool	创建任务
TaskGetTool	查询任务详情
TaskListTool	列出所有任务
TaskUpdateTool	更新任务状态
TaskStopTool	停止任务
TaskOutputTool	获取任务输出

import { BashTool, FileReadTool } from 'claude-code-sdk-ts'
sdk.use(new BashTool().toTool(), new FileReadTool().toTool())

// 也可以只注册 Task 工具
import { registerAllTaskTools } from 'claude-code-sdk-ts'
registerAllTaskTools(sdk.getTools())
Copy

---

ask / askStream — 高层 API

除了 send() / stream()，SDK 还提供了 ask() 和 askStream() 两个高层函数，自动完成"发送→工具调用→返回结果"的完整循环，无需手动管理 SDK 实例。

ask()

import { ask, ToolRegistry, createLLMConnector } from 'claude-code-sdk-ts'

const llm = createLLMConnector({
  provider: 'anthropic',
  model: 'claude-sonnet-4-6',
  apiKey: process.env.ANTHROPIC_API_KEY,
})

const tools = new ToolRegistry()
registerAllBuiltInTools(tools)

const result = await ask(llm, {
  systemPrompt: 'You are a helpful assistant.',
  messages: [{ role: 'user', content: '列出当前目录的文件', id: '1', createdAt: new Date().toISOString() }],
  tools,
})

console.log(result.text)       // 最终回复文本
console.log(result.usage)      // Token 用量
console.log(result.toolCalls)  // 工具调用记录
Copy

askStream()

const stream = askStream(llm, {
  messages: [{ role: 'user', content: 'Tell me a joke', id: '1', createdAt: new Date().toISOString() }],
  tools,
})

for await (const event of stream) {
  if (event.type === 'text') {
    process.stdout.write(event.text)
  }
  if (event.type === 'result') {
    console.log('\nDone:', event.result.usage)
  }
}
Copy

AskOptions

参数	类型	说明
autoExecuteTools	boolean	是否自动执行工具调用（默认 true）
onToolCall	(name, input) => Promise<boolean>	工具执行前钩子，返回 false 跳过
maxToolCallDepth	number	最大工具调用深度（默认 10）
feedback	FeedbackOptions	反馈选项（manual / auto）

---

MCP 协议集成

SDK 支持 Model Context Protocol (MCP)，可以连接任何 MCP 兼容的工具服务器。

配置式集成

const sdk = ClaudeCodeSDK.create({
  llm: { provider: 'anthropic', model: 'claude-sonnet-4-6', apiKey: '...' },
  mcpServers: [
    {
      name: 'github',
      type: 'url',
      commandOrUrl: 'https://mcp.github.com/',
      authorizationToken: 'ghp_...',
    },
    {
      name: 'local-fs',
      type: 'stdio',
      commandOrUrl: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '/path/to/project'],
    },
  ],
})
// MCP 工具自动注册，send/stream 时自动可用
Copy

编程式集成

// ClaudeCodeSDK.create() 和 new ClaudeCodeSDK() 等价
// create() 只是简单调用 new，推荐使用 create()
const sdk = ClaudeCodeSDK.create({ llm: { provider: 'anthropic', ... } })
await sdk.connectMCPServers({
  name: 'my-server',
  type: 'stdio',
  commandOrUrl: 'python',
  args: ['server.py'],
})
Copy

MCP Server 配置

参数	类型	说明
name	string	服务器唯一标识
type	'stdio' | 'url'	传输类型
commandOrUrl	string	stdio 命令 或 HTTP URL
args	string[]	stdio 命令参数
env	Record<string, string>	环境变量
authorizationToken	string	远程服务器鉴权 Token
toolConfiguration	object	工具过滤配置

---

API 参考

ClaudeCodeSDK

方法	说明
ClaudeCodeSDK.create(config)	工厂方法创建实例（与 new ClaudeCodeSDK(config) 等价）
sdk.use(...tools)	注册工具（链式调用）
sdk.send(message)	发送消息，获取完整响应
sdk.stream(message)	发送消息，流式获取事件
sdk.newConversation()	开始新对话
sdk.getHistory()	获取对话历史
sdk.getTokenUsage()	获取 Token 用量
sdk.withPermissionMode(mode)	设置权限模式
sdk.connectMCPServers(...servers)	编程式连接 MCP 服务器
sdk.disconnectMCPServers()	断开所有 MCP 连接
sdk.getMCPConnections()	获取 MCP 连接信息

ToolRegistry

方法	说明
registry.register(...tools)	注册一个或多个工具
registry.get(name)	按名称获取工具
registry.getAll()	获取所有已注册工具
registry.getTools()	获取只读工具数组
registry.has(name)	检查工具是否已注册
registry.execute(name, input)	执行指定工具

---

开发

# 克隆
git clone https://github.com/DZCD/claude-code-sdk.git
cd claude-code-sdk

# 安装依赖
npm install

# 构建
npm run build

# 测试
npm test

# 类型检查
npm run type-check
Copy

项目结构

src/
├── ask/             # 高层 ask / askStream API
├── config/          # 配置管理（多源合并、环境变量）
├── context/         # 上下文构建（Git 状态、CLAUDE.md）
├── conversation/    # 对话管理（消息历史、工具调用循环）
├── feedback/        # 反馈注入机制
├── hooks/           # 事件钩子系统
├── llm/             # LLM 通信层
│   ├── anthropic.ts  # Anthropic Direct API
│   ├── bedrock.ts    # AWS Bedrock
│   ├── vertex.ts     # Google Vertex
│   └── foundry.ts    # Azure Foundry
├── mcp/             # MCP 协议集成
│   ├── manager.ts    # 多 Server 生命周期管理
│   └── tool-adapter.ts  # MCP Tool → SDK Tool 适配器
├── permission/      # 权限系统（模式、规则引擎）
├── session/         # 会话引擎（主入口 ClaudeCodeSDK）
├── tools/           # 工具系统
│   ├── built-in/     # 内置工具实现
│   └── registry.ts   # 工具注册中心
└── types/           # 类型定义
Copy

---

质量

指标	数值
测试数	234 ✅
语句覆盖率	82.84%
函数覆盖率	91.02%
TypeScript	零错误编译

---

License

MIT

---

致谢

• Anthropic Claude
• Model Context Protocol
• obra/superpowers — 开发工作流方法论