Definesys MCP Framework

核心特性

• 简化工具扩展 - 声明式工具配置,无需关心 MCP 协议细节
• 多传输模式 - 支持 Stdio、SSE 和 Streamable HTTP 三种传输模式
• JSON 配置驱动 - 通过 JSON 配置文件零代码创建 API 工具
• 环境变量支持 - 在 JSON 配置中使用环境变量,提升安全性和灵活性
• 请求预处理器 - 支持在 API 请求发送前进行自定义处理
• JSON 配置映射 - 通过简单的 key 加载预定义的配置文件集合
• 类型安全 - 使用 TypeScript 开发,严格的类型检查
• Schema 验证 - 基于 Zod 的输入输出验证

安装

npm install definesys-mcp

快速开始

创建一个简单的 MCP 服务

import { McpServer, startHttpServer, ToolConfig } from 'definesys-mcp';

// 定义工具
const greetTool: ToolConfig = {
  name: 'greet',
  description: 'Greets a person by name',
  inputSchema: {
    type: 'object',
    properties: {
      name: {
        type: 'string',
        description: 'The name of the person to greet',
      },
    },
    required: ['name'],
  },
  handler: async (args) => {
    const name = args.name as string;
    return {
      content: [
        {
          type: 'text',
          text: `Hello, ${name}! Welcome to MCP!`,
        },
      ],
    };
  },
};

// 创建服务器
const server = new McpServer({
  name: 'my-mcp-server',
  version: '1.0.0',
});

// 注册工具
server.registerTool(greetTool);

// 启动 HTTP 服务器
await startHttpServer(server, { port: 3000 });

使用 Stdio 模式 (适用于 Claude Desktop)

import { McpServer, startStdioServer } from 'definesys-mcp';

const server = new McpServer({
  name: 'my-mcp-server',
  version: '1.0.0',
});

server.registerTool(greetTool);

await startStdioServer(server);

核心概念

工具配置

工具通过声明式配置进行定义:

interface ToolConfig {
  name: string;              // 工具唯一标识符
  title?: string;            // 工具的可读标题
  description: string;       // 工具功能描述
  inputSchema: object;       // 输入参数的 JSON Schema
  outputSchema?: object;     // 输出结果的 JSON Schema
  handler: ToolHandler;      // 工具处理函数
}

传输模式

框架支持三种传输模式:

JSON 配置 API 工具

通过 JSON 配置文件自动生成 MCP 工具,无需编写代码即可调用 RESTful API。

基本配置结构

{
  "version": "1.0",
  "globals": {
    "baseUrl": "https://api.example.com",
    "timeout": 30000,
    "headers": {
      "User-Agent": "MyApp/1.0"
    }
  },
  "tools": [
    {
      "name": "get_user",
      "description": "Get user by ID",
      "method": "GET",
      "path": "/users/{userId}",
      "parameters": [
        {
          "name": "userId",
          "in": "path",
          "required": true,
          "type": "integer"
        }
      ]
    }
  ]
}

在配置中使用环境变量

支持在 JSON 配置中使用环境变量占位符:

{
  "baseUrl": "${API_BASE_URL}",
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}"
  },
  "timeout": "${API_TIMEOUT:30000}"
}

• 基本语法: ${ENV_VAR_NAME}
• 带默认值: ${ENV_VAR_NAME:default_value}

JSON 配置映射

通过环境变量快速加载预定义的配置文件集合:

# .env 文件
MCP_JSON_CONFIG=kingdee_basic,kingdee_finance

可用配置 Keys:

请求预处理器

在 API 请求发送前对请求数据进行自定义处理:

创建预处理器

import { type RequestPreprocessor, type RequestData } from 'definesys-mcp';

export class MyPreprocessor implements RequestPreprocessor {
  readonly name = 'my_preprocessor';

  preprocess(requestData: RequestData): RequestData {
    requestData.headers['X-Custom-Header'] = 'value';
    return requestData;
  }
}

注册并使用

import { PreprocessorRegistry } from 'definesys-mcp';

PreprocessorRegistry.register(new MyPreprocessor());

在配置中指定预处理器:

{
  "name": "my_api",
  "preprocessor": "my_preprocessor",
  "method": "GET",
  "path": "/data"
}

