# @civic/mcp-client 中文文档

规范地址：https://npmcn.com/package/%40civic/mcp-client/

版本：2\.0\.0
npm 元数据更新时间：2026-10-30T07:49:27.977Z
中文译文更新时间：2026-11-09T22:37:44.367Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40civic/mcp-client
原文对照：https://npmcn.com/package/%40civic/mcp-client/?lang=original
项目主页：https://github.com/civicteam/civic-mcp#readme
源码仓库：https://github.com/civicteam/civic-mcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：296 kB，32 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- peer 依赖：ai \>=6\.0\.79，openai \>=6\.9\.1，@langchain/core \>=1\.0\.0，@anthropic-ai/sdk ^0\.71\.0
- 首次发布：2026-03-18T15:34:21.352Z
- 最新版本发布：2026-10-09T15:13:44.950Z
- 近 30 天下载量：4419（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

TypeScript 客户端库,用于连接 Civil Hub 和向 AI SDK 曝光 MCP 工具

## 安装

```sh
npm install @civic/mcp-client
```

也可以使用：`pnpm add @civic/mcp-client`、`yarn add @civic/mcp-client`、`bun add @civic/mcp-client`

## README

# @civic/mcp-客户端

TypeScript客户端库,用于连接 Civil MCP Hub,并将MCP(模式上下文协议)工具曝光给AI SDK,如Vercel AI,OpenAI,Anthropic,和LangChain.js.

## 安装

```bash
pnpm add @civic/mcp-client
```

根据您使用的 AI SDK, 同时安装对等依赖 :

```bash
# For Vercel AI SDK
pnpm add ai

# For OpenAI
pnpm add openai

# For Anthropic
pnpm add @anthropic-ai/sdk

# For LangChain.js
pnpm add @langchain/core
```

## 快速启动

### 使用 Vercel AI SDK 软件

```typescript
import { CivicMcpClient } from "@civic/mcp-client";
import { vercelAIAdapter } from "@civic/mcp-client/adapters/vercel-ai";
import { streamText } from "ai";

const client = new CivicMcpClient({
  auth: {
    token: "your-access-token",
  },
});

const tools = await client.getTools(vercelAIAdapter());

const result = streamText({
  model: yourModel,
  messages: [{ role: "user", content: "Search GitHub for civic repos" }],
  tools,
});

// Clean up when done
await client.close();
```

### 带有 OpenAI SDK

```typescript
import { CivicMcpClient } from "@civic/mcp-client";
import { openAIAdapter } from "@civic/mcp-client/adapters/openai";
import OpenAI from "openai";

const client = new CivicMcpClient({
  auth: { token: "your-access-token" },
});

const tools = await client.getTools(openAIAdapter());

const openai = new OpenAI();
const response = await openai.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Search GitHub for civic repos" }],
  tools,
});
```

### 与 Anthropic SDK 游戏

```typescript
import { CivicMcpClient } from "@civic/mcp-client";
import { anthropicAdapter } from "@civic/mcp-client/adapters/anthropic";
import Anthropic from "@anthropic-ai/sdk";

const client = new CivicMcpClient({
  auth: { token: "your-access-token" },
});

const tools = await client.getTools(anthropicAdapter());

const anthropic = new Anthropic();
const message = await anthropic.messages.create({
  model: "claude-3-5-sonnet-20241022",
  messages: [{ role: "user", content: "Search GitHub for civic repos" }],
  tools,
});
```

### 和LangChain.js在一起的电影

返回数组 `DynamicStructuredTool` 任何LangChain的代理商 `langchain` v1 级 `createAgent`兰格拉夫的 `createReactAgent`遗产 `AgentExecutor`,或者n8n的"AI代理"节点.

工具结果默认缩合为单个字符串( MCP) `text` 块加入;非文本块 JSON-stringifed),这是每个模型和代理变量最相容的形状.

