AI导哈

MCP客户端聚焦库

一个TypeScript库，为MCP客户端提供聚焦强制包装器，实现细粒度的工具访问控制和参数验证。

  • by MimoryInc
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 MimoryInc/mimory-mcp-focusjs

使用说明

mimory-mcp-focusjs 翻译成中文可以是：“记忆-MCP-焦点JS” 或者根据具体上下文，也可以翻译为“记忆模块-MCP-焦点JavaScript”等，以更准确地表达其含义。这里，“mimory”可能是一个特定项目或模块的名称，我将其译为“记忆”是基于一种可能的解释，实际翻译可能需要根据具体语境调整

一个TypeScript库，为MCP（模型上下文协议）客户端提供强制焦点的包装器，实现对工具访问和参数验证的细粒度控制。

特点/特性

  • 重点执法控制可以调用哪些工具以及允许使用哪些参数
  • JWT 集成从JWT令牌中提取焦点规则，以实现基于令牌的安全访问控制
  • 灵活配置支持基于简单参数和复合焦点配置的配置
  • TypeScript 支持全面支持TypeScript，配备完整的类型定义
  • 与MCP兼容与基础MCP客户端实现无缝工作

未来工作

  • 全面MCP覆盖集中所有MCP功能，包括资源、提示等
  • 改进后的对焦功能更精确的模式匹配以强化焦点控制
  • 更便捷的JWT集成已签名的JWT，即使不作为访问令牌使用，也应自动更新上下文

安装

npm install mimory-mcp-focusjs

快速入门

使用工厂函数（推荐）

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { focusClientSimple, focusClientComposite } from "mimory-mcp-focusjs";

// Create your MCP client
const client = new Client(/* your MCP client configuration */);

// Simple focus using factory function
const simpleFocusedClient = focusClientSimple(
  client,
  ["echo", "add"], // focus_tools
  {
    message: ["hello", "world"], // focus_params
    a: ["range:1-100"],
    b: ["range:1-100"]
  },
  false // strict mode
);

// Composite focus using factory function
const compositeFocusedClient = focusClientComposite(
  client,
  {
    "echo": {
      message: ["hello", "world"],
      priority: ["range:1-10"]
    },
    "add": {
      a: ["range:1-100"],
      b: ["range:1-100"]
    }
  },
  false // strict mode
);

// Use the focused clients - they will automatically enforce your rules
const tools = await simpleFocusedClient.listTools(); // Only returns allowed tools
const result = await simpleFocusedClient.callTool({
  name: "add",
  arguments: { a: 5, b: 10 } // Will succeed
});

使用 withFocus（旧版）

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { withFocus } from "mimory-mcp-focusjs";

// Create your MCP client
const client = new Client(/* your MCP client configuration */);

// Apply focus rules
const focusedClient = await withFocus(client, {
  focusTools: ["echo", "add"], // Only allow these tools
  focusParams: {
    message: ["hello", "world"], // Only allow these values for 'message' parameter
    a: ["range:1-100"], // Only allow values between 1-100 for 'a' parameter
    b: ["range:1-100"]
  },
  strict: true // Enforce all parameters must be in focus rules
});

// Use the focused client - it will automatically enforce your rules
const tools = await focusedClient.listTools(); // Only returns allowed tools
const result = await focusedClient.callTool({
  name: "add",
  arguments: { a: 5, b: 10 } // Will succeed
});

API 参考文档

工厂函数（推荐）

focusClientSimple()

使用基于简单参数的配置创建一个专注的客户端。

function focusClientSimple(
  client: Client,
  focusTools?: string[],
  focusParams?: Record<string, string | string[]>,
  strict: boolean = false
): FocusedClient

参数：

  • client底层的MCP客户端
  • focusTools允许使用的工具名称数组（默认： ["*"]）
  • focusParams将对象参数名称映射到允许的值
  • strict如果为真，则所有参数必须在焦点规则中定义

focusClientComposite()

使用复合配置创建一个专注的客户端。

function focusClientComposite(
  client: Client,
  focus?: Record<string, Record<string, string[]>>,
  strict: boolean = false
): FocusedClient

参数：

  • client底层的MCP客户端
  • focus复合焦点配置对象
  • strict如果为真，则所有参数必须在焦点规则中定义

refocusClientSimple()

更新简单聚焦客户端的焦点规则。

function refocusClientSimple(
  client: FocusedClient,
  focusTools: string[],
  focusParams: Record<string, string | string[]>,
  strict: boolean
): void

refocusClientComposite()

更新组合焦点客户端的焦点规则。

function refocusClientComposite(
  client: FocusedClient,
  focus: Record<string, Record<string, string[]>>,
  strict: boolean
): void

核心类

FocusedClient

统一的焦点客户端类，能够处理简单和复合焦点类型。

class FocusedClient {
  constructor(
    client: Client,
    focus: Record<string, any>,
    focusType: string
  )
  
