proxy-api-mcp 1.0.0

package/.env.example

@@ -0,0 +1,57 @@
+# MCP 服务配置
+MCP_TRANSPORT=http
+MCP_PORT=3000
+MCP_SESSION_TIMEOUT=3600000
+MCP_LOG_LEVEL=info
+MCP_TOOLS_DIR=./tools
+
+# API 工具配置文件路径
+MCP_API_TOOLS_CONFIG=./api-tools.json
+
+# JSON 配置映射（通过预定义的key加载对应的JSON配置文件）
+# 支持多个配置，用逗号分隔，例如：kingdee_basic,kingdee_finance
+# 可用的配置keys：
+#   - kingdee_basic: 金蝶云星空-基础管理（基础资料、消息平台）
+#   - kingdee_finance: 金蝶云星空-财务会计（总账、应收应付、存货核算）
+#   - kingdee_scm: 金蝶云星空-供应链管理（库存、销售、供应商、组织间结算）
+#   - kingdee_manufacture: 金蝶云星空-生产制造（生产管理、车间管理、工程数据）
+#   - kingdee_tax: 金蝶云星空-税务管理（发票管理）
+#   - kingdee_employee: 金蝶云星空-员工服务（人人报销）
+#   - kingdee_all: 金蝶云星空-全部模块
+# 示例：MCP_JSON_CONFIG=kingdee_basic,kingdee_finance
+MCP_JSON_CONFIG=
+
+# API 工具相关环境变量示例
+# 这些变量可以在 api-tools.json 中通过 ${VAR_NAME} 或 ${VAR_NAME:default} 语法使用
+
+# API 基础 URL
+# API_BASE_URL=https://api.example.com
+
+# API 认证 Token
+# API_TOKEN=your_api_token_here
+
+# 自定义 User-Agent
+# USER_AGENT=DefinesysMCP/1.0
+
+# API 超时时间(毫秒)
+# API_TIMEOUT=30000
+
+# JSONPlaceholder API 相关
+# JSONPLACEHOLDER_BASE_URL=https://jsonplaceholder.typicode.com
+
+# 金蝶云星空
+# 域名
+KINGDEE_DOMAIN=
+# 账套ID
+KINGDEE_ACCT_ID=
+# 用户名
+KINGDEE_USERNAME=
+# 应用ID
+KINGDEE_APP_ID=
+# 应用密钥
+KINGDEE_SECRET=
+# 语言ID
+KINGDEE_LCID=
+# 算法
+KINGDEE_ALGORITHM=
+

package/README.md