```typescript
import { CivicMcpClient } from "@civic/mcp-client";
import { langchainAdapter } from "@civic/mcp-client/adapters/langchain";
import { ChatOpenAI } from "@langchain/openai";
import { createReactAgent } from "@langchain/langgraph/prebuilt";

const client = new CivicMcpClient({
  auth: { token: "your-access-token" },
});

const tools = await client.getTools(langchainAdapter());

const agent = createReactAgent({
  llm: new ChatOpenAI({ model: "gpt-4o-mini" }),
  tools,
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "Search GitHub for civic repos" }],
});
```

## 特征

-   **议定书版本谈判**:向支持它的服务器说出MCP 2026-07-28,并自动回落到2025-时代的握手状态
-   **会话管理**: 维持持续 MCP会话,在遗留时代服务器上自动重新连接
-   **框架不可知论**: 通过适配器与任何 AI SDK 工作
-   **类型脚本第一**: 完全类型安全和IntelliSense支持
-   **灵活认证**: 支持静态令牌、 自动令牌提供者或自动令牌交换
-   **轻巧**: 没有不必要的依赖, 最小捆绑大小

## API 参考

### `CivicMcpClient`

#### 构造选项

```typescript
interface CivicMcpClientConfig {
  // Hub URL (defaults to "https://app.civic.com/hub/mcp")
  url?: string;

  // Authentication — provide either a token directly or use token exchange
  auth:
    | { token: string | (() => Promise<string>) }
    | { tokenExchange: TokenExchangeConfig };

  // Scope requests to a specific profile (UUID)
  civicProfile?: string;  // Sent as x-civic-profile-id header

  // Optional custom headers
  headers?: Record<string, string>;

  // Optional connection options
  reconnection?: {
    maxRetries?: number;
    initialReconnectionDelay?: number;
    maxReconnectionDelay?: number;
    reconnectionDelayGrowFactor?: number;
  };

  // Protocol version negotiation (default: "auto")
  // "auto": probe with server/discover, fall back to initialize on legacy servers
  // "legacy": always run the 2025-era initialize handshake
  // { pin: "2026-07-28" }: require exactly that revision, fail otherwise
  versionNegotiation?: "auto" | "legacy" | { pin: string };
}

interface TokenExchangeConfig {
  clientId: string;       // Civic Auth Client ID
  clientSecret: string;   // Civic Auth Client Secret
  subjectToken: string | (() => Promise<string>); // External IdP token
  authUrl?: string;       // Token endpoint (default: "https://auth.civic.com/oauth/token")
  expiresIn?: number;     // Requested token lifetime in seconds (server default if omitted)
  lockToProfile?: boolean; // Lock exchanged token to civicProfile (default: true)
}
```

#### 方法

-   `getTools<T>(adapter?: ToolAdapter<T>): Promise<T>` - 获取工具,可选地适用于特定的AI SDK
-   `getServerInstructions(): Promise<string>` - 获取服务器指令以便系统迅速
-   `callTool(name: string, args: unknown): Promise<CallToolResult>` - 直接调用工具
-   `getAccessToken(): string | undefined` - 获取当前缓存的 Civil Auth 访问令牌( 仅保存交换)
-   `close(): Promise<void>` - 关闭连接

## 高级使用

### 议定书版本谈判

默认情况下,客户端会用 `server/discover` 并使用协议修订 2026-07-28 当服务器提供它。 只讲2025年代协议的服务器获得经典 `initialize` 握个手,这样一来就对了 连接后, `getProtocolEra()` 谈判的时代:

```typescript
await client.connect();
client.getProtocolEra(); // "modern" (2026-07-28+) or "legacy" (2025-era)
```

会话标识和 `onInitialized` 仅适用于遗留时代的连接; 现代服务器不发布会话.

### 缓存客户端实例

图书馆不包含缓存逻辑 - 你自己管理 CivilMcpclient 例:

