# @flink-app/mcp-plugin 中文文档

规范地址：https://npmcn.com/package/%40flink-app/mcp-plugin/

版本：2\.0\.0-alpha\.134
npm 元数据更新时间：2026-11-07T11:33:19.758Z
中文译文更新时间：2026-11-15T03:30:25.908Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40flink-app/mcp-plugin
原文对照：https://npmcn.com/package/%40flink-app/mcp-plugin/?lang=original

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

- 包体积（解压后）：30.7 kB，10 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@flink-app/flink \>=2\.0\.0-alpha\.134
- 首次发布：2026-08-26T18:15:20.456Z
- 最新版本发布：2026-11-07T11:30:12.556Z
- 近 30 天下载量：2185（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

通过可流取的 HTTP 显示 Flink AI 工具的 Flink 插件

## 安装

```sh
npm install @flink-app/mcp-plugin
```

也可以使用：`pnpm add @flink-app/mcp-plugin`、`yarn add @flink-app/mcp-plugin`、`bun add @flink-app/mcp-plugin`

## README

# @flink-app/mcp-插件

将 Flink AI 工具作为一种 [MCP 磁共振](https://modelcontextprotocol.io/) 因此,MCP客户端——克洛德代码(Claude Code),克洛德桌面(Claude Desktop),Cursor(Cursor),自定义代理商——可以通过HTTP调用.

-   使用 **可流取的 HTTP** 运输(无状态,负载-平衡器友好),安装在Flink app自己的Express服务器上.
-   工具为 **选入** 每个工具通过 `mcp: true`。 。 。 .
-   每一次通话都在Flink的请求上下文中运行:认证的用户和权限流入与代理完全相同的工具,工具的宣告性 `permissions` 强制执行.

## 安装

```bash
pnpm add @flink-app/mcp-plugin
```

## 使用量

```typescript
import { FlinkApp } from "@flink-app/flink";
import { mcpPlugin } from "@flink-app/mcp-plugin";

const app = await new FlinkApp<AppCtx>({
    name: "My app",
    auth: jwtAuthPlugin({ ... }),
    plugins: [
        mcpPlugin({
            instructions: "Tools for looking up cars in the demo inventory.",
        }),
    ],
}).start();
```

标记要曝光的工具 :

```typescript
export const Tool: FlinkToolProps = {
    id: "search-cars-by-brand",
    description: "Search for cars by brand name.",
    inputSchema: z.object({ brand: z.string() }),
    permissions: ["car:read"],
    mcp: true, // 👈 visible over MCP
};
```

没有工具 `mcp: true` 留在你的特工内部.

### 标题和说明

MCP客户根据它来决定在工具呼叫前 有多少摩擦 [说明](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-annotations)没有他们,客户必须承担最坏的, 所以,即使是纯洁的检查,每一次通话都会得到批准。 让他们上 `Tool` 道具与可选择的可读性 `title`数字 :

```typescript
export const Tool: FlinkToolProps = {
    id: "get-order-outcome",
    title: "Order outcome",
    description: "Returns what was done with an order. Read-only.",
    mcp: true,
    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
};
```

| 提示 | 含义 | MCP 默认 |
| --- | --- | --- |
| `readOnlyHint` | 该工具不会改变其环境. | `false` |
| `destructiveHint` | 该工具可能进行破坏性更新(删除,覆盖). | `true` (不只读时) |
| `idempotentHint` | 重复使用同样论点的电话没有附加效果. | `false` |
| `openWorldHint` | 该工具与外部实体(web,第三方API)交互. | `true` |

两个字段都通过 `tools/list` 未设置时作为正则并省略。 提示是建议: Flink 不执行它们, 所以一个工具标记 `readOnlyHint: true` 写作是作者的问题,如MCP谱. 特工们忽略了这两个领域.

## 从 Claude 代码连接

```bash
claude mcp add --transport http my-flink-app https://api.example.com/mcp \
  --header "Authorization: Bearer <token>"
```

## 选项

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `path` | `/mcp` | 端点路径 . |
| `name` | 应用程序名称 | 服务器名称向客户端报告 . |
| `version` | `1.0.0` | 服务器版本向客户端报告. |
| `instructions` | —— 说 | 在初始化时发送给客户端的简短描述,用工具列表显示给模型. |
| `auth` | 应用程序认证插件 | 见 [认证](https://npmcn.com/package/%40flink-app/mcp-plugin/#readme-authentication)。 。 。 . |
| `filter` | `tool.mcp === true` | 自定义规则 哪些工具可以曝光 。 替换默认值. |
| `debug` | `false` | 记录每个工具调用 . |

## 认证

| `auth` 价值 | 行为 |
| --- | --- |
| 删除 | 使用应用程序 `auth` 插件 (e)`authenticateRequest` 不需要权限——有效的符号就够了). 没有认证插件, 端点会打开, 警告会被记录 . |
| `{ permissions: [...] }` | 使用应用程序的认证插件, 并需要这些权限才能到达终点 . |
| `false` | 明确开放,无预警. |
| `async (req, app) => ...` | 自定义。 返回时 `{ user, permissions }`, (中文(简体) ), `false` (401个)或a `FlinkResponse` 以塑造拒绝. |

被拒绝的请求获得 a `401` 与 `WWW-Authenticate: Bearer` (或返回者的状况) `FlinkResponse`。 。 每个工具 `permissions` 总是在顶部执行,使用通过认证解决的权限.

## 如何将工具结果映射到 MCP

| 闪烁 `ToolResult` | MCP 磁共振 `CallToolResult` |
| --- | --- |
| `{ success: true, data: object }` | `content: [text(JSON)]` + 键 `structuredContent: data` |
| `{ success: true, data: primitive }` | `content: [text(data)]` |
| `{ success: false, error, code }` | `isError: true`, (中文(简体) ), `content: [text("CODE: error")]` |
| 扔出 Flink 错误( 例如 ). `forbidden`(中文(简体) ) | `isError: true`, (中文(简体) ), `content: [text("PERMISSION_DENIED: ...")]` |

输入策略来自 `inputSchema` (分区4), `inputJsonSchema`,或者编译器生成的 schema ——与代理器的优先权相同. `outputSchema` 当它描述一个对象时,会发布广告.

## 插件上下文

```typescript
ctx.plugins.mcp.listTools(); // McpToolDefinition[] currently exposed
ctx.plugins.mcp.path;        // "/mcp"
```

## 页:1

-   无国籍人运输: `GET`编号 :`DELETE` 终点返回 `405` (没有会话,没有服务器启动的通知). 这是克劳德代码和其他当前客户的期望.
-   工具描述成为模型唯一的文档——使其明确论证和副作用.
-   长期运行的工具必须在客户端请求超时内完成.

## 常见问题

### @flink-app/mcp-plugin 是什么？

通过可流取的 HTTP 显示 Flink AI 工具的 Flink 插件

### 如何安装 @flink-app/mcp-plugin？

在项目目录运行 npm install @flink-app/mcp-plugin，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@flink-app/flink（\>=2\.0\.0-alpha\.134）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @flink-app/mcp-plugin 支持 TypeScript 吗？

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

### @flink-app/mcp-plugin 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @flink-app/mcp-plugin 可以商用吗？

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

### @flink-app/mcp-plugin 的下载量有多少？

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

### @flink-app/mcp-plugin 还在维护吗？

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