@@ -0,0 +1,443 @@
+# Definesys MCP Framework
+
+<p align="center">
+  <strong>一个灵活、易用的 MCP (Model Context Protocol) 服务框架</strong>
+</p>
+
+<p align="center">
+  快速将业务接口转换为 MCP 工具,供 LLM 应用调用
+</p>
+
+## 核心特性
+
+- **简化工具扩展** - 声明式工具配置,无需关心 MCP 协议细节
+- **多传输模式** - 支持 Stdio、SSE 和 Streamable HTTP 三种传输模式
+- **JSON 配置驱动** - 通过 JSON 配置文件零代码创建 API 工具
+- **环境变量支持** - 在 JSON 配置中使用环境变量,提升安全性和灵活性
+- **请求预处理器** - 支持在 API 请求发送前进行自定义处理
+- **JSON 配置映射** - 通过简单的 key 加载预定义的配置文件集合
+- **类型安全** - 使用 TypeScript 开发,严格的类型检查
+- **Schema 验证** - 基于 Zod 的输入输出验证
+
+## 安装
+
+### 使用 npx 直接运行 (推荐)
+
+无需安装,直接通过 npx 运行:
+
+```bash
+npx proxy-api-mcp
+```
+
+### 全局安装
+
+```bash
+npm install -g proxy-api-mcp
+proxy-api-mcp
+```
+
+### 本地项目安装
+
+```bash
+npm install proxy-api-mcp
+```
+
+## 快速开始
+
+### 创建一个简单的 MCP 服务
+
+```typescript
+import { McpServer, startHttpServer, ToolConfig } from 'proxy-api-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)
+
+```typescript
+import { McpServer, startStdioServer } from 'proxy-api-mcp';
+
+const server = new McpServer({
+  name: 'my-mcp-server',
+  version: '1.0.0',
+});
+
+server.registerTool(greetTool);
+
+await startStdioServer(server);
+```
+
+## 核心概念
+
+### 工具配置
+
+工具通过声明式配置进行定义:
+
+```typescript
+interface ToolConfig {
+  name: string;              // 工具唯一标识符
+  title?: string;            // 工具的可读标题
+  description: string;       // 工具功能描述
+  inputSchema: object;       // 输入参数的 JSON Schema
+  outputSchema?: object;     // 输出结果的 JSON Schema
+  handler: ToolHandler;      // 工具处理函数
+}
+```
+
+### 传输模式
+
+框架支持三种传输模式:
+
+| 模式 | 场景 | 特点 |
+|------|------|------|
+| **stdio** | 本地进程,IDE 插件 | 零网络配置,最高安全性 |
+| **http** | 远程服务,多客户端 | 支持并发,会话管理 |
+| **sse** | 需要服务端推送 | 向后兼容旧版协议 |
+
+## JSON 配置 API 工具
+
+通过 JSON 配置文件自动生成 MCP 工具,无需编写代码即可调用 RESTful API。
+
+### 基本配置结构
+
+```json
+{
+  "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 配置中使用环境变量占位符:
+
+```json
+{
+  "baseUrl": "${API_BASE_URL}",
+  "headers": {
+    "Authorization": "Bearer ${API_TOKEN}"
+  },
+  "timeout": "${API_TIMEOUT:30000}"
+}
+```
+
+- **基本语法**: `${ENV_VAR_NAME}`
+- **带默认值**: `${ENV_VAR_NAME:default_value}`
+
+### JSON 配置映射
+
+通过环境变量快速加载预定义的配置文件集合:
+
+```bash
+# .env 文件
+MCP_JSON_CONFIG=kingdee_basic,kingdee_finance
+```
+
+可用配置 Keys:
+
+| Key | 说明 |
+|-----|------|
+| `kingdee_basic` | 基础管理 |
+| `kingdee_finance` | 财务会计 |
+| `kingdee_scm` | 供应链管理 |
+| `kingdee_manufacture` | 生产制造 |
+| `kingdee_tax` | 税务管理 |
+| `kingdee_employee` | 员工服务 |
+| `kingdee_all` | 全部模块 |
+
+## 请求预处理器
+
+在 API 请求发送前对请求数据进行自定义处理:
+
+### 创建预处理器
+
+```typescript
+import { type RequestPreprocessor, type RequestData } from 'proxy-api-mcp';
+
+export class MyPreprocessor implements RequestPreprocessor {
+  readonly name = 'my_preprocessor';
+
+  preprocess(requestData: RequestData): RequestData {
+    requestData.headers['X-Custom-Header'] = 'value';
+    return requestData;
+  }
+}
+```
+
+### 注册并使用
+
+```typescript
+import { PreprocessorRegistry } from 'proxy-api-mcp';
+
+PreprocessorRegistry.register(new MyPreprocessor());
+```
+
+在配置中指定预处理器:
+
+```json
+{
+  "name": "my_api",
+  "preprocessor": "my_preprocessor",
+  "method": "GET",
+  "path": "/data"
+}
+```
+
+## 环境变量管理
+
+使用集中式环境变量管理类:
+
+```typescript
+import { env } from './config/env';
+
+// 获取环境变量
+const port = env.get('MCP_PORT');
+const transport = env.get('MCP_TRANSPORT');
+
+// 验证环境变量
+env.validate();
+
+// 判断运行环境
+if (env.isProduction()) {
+  // 生产环境逻辑
+}
+```
+
+## 配置
+
+### 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `MCP_TRANSPORT` | `http` | 传输模式 (stdio/sse/http) |
+| `MCP_PORT` | `3000` | HTTP 端口 |
+| `MCP_SESSION_TIMEOUT` | `3600000` | 会话超时时间(毫秒) |
+| `MCP_LOG_LEVEL` | `info` | 日志级别 (debug/info/warn/error) |
+| `MCP_TOOLS_DIR` | `./tools` | 工具目录路径 |
+| `MCP_API_TOOLS_CONFIG` | `./api-tools.json` | API 工具配置文件路径 |
+| `MCP_JSON_CONFIG` | - | JSON 配置映射 keys (逗号分隔) |
+| `NODE_ENV` | `development` | 运行环境 |
+
+### Claude Desktop 配置
+
+#### HTTP 模式
+
+```json
+{
+  "mcpServers": {
+    "proxy-api-mcp": {
+      "type": "streamableHttp",
+      "url": "http://localhost:3000/mcp",
+      "timeout": 60000
+    }
+  }
+}
+```
+
+#### Stdio 模式
+
+```json
+{
+  "mcpServers": {
+    "proxy-api-mcp": {
+      "command": "node",
+      "args": ["/path/to/proxy-api-mcp/dist/server.js"],
+      "env": {
+        "MCP_TRANSPORT": "stdio"
+      }
+    }
+  }
+}
+```
+
+## 高级用法
+
+### 添加中间件
+
+```typescript
+import { Middleware } from 'proxy-api-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);
+```
+
+### 批量注册工具
+
+```typescript
+server.registerTools([
+  echoTool,
+  calculatorTool,
+]);
+```
+
+## 项目结构
+
+```
+proxy-api-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 工具架构指南](./docs/API_TOOLS_GUIDE.md) - JSON 配置创建 API 工具
+- [环境变量管理指南](./docs/ENV_GUIDE.md) - 环境变量管理类使用
+- [JSON 配置中使用环境变量](./docs/ENV_IN_JSON_GUIDE.md) - 在配置中使用环境变量
+- [请求预处理器指南](./docs/PREPROCESSOR_GUIDE.md) - 自定义请求处理
+- [JSON 配置映射指南](./docs/JSON_CONFIG_MAPPING_GUIDE.md) - 配置映射加载
+- [开发指南](./docs/DEVELOPMENT.md) - 项目开发总结
+- [测试指南](./docs/TESTING.md) - 测试 MCP 服务器
+
+## 常用命令
+
+```bash
+npm run build      # 编译 TypeScript
+npm run dev        # 开发模式运行
+npm start          # 运行编译后的服务
+npm run lint       # 代码检查
+npm test           # 运行测试
+```
+
+## API 参考
+
+### McpServer
+
+```typescript
+class McpServer {
+  constructor(config: ServerConfig);
+  registerTool(config: ToolConfig): void;
+  registerTools(configs: ToolConfig[]): void;
+  getRegistry(): ToolRegistry;
+  getRouter(): ToolRouter;
+  getSessionManager(): SessionManager;
+  close(): Promise<void>;
+}
+```
+
+### PreprocessorRegistry
+
+```typescript
+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
+
+```typescript
+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](https://modelcontextprotocol.io/) - MCP 官方规范
+- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) - MCP TypeScript SDK
+- [Zod](https://github.com/colinhacks/zod) - TypeScript-first schema validation