mcp2service 1.0.0

package/README.md

@@ -0,0 +1,272 @@
+# mcp2service - MCP代理服务
+
+Model Context Protocol (MCP)代理服务，支持通过多种适配器将工具调用代理到后端服务。
+
+## 特性
+
+- ✅ **多协议支持**: HTTP, GraphQL, gRPC适配器
+- ✅ **类型安全**: 完整的TypeScript支持，输入参数验证
+- ✅ **插件化架构**: 动态适配器注册，工厂模式
+- ✅ **错误处理**: 统一的错误类型和恢复机制
+- ✅ **配置验证**: 使用Zod进行运行时配置验证
+- ✅ **脚手架工具**: 快速项目初始化CLI
+
+## 快速开始
+
+### 安装
+
+```bash
+# 作为依赖安装
+bun add mcp2service
+
+# 或从源码安装
+git clone https://github.com/your-org/mcp2service.git
+cd mcp2service
+bun install
+```
+
+### 基本使用
+
+```typescript
+import { McpProxy } from 'mcp2service';
+
+const proxy = new McpProxy({
+  name: 'my-mcp-service',
+  version: '1.0.0',
+  transport: {
+    httpStream: {
+      port: 3000,
+    },
+  },
+  tools: {
+    'http-example': {
+      type: 'http',
+      description: '示例HTTP工具',
+      params: {},
+      options: {
+        url: 'https://api.example.com/data',
+        method: 'GET',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      },
+    },
+    'graphql-example': {
+      type: 'graphql',
+      description: '示例GraphQL查询',
+      params: {
+        query: {
+          type: 'string',
+          description: 'GraphQL查询语句',
+        },
+      },
+      options: {
+        endpoint: 'https://api.example.com/graphql',
+        headers: {
+          Authorization: 'Bearer ${TOKEN}',
+        },
+      },
+    },
+  },
+});
+
+await proxy.start();
+console.log('MCP代理服务已启动，端口: 3000');
+```
+
+### 使用脚手架工具
+
+```bash
+# 初始化新项目
+bun run cli.ts init my-mcp-project
+
+# 或直接使用（安装后）
+mcp2service init my-mcp-project
+
+# 生成适配器模板
+mcp2service generate:adapter custom-adapter
+```
+
+## 适配器系统
+
+### 内置适配器
+
+1. **HTTP适配器** (`type: 'http'`)
+   - 支持GET, POST, PUT, DELETE, PATCH方法
+   - 请求/响应头配置
+   - 超时和重试机制
+
+2. **GraphQL适配器** (`type: 'graphql'`)
+   - GraphQL查询执行
+   - 变量和操作名支持
+   - 错误处理
+
+3. **gRPC适配器** (`type: 'grpc'`)
+   - Protocol Buffers支持
+   - 服务和方法发现
+   - 元数据传递
+
+### 自定义适配器
+
+实现 `ServiceAdapter` 接口：
+
+```typescript
+import type { ServiceAdapter } from 'mcp2service';
+
+export class CustomAdapter implements ServiceAdapter {
+  config(options: Record<string, any>): void {
+    // 配置适配器
+  }
+  
+  async call(args: any, context: any): Promise<any> {
+    // 执行工具调用
+    return { result: 'success' };
+  }
+}
+```
+
+注册到适配器工厂：
+
+```typescript
+import { defaultAdapterFactory } from 'mcp2service';
+import { CustomAdapter } from './adapters/custom';
+
+defaultAdapterFactory.registerAdapter('custom', CustomAdapter);
+```
+
+## 配置验证
+
+所有配置都使用Zod进行验证：
+
+```typescript
+import { mcpOptionsSchema, validate } from 'mcp2service';
+
+// 验证配置
+const validatedConfig = validate(mcpOptionsSchema, userConfig, 'MCP配置');
+
+// 创建代理
+const proxy = new McpProxy(validatedConfig);
+```
+
+## 错误处理
+
+```typescript
+import { 
+  MCPError, 
+  ValidationError, 
+  AdapterError,
+  ConfigurationError 
+} from 'mcp2service';
+
+try {
+  await proxy.start();
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.error('配置验证失败:', error.details);
+  } else if (error instanceof AdapterError) {
+    console.error('适配器错误:', error.adapterName);
+  }
+  // 处理其他错误...
+}
+```
+
+## API参考
+
+### McpProxy 类
+
+```typescript
+class McpProxy {
+  constructor(options: McpOptions);
+  start(): Promise<void>;
+}
+```
+
+### 类型定义
+
+```typescript
+interface McpOptions {
+  name: string;
+  version: `${number}.${number}.${number}`;
+  transport: TransportOptions;
+  tools: Record<string, ToolDefine>;
+  headers?: string[];
+  authedFn?: AuthenticateFunction;
+}
+
+interface ToolDefine {
+  type: string;
+  description?: string;
+  params: ToolParameters;
+  options: Record<string, any>;
+  execute?: ToolFn;
+}
+```
+
+### 适配器接口
+
+```typescript
+interface ServiceAdapter {
+  config(option: Record<string, any>): void;
+  call: ToolFn;
+}
+
+interface AdapterFactory {
+  createAdapter(type: string, options: Record<string, any>): ServiceAdapter;
+  registerAdapter(type: string, adapterClass: new () => ServiceAdapter): void;
+  getSupportedTypes(): string[];
+}
+```
+
+## 开发
+
+### 项目结构
+
+```
+mcp2service/
+├── src/
+│   ├── mpc-proxy.ts      # MCP代理主类
+│   ├── types.ts          # 类型定义
+│   ├── validation.ts     # 验证逻辑
+│   ├── errors.ts         # 错误类型
+│   └── adapters/         # 适配器实现
+│       ├── http.ts       # HTTP适配器
+│       ├── graphql.ts    # GraphQL适配器
+│       ├── grpc.ts       # gRPC适配器
+│       ├── factory.ts    # 适配器工厂
+│       └── index.ts      # 适配器导出
+├── cli.ts               # 脚手架工具
+├── index.ts            # 主入口点
+└── package.json
+```
+
+### 构建
+
+```bash
+# 开发模式
+bun run index.ts
+
+# 构建
+bun build index.ts --outdir ./dist
+
+# 测试
+bun test
+```
+
+## 路线图
+
+查看 [ROADMAP.md](ROADMAP.md) 了解项目开发计划和功能规划。
+
+## 许可证
+
+MIT
+
+## 贡献
+
+欢迎提交Issue和Pull Request！
+
+## 支持
+
+如有问题，请：
+1. 查看 [文档](https://github.com/your-org/mcp2service/wiki)
+2. 提交 [Issue](https://github.com/your-org/mcp2service/issues)
+3. 加入 [Discussions](https://github.com/your-org/mcp2service/discussions)