MCP工具路由器

npm install mcp-tool-router

import { ToolRouter } from 'mcp-tool-router';

const router = new ToolRouter({
  name: 'my-router',
  version: '1.0.0',
  separator: '/',
  conflictResolution: 'prefix',
});

// Register upstream servers with their tools and handlers
router.addServer('github', {
  tools: [
    { name: 'create_issue', description: 'Create a GitHub issue', inputSchema: { type: 'object', properties: { title: { type: 'string' } }, required: ['title'] } },
    { name: 'search', description: 'Search repositories' },
  ],
  handler: async (toolName, args) => {
    // Forward to actual MCP server or implement directly
    return { content: [{ type: 'text', text: `GitHub ${toolName}: ${JSON.stringify(args)}` }] };
  },
});

router.addServer('jira', {
  tools: [
    { name: 'create_ticket', description: 'Create a Jira ticket' },
    { name: 'search', description: 'Search Jira issues' },
  ],
  handler: async (toolName, args) => {
    return { content: [{ type: 'text', text: `Jira ${toolName}: ${JSON.stringify(args)}` }] };
  },
});

// Tools are namespaced automatically:
// github/create_issue, github/search, jira/create_ticket, jira/search
const tools = router.listTools();
console.log(tools.map(t => t.namespacedName));

// Route calls to the correct upstream server
const result = await router.callTool('github/create_issue', { title: 'Bug report' });

// Default: server name is used as prefix
router.addServer('github', { tools, handler });
// Tool exposed as: github/create_issue

// Custom prefix
router.addServer('postgres', { tools, handler }).namespace('pg');
// Tool exposed as: pg/query

// Disable namespacing (use with caution -- collisions possible)
router.addServer('local', { tools, handler }).namespace(null);
// Tool exposed as: my_tool (original name, no prefix)

const dotRouter = new ToolRouter({ separator: '.' });
// Tools: github.create_issue, github.search

const dunderRouter = new ToolRouter({ separator: '__' });
// Tools: github__create_issue, github__search

const colonRouter = new ToolRouter({ separator: '::' });
// Tools: github::create_issue, github::search

// Include only specific tools (glob patterns supported)
router.addServer('github', { tools, handler })
  .include(['create_*', 'search']);

// Exclude dangerous tools
router.addServer('postgres', { tools, handler })
  .exclude(['drop_*', 'truncate_*']);

// Full filter config with predicate function
router.addServer('db', { tools, handler })
  .filter({
    include: ['*'],
    exclude: ['internal_*'],
    predicate: (tool) => !tool.annotations?.destructiveHint,
  });

// Router-level alias: replaces the namespaced name entirely
router.alias('search', 'github/search_repositories');
// "github/search_repositories" is removed, "search" is exposed

// Server-level alias via the builder
router.addServer('github', { tools, handler })
  .alias('find', 'search_repositories');
// "github/search_repositories" is removed, "find" is exposed

// Global middleware: applies to all tool calls
router.use(async (ctx, next) => {
  console.log(`Calling ${ctx.namespacedName} on ${ctx.upstreamName}`);
  const result = await next();
  console.log(`Completed in context of ${ctx.upstreamName}`);
  return result;
});

// Server-specific middleware via the builder
router.addServer('db', { tools, handler })
  .use(async (ctx, next) => {
    if (ctx.toolDefinition.annotations?.destructiveHint) {
      return {
        content: [{ type: 'text', text: 'Denied: destructive operations are blocked' }],
        isError: true,
      };
    }
    return next();
  });

// Short-circuit: return without calling next() to skip the upstream
router.use(async (ctx, next) => {
  if (ctx.namespacedName === 'cached/tool') {
    return { content: [{ type: 'text', text: 'cached result' }] };
  }
  return next();
});

// 'prefix' (default): tools are namespaced; collision on identical qualified names throws
const router = new ToolRouter({ conflictResolution: 'prefix' });

// 'first-wins': the first registered tool keeps the name, duplicates are silently dropped
const router2 = new ToolRouter({ conflictResolution: 'first-wins' });

// 'error': throw CollisionError immediately on any collision
const router3 = new ToolRouter({ conflictResolution: 'error' });

const metrics = router.metrics;

console.log(metrics.totalCalls);    // Total calls across all servers
console.log(metrics.totalErrors);   // Total errors across all servers
console.log(metrics.totalTools);    // Number of tools in the route table
console.log(metrics.uptimeMs);      // Router uptime in milliseconds