  refocus(focus: Record<string, any>, focusType: string): void
}

FocusClient （遗产）

一个通过简单参数配置来强制MCP客户端遵循焦点规则的封装器。

class FocusClient {
  constructor(
    client: Client,
    focusTools: string[] = ["*"],
    focusParams: Record<string, string[]> = {},
    strict: boolean = false
  )
}

参数：

  • client底层的MCP客户端
  • focusTools允许使用的工具名称数组（使用 ["*"] （适用于所有工具）
  • focusParams将对象映射参数名称到允许的值
  • strict如果为真，则所有参数必须在焦点规则中定义

FocusClientComposite （遗产）

一个使用组合配置对象来强制执行焦点规则的包装器。

class FocusClientComposite {
  constructor(
    client: Client,
    focus: FocusComposite = {},
    strict: boolean = false
  )
}

参数：

  • client底层的MCP客户端
  • focus复合焦点配置对象
  • strict如果为真，则所有参数必须在焦点规则中定义

实用函数

withFocus()

便捷功能，用于创建一个带有自动配置检测的专注客户端。

async function withFocus(
  client: Client,
  opts: {
    focusTools?: string[];
    focusParams?: FocusParams;
    focus?: FocusComposite;
    strict?: boolean;
  }
): Promise<Client>

实用函数

checkToolArgsFocus()

检查工具参数是否符合焦点规则。

function checkToolArgsFocus(
  tool: string,
  args: Record<string, any>,
  focus: any,
  focusType: string
): { isValid: boolean; errorResult?: any }
filterToolsFocus()

基于焦点规则的过滤工具。

function filterToolsFocus(
  tools: any[],
  focus: any,
  focusType: string
): any[]

JWT 集成

extractMCPContextJWT()

从JWT令牌中提取焦点规则。

async function extractMCPContextJWT(
  jwtToken: string,
  jwtKey: string,
  jwtSigningAlgorithm: string,
  parameterField: string = 'context',
  toolField: string = 'tools',
  strict: boolean = false
): Promise<{ contextParams: FocusParams; toolsAllowed: FocusTools }>
extractMCPCompositeContextJWT()

从JWT令牌中提取复合焦点配置。

async function extractMCPCompositeContextJWT(
  jwtToken: string,
  jwtKey: string,
  jwtSigningAlgorithm: string,
  compositeContextField: string
): Promise<FocusComposite>

类型定义

type FocusComposite = Record<string, Record<string, Primitive[] | Primitive>>;
type FocusParams = Record<string, string | string[]>;
type FocusTools = string[];
type Primitive = string | number | boolean;

焦点规则

参数值

焦点规则支持多种值类型：

  • 确切值： "hello"， "world"
  • 通配符: "*" （允许任何值）
  • 范围： "range:1-100" （允许输入范围内的数值）
  • 数组： ["value1", "value2"] （允许列表中的任意值）

示例

// Simple parameter focus
const focusParams = {
  message: ["hello", "world"], // Only allow these exact values
  count: ["range:1-10"], // Allow numbers 1-10
  enabled: ["true", "false"], // Allow boolean strings
  any: "*" // Allow any value
};

// Composite focus
const focusComposite = {
  "echo": { // Specific rules for 'echo' tool
    message: ["hello", "world"],
    priority: ["range:1-5"]
  },
  "add": { // Specific rules for 'add' tool
    a: ["range:1-100"],
    b: ["range:1-100"]
  }
};

JWT 集成示例

import { extractMCPContextJWT, focusClientSimple } from "mimory-mcp-focusjs";

// Extract focus rules from JWT
const { contextParams, toolsAllowed } = await extractMCPContextJWT(
  jwtToken,
  secretKey,
  "HS256",
  "context", // JWT field containing parameters
  "tools"    // JWT field containing allowed tools
);

// Apply the extracted rules using factory function
const focusedClient = focusClientSimple(
  client,
  toolsAllowed,
  contextParams,
  true // strict mode
);

错误处理

图书馆抛出（或：图书馆推出） FocusError 对于与焦点相关的违规行为：

try {
  await focusedClient.callTool({
    name: "unauthorized_tool",
    arguments: { message: "hello" }
  });
} catch (error) {
  if (error instanceof FocusError) {
    console.log("Focus violation:", error.message);
  }
}

示例

查看 examples/ 完整工作示例的目录：

  • basic-usage.ts - 基础焦点客户端使用（传统方法）
  • jwt-integration.ts 基于JWT的焦点提取
  • composite-focus.ts - 复合焦点配置（传统方法）
  • everything-mcp-server.ts - 与Everything MCP服务器的集成

发展

# Install dependencies
npm install

# Build the library
npm run build

许可证

麻省理工学院（MIT）

贡献

欢迎贡献！请随时提交拉取请求。

支持

如需支持，请在此提交问题 GitHub。

相关 MCP