mcp2service - MCP代理服务

Model Context Protocol (MCP)代理服务，支持通过多种适配器将工具调用代理到后端服务。

特性

• ✅ 多协议支持: HTTP, GraphQL, gRPC适配器
• ✅ 类型安全: 完整的TypeScript支持，输入参数验证
• ✅ 插件化架构: 动态适配器注册，工厂模式
• ✅ 错误处理: 统一的错误类型和恢复机制
• ✅ 配置验证: 使用Zod进行运行时配置验证
• ✅ 脚手架工具: 快速项目初始化CLI

快速开始

安装

# 作为依赖安装
bun add mcp2service

# 或从源码安装
git clone https://github.com/your-org/mcp2service.git
cd mcp2service
bun install

基本使用

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');

使用脚手架工具

# 初始化新项目
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 接口：

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' };
  }
}

注册到适配器工厂：

import { defaultAdapterFactory } from 'mcp2service';
import { CustomAdapter } from './adapters/custom';

defaultAdapterFactory.registerAdapter('custom', CustomAdapter);

配置验证

所有配置都使用Zod进行验证：

import { mcpOptionsSchema, validate } from 'mcp2service';

// 验证配置
const validatedConfig = validate(mcpOptionsSchema, userConfig, 'MCP配置');

// 创建代理
const proxy = new McpProxy(validatedConfig);

错误处理

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 类

class McpProxy {
  constructor(options: McpOptions);
  start(): Promise<void>;
}

类型定义

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;
}

适配器接口

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

构建

# 开发模式
bun run index.ts

# 构建
bun build index.ts --outdir ./dist

# 测试
bun test

路线图

查看 ROADMAP.md 了解项目开发计划和功能规划。

许可证

MIT

贡献

欢迎提交Issue和Pull Request！

支持

如有问题，请：

1. 查看 文档
2. 提交 Issue
3. 加入 Discussions