// Per-upstream metrics
console.log(metrics.upstreams.github.callCount);
console.log(metrics.upstreams.github.errorCount);
console.log(metrics.upstreams.github.avgLatencyMs);
console.log(metrics.upstreams.github.lastCallAt);

router.on('serverConnected', (e) => console.log(`Connected: ${e.name}`));
router.on('serverDisconnected', (e) => console.log(`Disconnected: ${e.name}`));
router.on('toolCall', (e) => {
  console.log(`Tool: ${e.tool}, Upstream: ${e.upstream}, Duration: ${e.durationMs}ms, Error: ${e.isError}`);
});

// Add servers dynamically
router.addServer('new-server', { tools, handler });

// Remove a server (its tools are removed from the route table)
router.removeServer('old-server');

// Update a server's tool list without removing it
router.updateServerTools('github', [
  { name: 'search' },
  { name: 'create_issue' },
  { name: 'close_issue' },  // newly added
]);

import { createRouter } from 'mcp-tool-router';

const router = createRouter({ name: 'my-router', version: '1.0.0' });

new ToolRouter(options?: RouterOptions)

import { NamespaceManager } from 'mcp-tool-router';

const ns = new NamespaceManager('/', 'prefix');

new NamespaceManager(separator?: string, conflictResolution?: ConflictResolution)

import { ServerRegistry } from 'mcp-tool-router';

const registry = new ServerRegistry();

import { RequestRouter } from 'mcp-tool-router';

const router = new RequestRouter(namespaceManager, serverRegistry);

import { applyFilter } from 'mcp-tool-router';

const filtered = applyFilter(tools, {
  include: ['get_*'],
  exclude: ['get_internal_*'],
  predicate: (tool) => !!tool.description,
});

import { CollisionError } from 'mcp-tool-router';

try {
  ns.addTool('server2', { name: 'search' }, null);
} catch (err) {
  if (err instanceof CollisionError) {
    console.log(err.conflicts);
    // [{ name: 'search', upstreams: ['server1', 'server2'] }]
  }
}

import { ConfigError } from 'mcp-tool-router';

import type {
  ToolDefinition,
  ToolAnnotations,
  ResourceDefinition,
  PromptDefinition,
  PromptArgument,
  ServerConfig,
  RouterOptions,
  ConflictResolution,
  ToolCallRequest,
  ToolCallResponse,
  ToolCallHandler,
  ToolCallContext,
  ToolContent,
  MiddlewareFn,
  FilterConfig,
  AliasConfig,
  UpstreamStatus,
  UpstreamInfo,
  RouterMetrics,
  ToolCallEvent,
  UpstreamEvent,
  RouterEvents,
  RouteEntry,
  UpstreamTransportConfig,
  ReconnectConfig,
  ServerRegistration,
} from 'mcp-tool-router';

type UpstreamTransportConfig =
  | { type: 'stdio'; command: string; args?: string[] }
  | { type: 'http'; url: string }
  | { type: 'sse'; url: string };

const result = await router.callTool('nonexistent/tool', {});
if (result.isError) {
  console.error(result.content[0]); // { type: 'text', text: 'Unknown tool: "nonexistent/tool"' }
}

const result = await router.callTool('github/search', {});
if (result.isError) {
  console.error(result.content[0]); // { type: 'text', text: 'Server "github" is disconnected' }
}

const result = await router.callTool('flaky/operation', {});
if (result.isError) {
  // { type: 'text', text: 'Error calling tool "operation" on server "flaky": Connection timeout' }
}

import { CollisionError } from 'mcp-tool-router';

try {
  router.addServer('server2', { tools: [{ name: 'search' }], handler }).namespace(null);
} catch (err) {
  if (err instanceof CollisionError) {
    console.error(err.message);
    // Tool name collision detected: "search" is exposed by both upstream "server1" and upstream "server2"
    console.error(err.conflicts);
  }
}

router.addServer('github', { tools: [], handler });
router.addServer('github', { tools: [], handler }); // throws: Server "github" is already registered

import { ToolRouter } from 'mcp-tool-router';

const router = new ToolRouter({
  name: 'enterprise-router',
  version: '2.0.0',
  separator: '/',
});

// GitHub: expose only read operations
router.addServer('github', {
  tools: [
    { name: 'create_issue', description: 'Create issue', annotations: { readOnlyHint: false } },
    { name: 'search', description: 'Search repos', annotations: { readOnlyHint: true } },
    { name: 'get_repo', description: 'Get repo info', annotations: { readOnlyHint: true } },
    { name: 'delete_repo', description: 'Delete repo', annotations: { destructiveHint: true } },
  ],
  handler: githubHandler,
}).filter({
  predicate: (tool) => !tool.annotations?.destructiveHint,
}).namespace('gh');

