mimory-mcp-focusjs

A TypeScript library that provides focus-enforcing wrappers for MCP (Model Context Protocol) clients, enabling fine-grained control over tool access and parameter validation.

Features

• Focus Enforcement: Control which tools can be called and which parameters are allowed
• JWT Integration: Extract focus rules from JWT tokens for secure, token-based access control
• Flexible Configuration: Support for both simple parameter-based and composite focus configurations
• TypeScript Support: Full TypeScript support with comprehensive type definitions
• MCP Compatible: Works seamlessly with base MCP client implementation

Future Work

• Full MCP Coverage: Focus all MCP features including resources, prompts, and more
• Improved Focusing: Better pattern matching for focus enforcement
• Easier JWT Integration: Signed JWTs, even when not used as access tokens, should automatically update the context

Installation

npm install mimory-mcp-focusjs

Quick Start

Using Factory Functions (Recommended)

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
});

Using withFocus (Legacy)

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 Reference

Factory Functions (Recommended)

focusClientSimple()

Creates a focused client using simple parameter-based configuration.

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

Parameters:

• client: The underlying MCP client
• focusTools: Array of allowed tool names (default: ["*"])
• focusParams: Object mapping parameter names to allowed values
• strict: If true, all parameters must be defined in focus rules

focusClientComposite()

Creates a focused client using composite configuration.

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

Parameters:

• client: The underlying MCP client
• focus: Composite focus configuration object
• strict: If true, all parameters must be defined in focus rules

refocusClientSimple()

Updates the focus rules for a simple focused client.

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

refocusClientComposite()

Updates the focus rules for a composite focused client.

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

Core Classes

FocusedClient

The unified focused client class that handles both simple and composite focus types.

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

FocusClient (Legacy)

A wrapper that enforces focus rules on an MCP client using simple parameter-based configuration.

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

Parameters:

• client: The underlying MCP client
• focusTools: Array of allowed tool names (use ["*"] for all tools)
• focusParams: Object mapping parameter names to allowed values
• strict: If true, all parameters must be defined in focus rules

FocusClientComposite (Legacy)

A wrapper that enforces focus rules using a composite configuration object.

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

Parameters:

• client: The underlying MCP client
• focus: Composite focus configuration object
• strict: If true, all parameters must be defined in focus rules

Utility Functions

withFocus()

Convenience function to create a focused client with automatic configuration detection.

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

Utility Functions

checkToolArgsFocus()

Check tool arguments against focus rules.

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

filterToolsFocus()

Filter tools based on focus rules.

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

JWT Integration

extractMCPContextJWT()

Extract focus rules from a JWT token.

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

extractMCPCompositeContextJWT()

Extract composite focus configuration from a JWT token.

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

Type Definitions

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

Focus Rules

Parameter Values

Focus rules support several value types:

• Exact values: "hello", "world"
• Wildcard: "*" (allows any value)
• Ranges: "range:1-100" (allows numeric values in range)
• Arrays: ["value1", "value2"] (allows any of the listed values)

Examples

// 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 Integration Example

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
);

Error Handling

The library throws FocusError for focus-related violations:

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

Examples

See the examples/ directory for complete working examples:

• basic-usage.ts - Basic focus client usage (legacy approach)
• jwt-integration.ts - JWT-based focus extraction
• composite-focus.ts - Composite focus configuration (legacy approach)
• everything-mcp-server.ts - Integration with Everything MCP Server

Development

# Install dependencies
npm install

# Build the library
npm run build

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For support, please open an issue on GitHub.