# mcp2service

**Repository Path**: kingecg/mcp2service

## Basic Information

- **Project Name**: mcp2service
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-24
- **Last Updated**: 2026-01-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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: {
        type: 'object',
        description: '请求参数',
        properties: {
          name:'string:姓名',
          age:{
            type: 'number',
            description: '年龄'
          },
          classes:{
            type: 'array',
            description: '课程列表',
            items: 'string:课程名称'
          }
        }
      },
      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)