@flink-app/mcp-插件
将 Flink AI 工具作为一种 MCP 磁共振 因此,MCP客户端——克洛德代码(Claude Code),克洛德桌面(Claude Desktop),Cursor(Cursor),自定义代理商——可以通过HTTP调用.
- 使用 可流取的 HTTP 运输(无状态,负载-平衡器友好),安装在Flink app自己的Express服务器上.
- 工具为 选入 每个工具通过
mcp: true。 。 。 . - 每一次通话都在Flink的请求上下文中运行:认证的用户和权限流入与代理完全相同的工具,工具的宣告性
permissions强制执行.
安装
pnpm add @flink-app/mcp-plugin
使用量
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();
标记要曝光的工具 :
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客户根据它来决定在工具呼叫前 有多少摩擦 说明没有他们,客户必须承担最坏的, 所以,即使是纯洁的检查,每一次通话都会得到批准。 让他们上 Tool 道具与可选择的可读性 title数字 :
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 代码连接
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 | 应用程序认证插件 | 见 认证。 。 。 . |
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 当它描述一个对象时,会发布广告.
插件上下文
ctx.plugins.mcp.listTools(); // McpToolDefinition[] currently exposed
ctx.plugins.mcp.path; // "/mcp"
页:1
- 无国籍人运输:
GET编号 :DELETE终点返回405(没有会话,没有服务器启动的通知). 这是克劳德代码和其他当前客户的期望. - 工具描述成为模型唯一的文档——使其明确论证和副作用.
- 长期运行的工具必须在客户端请求超时内完成.