使用说明

项目简介

Ithena MCP Governance SDK ('@ithena-one/mcp-governance') 是一个开源的SDK，旨在为基于 Model Context Protocol (MCP) 构建的服务器应用增加关键的治理功能。它构建在 '@modelcontextprotocol/typescript-sdk' 之上，通过插件式的架构，帮助开发者轻松集成身份验证、授权 (RBAC)、凭据管理、审计日志和追踪等企业级特性，从而构建安全、合规且可观测的 MCP 应用。

该 SDK 提供了两种使用方式：开源 SDK 自托管和 Ithena 托管平台（即将推出，需加入候补名单）。您可以选择最适合您需求的方式来增强您的 MCP 服务器。

主要功能点

身份验证 (Identity Resolution): 可插拔的身份解析器 ('IdentityResolver')，用于确定请求的调用者身份。
授权 (Role-Based Access Control, RBAC): 灵活的角色和权限管理系统 ('RoleStore', 'PermissionStore')，控制用户对资源和工具的访问权限。
凭据管理 (Credential Resolution): 安全的凭据注入机制 ('CredentialResolver')，允许处理程序安全地访问所需的密钥和凭据。
审计日志 (Auditing): 全面的审计日志记录 ('AuditLogStore')，满足合规性要求，追踪用户操作。
请求作用域日志 (Request-Scoped Logging): 结构化日志记录 ('Logger')，方便监控和调试。
追踪上下文传播 (Trace Context Propagation): 支持 W3C Trace Context ('TraceContextProvider')，便于分布式追踪。
可配置的治理管道 (Configurable Governance Pipeline): 请求和通知处理流程可定制，易于集成到现有系统。

安装步骤

确保已安装 Node.js 和 npm (或 yarn, pnpm)。

在您的 MCP 服务器项目目录中，使用 npm, yarn 或 pnpm 安装 '@ithena-one/mcp-governance', '@modelcontextprotocol/sdk' 和 'zod'：

npm install @ithena-one/mcp-governance @modelcontextprotocol/sdk zod
# 或使用 yarn
yarn add @ithena-one/mcp-governance @modelcontextprotocol/sdk zod
# 或使用 pnpm
pnpm add @ithena-one/mcp-governance @modelcontextprotocol/sdk zod

服务器配置

MCP 客户端需要配置 MCP 服务器的启动命令 (command) 及其参数 (args) 才能与之建立连接。对于使用 '@ithena-one/mcp-governance' SDK 构建的 MCP 服务器，其核心是您基于 '@modelcontextprotocol/sdk' 实现的服务器应用，SDK 仅作为增强治理能力的中间件。

因此，MCP 客户端的服务器配置与您原有的基于 '@modelcontextprotocol/sdk' 的服务器启动方式基本一致。您需要配置的是如何启动您的 MCP 服务器应用程序，而不是 SDK 本身。

以下是一个通用的 JSON 格式配置示例，您需要根据您的实际服务器应用进行调整：

{
  "serverName": "MyGovernedMCPServer",
  "command": "node",
  "args": [
    "dist/index.js",  //  <--  指向您的服务器应用入口文件 (例如，编译后的 JavaScript 文件)
    "--config",       //  <--  可选：传递配置文件路径的参数
    "config/server-config.json" // <-- 可选：配置文件路径
  ],
  "transport": "stdio" //  <--  通常 MCP 客户端使用 stdio, SSE 或 WebSocket 连接
}

参数注释:

'serverName': MCP 服务器的名称，自定义即可。
'command': 启动服务器应用的命令。通常是 'node' (如果您的服务器是 Node.js 应用)。
'args': 传递给启动命令的参数数组。
- 'dist/index.js': 请替换为您实际的 MCP 服务器应用入口文件路径。这通常是您使用 '@modelcontextprotocol/sdk' 和 '@ithena-one/mcp-governance' SDK 构建的应用的编译输出文件。
- '--config config/server-config.json': 可选。如果您的服务器应用需要配置文件，您可以通过参数传递配置文件路径。参数名称 ('--config') 和文件路径 ('config/server-config.json') 需要根据您的应用实际情况调整。
'transport': MCP 客户端与服务器建立连接的传输协议。常用的有 'stdio', 'sse', 'websocket'，根据您的服务器配置选择。

关键点:

入口文件路径： 'args' 数组中的第一个元素 ('dist/index.js' 示例) 至关重要。请务必将其替换为您实际的服务器应用入口文件路径，确保 MCP 客户端能够正确启动您的服务器。
配置文件参数： 如果您的服务器应用依赖配置文件，请在 'args' 数组中添加相应的参数和配置文件路径。
传输协议： 'transport' 字段需要与您的 MCP 服务器配置的传输协议一致。

基本使用方法

创建一个基于 '@modelcontextprotocol/sdk' 的 MCP 服务器。

引入 '@ithena-one/mcp-governance' SDK，并使用 'GovernedServer' 类包装您的 'Server' 实例。

import { Server } from '@modelcontextprotocol/sdk/server';
import { GovernedServer } from '@ithena-one/mcp-governance';

const baseServer = new Server({ name: 'MyBaseServer', version: '1.0' });
const governedServer = new GovernedServer(baseServer, {
    // 配置 governance options，例如 IdentityResolver, AuditStore 等
    // ...
});

// 注册请求和通知处理程序 (使用 governedServer 而不是 baseServer)
// governedServer.setRequestHandler(...)
// governedServer.setNotificationHandler(...)

// ... 启动服务器 ...

配置 Governance Options： 在 'GovernedServer' 的构造函数中，您可以配置各种治理选项，例如：
- 'identityResolver': 自定义身份解析器实例。
- 'roleStore', 'permissionStore': RBAC 角色和权限存储实例。
- 'credentialResolver': 凭据解析器实例。
- 'auditStore': 审计日志存储实例。
- 'logger': 自定义日志记录器实例。
- 'enableRbac': 启用或禁用 RBAC 功能。
- 'failOnCredentialResolutionError': 配置凭据解析失败时是否终止请求。
- 'auditDeniedRequests', 'auditNotifications': 配置是否审计被拒绝的请求和通知。
- 'derivePermission', 'sanitizeForAudit', 'postAuthorizationHook': 自定义权限派生、审计日志脱敏和后授权钩子函数。
注册处理程序： 使用 'governedServer.setRequestHandler()' 和 'governedServer.setNotificationHandler()' 注册您的请求和通知处理程序，而不是 'baseServer'。

连接和启动服务器： 使用 'governedServer.connect(transport)' 连接到指定的传输协议，并启动服务器。

import { StdioTransport } from '@modelcontextprotocol/sdk/stdio';

const transport = new StdioTransport();
governedServer.connect(transport).then(() => {
    console.log('GovernedServer connected');
});

实现接口： 根据您的需求，实现 SDK 提供的接口，例如 'IdentityResolver', 'RoleStore', 'PermissionStore', 'CredentialResolver', 'AuditLogStore' 和 'Logger'，以便与您的基础设施集成。

请参考仓库中的 'README.md' 和 'docs' 目录下的文档，获取更详细的配置和使用说明。

关键词