环境变量管理

使用集中式环境变量管理类:

import { env } from './config/env';

// 获取环境变量
const port = env.get('MCP_PORT');
const transport = env.get('MCP_TRANSPORT');

// 验证环境变量
env.validate();

// 判断运行环境
if (env.isProduction()) {
  // 生产环境逻辑
}

配置

环境变量

Claude Desktop 配置

HTTP 模式

{
  "mcpServers": {
    "definesys-mcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3000/mcp",
      "timeout": 60000
    }
  }
}

Stdio 模式

{
  "mcpServers": {
    "definesys-mcp": {
      "command": "node",
      "args": ["/path/to/definesys-mcp/dist/server.js"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

高级用法

添加中间件

import { Middleware } from 'definesys-mcp';

const loggingMiddleware: Middleware = async (context, next) => {
  console.log(`Tool called at ${new Date(context.timestamp)}`);
  const result = await next();
  console.log(`Tool completed`);
  return result;
};

server.getRouter().use(loggingMiddleware);

批量注册工具

server.registerTools([
  echoTool,
  calculatorTool,
]);

项目结构

definesys-mcp/
├── src/
│   ├── core/                 # 核心框架
│   │   ├── server.ts        # MCP Server 封装
│   │   ├── registry.ts      # 工具注册器
│   │   ├── router.ts        # 工具路由器
│   │   ├── session.ts       # 会话管理器
│   │   └── transports/      # 传输层实现
│   ├── tools/               # 工具层
│   │   ├── types.ts         # 类型定义
│   │   ├── validator.ts     # Schema 验证器
│   │   ├── api/             # API 工具模块
│   │   │   ├── builder.ts   # API 工具构建器
│   │   │   ├── executor.ts  # API 请求执行器
│   │   │   ├── loader.ts    # API 工具加载器
│   │   │   ├── preprocessor.ts # 预处理器注册表
│   │   │   └── json-config-*.ts # JSON 配置相关
│   │   └── examples/        # 示例工具
│   ├── config/              # 配置管理
│   │   └── env.ts           # 环境变量管理
│   ├── utils/               # 工具函数
│   │   ├── logger.ts        # 日志工具
│   │   ├── errors.ts        # 错误定义
│   │   └── env-replacer.ts  # 环境变量替换
│   └── index.ts             # 框架入口
├── examples/                # 使用示例
└── docs/                    # 文档

文档

• API 工具架构指南 - JSON 配置创建 API 工具
• 环境变量管理指南 - 环境变量管理类使用
• JSON 配置中使用环境变量 - 在配置中使用环境变量
• 请求预处理器指南 - 自定义请求处理
• JSON 配置映射指南 - 配置映射加载
• 开发指南 - 项目开发总结
• 测试指南 - 测试 MCP 服务器

常用命令

npm run build      # 编译 TypeScript
npm run dev        # 开发模式运行
npm start          # 运行编译后的服务
npm run lint       # 代码检查
npm test           # 运行测试

API 参考

McpServer

class McpServer {
  constructor(config: ServerConfig);
  registerTool(config: ToolConfig): void;
  registerTools(configs: ToolConfig[]): void;
  getRegistry(): ToolRegistry;
  getRouter(): ToolRouter;
  getSessionManager(): SessionManager;
  close(): Promise<void>;
}

PreprocessorRegistry

class PreprocessorRegistry {
  static register(preprocessor: RequestPreprocessor): void;
  static registerMany(preprocessors: RequestPreprocessor[]): void;
  static get(name: string): RequestPreprocessor | undefined;
  static has(name: string): boolean;
  static unregister(name: string): boolean;
  static getAll(): string[];
  static clear(): void;
}

EnvManager

class EnvManager {
  get<K extends keyof EnvSchema>(key: K): EnvSchema[K];
  getAll(): EnvSchema;
  has(key: keyof EnvSchema): boolean;
  validate(): void;
  isProduction(): boolean;
  isDevelopment(): boolean;
  isTest(): boolean;
  print(): void;
}

许可证

MIT License

致谢

• Model Context Protocol - MCP 官方规范
• @modelcontextprotocol/sdk - MCP TypeScript SDK
• Zod - TypeScript-first schema validation