```typescript
// Simple in-memory cache
const clientCache = new Map<string, CivicMcpClient>();

function getCivicMcpClient(userId: string): CivicMcpClient {
  let client = clientCache.get(userId);
  if (!client) {
    client = new CivicMcpClient({ /* config */ });
    clientCache.set(userId, client);
  }
  return client;
}
```

### 配置范围

```typescript
const client = new CivicMcpClient({
  auth: { token: accessToken },
  civicProfile: "7c9e6679-7425-40de-944b-e07fc1f90ae7",
});
```

### 动态托肯刷新

```typescript
const client = new CivicMcpClient({
  auth: {
    token: async () => {
      const session = await getSession();
      return session.accessToken;
    },
  },
});
```

### Token交易所(RFC 8693)

> **仅限服务器侧.** 托肯交换需要 `clientSecret`,它绝不能在浏览器/客户端代码中被曝光。 仅使用 `tokenExchange` 在服务器侧环境(Node.js,无服务器功能等)中.

如果您的应用程序使用自己的身份提供者(Google, Auth0等),客户端可以自动交换外部的Civil Auth访问令牌. 交换的令牌被缓存并被重新交换,在到期或外部令牌改变时.

```typescript
const client = new CivicMcpClient({
  auth: {
    tokenExchange: {
      clientId: process.env.CIVIC_CLIENT_ID,
      clientSecret: process.env.CIVIC_CLIENT_SECRET,
      subjectToken: () => getGoogleAccessToken(user),
    },
  },
  civicProfile: "550e8400-e29b-41d4-a716-446655440000", // optional: scope to a specific profile
});

// Token exchange happens automatically on first use.
// The exchanged token is locked to the civicProfile by default.
const tools = await client.getTools(vercelAIAdapter());
```

设置指令(创建组织、连接客户端标识和配置符号交换),请参见 [公民签名交换指南](https://docs.civic.com/civic/developers/native-integration/authorization#option-b%3A-token-exchange)。 。 。 .

## 从1.x升级

版本 2 互换基础 SDK 从 `@modelcontextprotocol/sdk` v1 改为 `@modelcontextprotocol/client` v2. 对大多数消费者来说,没有什么变化: `CivicMcpClient` API和适配器相同,客户端自动与中枢谈判协议版本.

需要检查的东西 :

-   **节点.js 22+** 需要时间.
-   **`CallToolResult` 财务报告和审定财务报表 `ListToolsResult`** 现在由此软件包定义,而不是从v1 SDK再出口。 它们与MCP的光谱形状相匹配,因此平庸使用不受影响. 如果您把它们传递到v1 SDK 函数上,请在那个边界上投放或者直接导入 SDK 的类型.
-   **V1 SDK不再以中转方式安装.** 如果输入您的代码 `@modelcontextprotocol/sdk` 仅仅因为这个包把它拉进去, 添加到你自己的依赖.
-   **会话恢复** 仅适用于遗留时代的连接。 2026-07-28服务器上没有会话,所以 `onInitialized` 不开火 `getSessionId()` 返回时 `undefined`。 。 。 .

见 [变动情况](https://npmcn.com/package/%40civic/mcp-client/CHANGELOG.md) 完整名单.

## 许可证

麻省理工学院

## 常见问题

### @civic/mcp-client 是什么？

TypeScript 客户端库,用于连接 Civil Hub 和向 AI SDK 曝光 MCP 工具

### 如何安装 @civic/mcp-client？

在项目目录运行 npm install @civic/mcp-client，或使用 pnpm add / yarn add / bun add。

### @civic/mcp-client 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @civic/mcp-client 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @civic/mcp-client 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @civic/mcp-client 可以商用吗？

@civic/mcp-client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @civic/mcp-client 的下载量有多少？

根据 npm 官方下载统计，@civic/mcp-client 在 2026/10/10 – 2026/11/08 这 30 天内被下载 4,419 次，日均约 147 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @civic/mcp-client 还在维护吗？

最新版本 2\.0\.0 发布于 2026/10/09（1 个月前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/03/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。