// Postgres: hide dangerous DDL operations
router.addServer('postgres', {
  tools: [
    { name: 'query', description: 'Run SQL query' },
    { name: 'list_tables', description: 'List tables' },
    { name: 'drop_table', description: 'Drop table' },
    { name: 'truncate_table', description: 'Truncate table' },
  ],
  handler: pgHandler,
}).exclude(['drop_*', 'truncate_*']).namespace('pg');

// Slack: expose everything, add a short alias
router.addServer('slack', {
  tools: [
    { name: 'send_message', description: 'Send a message' },
    { name: 'list_channels', description: 'List channels' },
  ],
  handler: slackHandler,
});

// Router-level alias for convenience
router.alias('send', 'slack/send_message');

// Final tool list:
// gh/create_issue, gh/search, gh/get_repo, pg/query, pg/list_tables,
// slack/list_channels, send

router.use(async (ctx, next) => {
  if (ctx.toolDefinition.annotations?.destructiveHint) {
    return {
      content: [{ type: 'text', text: 'Access denied: destructive operations are not allowed' }],
      isError: true,
    };
  }
  return next();
});

router.use(async (ctx, next) => {
  const start = Date.now();
  console.log(`[AUDIT] Calling ${ctx.namespacedName} on ${ctx.upstreamName}`);

  const result = await next();

  console.log(`[AUDIT] ${ctx.namespacedName} completed in ${Date.now() - start}ms, error=${!!result.isError}`);
  return result;
});

// Add input validation middleware only to the database server
router.addServer('db', { tools, handler })
  .use(async (ctx, next) => {
    // Inject a read-only flag for safety
    if (!ctx.arguments.readOnly) {
      ctx.arguments.readOnly = true;
    }
    return next();
  });

router.use(async (ctx, next) => {
  const result = await next();
  // Redact sensitive data from all responses
  return {
    ...result,
    content: result.content.map(c =>
      c.type === 'text'
        ? { ...c, text: c.text.replace(/\b\d{3}-\d{2}-\d{4}\b/g, '***-**-****') }
        : c
    ),
  };
});

const router = new ToolRouter({ name: 'monitored-router' });

router.on('serverConnected', ({ name }) => {
  console.log(`[EVENT] Server connected: ${name}`);
});

router.on('serverDisconnected', ({ name }) => {
  console.log(`[EVENT] Server disconnected: ${name}`);
});

router.on('toolCall', (event) => {
  if (event.isError) {
    console.error(`[ERROR] ${event.tool} on ${event.upstream}: ${event.errorMessage}`);
  }
});

// Periodic metrics reporting
setInterval(() => {
  const m = router.metrics;
  console.log(`[METRICS] Tools: ${m.totalTools}, Calls: ${m.totalCalls}, Errors: ${m.totalErrors}, Uptime: ${m.uptimeMs}ms`);
  for (const [name, info] of Object.entries(m.upstreams)) {
    console.log(`  ${name}: calls=${info.callCount}, errors=${info.errorCount}, avg=${info.avgLatencyMs.toFixed(1)}ms`);
  }
}, 60_000);

const router = new ToolRouter({ name: 'managed-router' });

// Register servers
router.addServer('github', { tools: githubTools, handler: githubHandler });
router.addServer('slack', { tools: slackTools, handler: slackHandler });

// Start the router
await router.start();

// ... use the router ...

// Dynamically add a new server
router.addServer('jira', { tools: jiraTools, handler: jiraHandler });

// Dynamically update tools when upstream changes
router.updateServerTools('github', updatedGithubTools);

// Remove a server
router.removeServer('slack');

// Stop and clean up
await router.stop();

import { ToolRouter, createRouter, NamespaceManager, ServerRegistry, RequestRouter, applyFilter, CollisionError, ConfigError } from 'mcp-tool-router';

import type {
  ToolDefinition,
  ToolAnnotations,
  ResourceDefinition,
  PromptDefinition,
  PromptArgument,
  ServerConfig,
  RouterOptions,
  ConflictResolution,
  ToolCallRequest,
  ToolCallResponse,
  ToolCallHandler,
  ToolCallContext,
  ToolContent,
  MiddlewareFn,
  FilterConfig,
  AliasConfig,
  UpstreamStatus,
  UpstreamInfo,
  RouterMetrics,
  ToolCallEvent,
  UpstreamEvent,
  RouterEvents,
  RouteEntry,
  UpstreamTransportConfig,
  ReconnectConfig,
  ServerRegistration,
} from 'mcp-tool-router';