zyw-ai-mcp-host

用于托管和管理 Model Context Protocol (MCP) 的开源库，支持与 OpenAI API 集成。使用该库，您可以轻松地管理多个MCP服务器，将MCP工具转换为OpenAI工具，并让您的项目本身成为一个功能完整的MCP服务器。

功能特点

• 🚀 管理 MCP（Model Context Protocol）服务器
• 🔄 将 MCP 工具转换为 OpenAI 工具
• 🤖 与 OpenAI API 无缝集成
• 📊 流式和非流式响应支持
• 🛠️ GitHub 一键创建 MCP 项目
• ⚙️ 简单易用的配置系统
• 📦 适用于 Next.js 15+ 项目
• 🏠 支持宿主项目作为MCP服务器
• 🔌 自动生成API路由，零配置部署

安装

npm install zyw-ai-mcp-host
# 或
yarn add zyw-ai-mcp-host
# 或
pnpm add zyw-ai-mcp-host

导入库

该库同时使用了命名导出和默认导出，请按照以下方式导入：

ESM 导入方式 (推荐)

// 导入默认对象
import MCP from 'zyw-ai-mcp-host';

// 导入特定组件
import { MCPClient, getConfig } from 'zyw-ai-mcp-host';

// 导入配置模块
import { config } from 'zyw-ai-mcp-host/config';

CommonJS 导入方式

// 导入默认对象和特定组件
const { default: MCP, MCPClient } = require('zyw-ai-mcp-host');

// 导入配置模块
const { config } = require('zyw-ai-mcp-host/config');

服务器端与客户端分离

为了确保 API 密钥安全和正确处理 Node.js 特定功能，本库实现了客户端和服务器端代码分离：

导入方式

• 客户端安全导入：

  import MCP, { MCPClient } from 'zyw-ai-mcp-host';

  这种导入方式适用于浏览器环境，所有服务器端特定功能（如文件系统操作）将被禁用。

• 服务器端功能导入：

  import { ServerTools } from 'zyw-ai-mcp-host/server';

  这种导入方式仅适用于服务器端代码中（如 API 路由），提供文件系统操作、路由设置等服务器端特定功能。

路由设置示例

在 Next.js 项目中，应该在服务器端代码中使用路由设置功能：

// 在服务器端脚本中（例如项目根目录的脚本）
import { ServerTools } from 'zyw-ai-mcp-host/server';

// 为 App Router 设置MCP路由
ServerTools.setupRoutes('./src', {
  apiPath: 'app/api/mcp', 
  usePagesRouter: false
});

// 或者为 Pages Router 设置MCP路由
ServerTools.setupRoutes('./src', {
  apiPath: 'pages/api/mcp',
  usePagesRouter: true
});

注意：不要在客户端组件中导入 zyw-ai-mcp-host/server，这会导致构建错误，因为服务器端模块依赖 Node.js 特定功能。

基本用法

配置库

在使用库之前，首先需要进行配置：

import { config } from 'zyw-ai-mcp-host';

// 设置配置
config({
  openai: {
    apiKey: 'your-openai-api-key',
    baseUrl: 'https://api.openai.com/v1',
    model: 'gpt-4-turbo',
    timeout: 60000,
  },
  mcp: {
    servers: ['https://your-mcp-server.com'],
    cacheExpiry: 3600, // 缓存过期时间（秒）
  },
  // 其他配置选项...
});

使用外部 MCP 服务器

import MCP from 'zyw-ai-mcp-host';

// 添加 MCP 服务器
await MCP.addServer('https://your-mcp-server.com');

// 获取所有服务器
const servers = MCP.getAllServers();

// 使用 MCP 工具进行对话
const result = await MCP.chat([
  { role: 'system', content: '你是一个有用的助手。' },
  { role: 'user', content: '请帮我查询天气。' }
], {
  includeAllTools: true, // 使用所有可用的 MCP 工具
});

console.log(result.content);

宿主项目作为 MCP 服务器

本库的一个强大功能是允许您的项目本身作为一个MCP服务器，提供自定义工具。这样，您可以：

1. 将您项目的现有功能转化为AI可以使用的工具
2. 让您的项目同时作为MCP服务器和MCP客户端
3. 为自己的项目或其他项目提供工具API

创建宿主MCP服务器

import MCP from 'zyw-ai-mcp-host';

// 创建宿主MCP服务器
const hostServer = MCP.createHostServer({
  name: '我的项目MCP服务器',
  description: '提供我的项目功能的MCP服务器',
  version: '1.0.0',
  tags: ['myproject', 'tools'],
  isPublic: true,
  baseUrl: '/api/mcp', // API路由的基础路径
});

注册自定义工具

您可以注册任意数量的自定义工具，每个工具都需要提供：名称、描述、参数定义和处理函数。

// 注册数据库查询工具
hostServer.registerTool({
  name: 'database-query',
  description: '查询数据库并返回结果',
  parameters: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: 'SQL查询语句',
      },
      limit: {
        type: 'number',
        description: '最多返回的记录数',
      },
    },
    required: ['query'],
  },
  handler: async (params) => {
    // 实现您的工具逻辑
    // 例如：连接数据库，执行查询
    const { query, limit = 10 } = params;
    
    // 这里模拟数据库查询
    console.log(`执行查询: ${query}, 限制: ${limit}`);
    
    return {
      results: [
        { id: 1, name: '示例数据1' },
        { id: 2, name: '示例数据2' },
      ],
      count: 2,
      query,
      timestamp: new Date().toISOString(),
    };
  },
});

// 注册文件操作工具
hostServer.registerTool({
  name: 'file-operations',
  description: '执行文件操作',
  parameters: {
    type: 'object',
    properties: {
      operation: {
        type: 'string',
        description: '操作类型: read, write, list',
      },
      path: {
        type: 'string',
        description: '文件或目录路径',
      },
      content: {
        type: 'string',
        description: '写入文件时的内容',
      },
    },
    required: ['operation', 'path'],
  },
  handler: async (params) => {
    // 实现您的文件操作逻辑
    const { operation, path, content } = params;
    
    // 根据操作类型执行不同的逻辑
    switch (operation) {
      case 'read':
        // 读取文件内容...
        return { content: '文件内容...', path };
      case 'write':
        // 写入文件...
        return { success: true, path };
      case 'list':
        // 列出目录内容...
        return { files: ['file1.txt', 'file2.txt'], path };
      default:
        throw new Error(`不支持的操作: ${operation}`);
    }
  },
});

初始化服务器

注册完所有工具后，需要初始化服务器：

// 初始化宿主MCP服务器
await hostServer.initialize();

console.log('宿主MCP服务器已初始化');
console.log('可用工具:', hostServer.getTools().map(t => t.name).join(', '));

设置 MCP 服务器路由

要让宿主项目作为MCP服务器工作，您需要设置API路由。本库提供了简单易用的方法来自动创建所需的路由文件。

一键设置路由文件

最简单的方法是使用setupRoutes函数，自动在您的项目中生成所需的API路由文件：

// 在您的Next.js项目初始化文件中
import MCP from 'zyw-ai-mcp-host';

// 初始化MCP服务器...

// 自动创建路由文件（默认使用App Router）
MCP.setupRoutes(process.cwd());

// 或指定详细选项
MCP.setupRoutes(process.cwd(), {
  apiPath: 'app/api/mcp', // API路由路径
  usePagesRouter: false   // 使用App Router还是Pages Router
});

这将在您的项目中创建以下文件：

App Router 模式 (默认):

• /app/api/mcp/manifest/route.ts
• /app/api/mcp/health/route.ts
• /app/api/mcp/tools/[toolName]/route.ts

Pages Router 模式:

• /pages/api/mcp/manifest.ts
• /pages/api/mcp/health.ts
• /pages/api/mcp/tools/[toolName].ts

手动设置路由

您也可以手动创建路由文件，直接导出我们提供的处理程序：

App Router 模式

// app/api/mcp/manifest/route.ts
import { GET } from 'zyw-ai-mcp-host/routes';
export { GET };

// app/api/mcp/health/route.ts
import { GET } from 'zyw-ai-mcp-host/routes/health';
export { GET };

// app/api/mcp/tools/[toolName]/route.ts
import { POST } from 'zyw-ai-mcp-host/routes/tools';
export { POST };

注意：如果遇到 AsyncLocalStorage accessed in runtime where it is not available 错误，请确保在路由文件中明确指定 Node.js 运行时：

// 在每个路由文件中添加
export const config = {
  runtime: 'nodejs'
};

Pages Router 模式

// pages/api/mcp/manifest.ts
import { handleManifest } from 'zyw-ai-mcp-host/examples/host-server-api-handlers';
export default handleManifest;

// pages/api/mcp/health.ts
import { handleHealth } from 'zyw-ai-mcp-host/examples/host-server-api-handlers';
export default handleHealth;

// pages/api/mcp/tools/[toolName].ts
import { handleToolCall } from 'zyw-ai-mcp-host/examples/host-server-api-handlers';
export default handleToolCall;

访问 MCP 服务器 API

一旦路由设置完成，您可以通过以下URL访问MCP服务器API：

• 清单: http://your-domain.com/api/mcp/manifest
  返回服务器详情和可用工具列表

• 健康检查: http://your-domain.com/api/mcp/health
  返回服务器健康状态

• 工具调用: http://your-domain.com/api/mcp/tools/{toolName}
  POST请求，调用特定工具

完整的集成示例

以下是一个完整的示例，展示如何在Next.js项目中设置宿主MCP服务器：

1. 初始化服务器（app/api/_init.ts）

import MCP, { config } from 'zyw-ai-mcp-host';

// 设置配置
config({
  openai: {
    apiKey: process.env.OPENAI_API_KEY,
    model: 'gpt-4-turbo',
  },
});

// 创建并初始化宿主MCP服务器
export function initMCPServer() {
  // 如果已经初始化，直接返回
  if (MCP.getHostServer()) {
    return MCP.getHostServer();
  }

  // 创建宿主服务器
  const hostServer = MCP.createHostServer({
    name: '我的Next.js项目MCP服务器',
    description: '提供我的项目功能的MCP服务器',
    tags: ['nextjs', 'custom'],
  });

  // 注册工具
  hostServer.registerTool({
    name: 'get-project-info',
    description: '获取项目信息',
    parameters: {
      type: 'object',
      properties: {
        detail: {
          type: 'boolean',
          description: '是否返回详细信息',
        },
      },
      required: [],
    },
    handler: async (params) => {
      return {
        name: '我的Next.js项目',
        version: '1.0.0',
        isDetailMode: params.detail || false,
        features: ['MCP服务器', '自定义工具'],
        timestamp: new Date().toISOString(),
      };
    },
  });

  // 初始化服务器
  hostServer.initialize();
  
  return hostServer;
}

// 确保服务器初始化
initMCPServer();

// 你也可以选择自动创建路由文件
// 注意：这应该只在开发环境或部署过程中执行一次
if (process.env.NODE_ENV === 'development') {
  MCP.setupRoutes(process.cwd());
}

2. 在App Router中使用（app/api/mcp/manifest/route.ts）

import { GET } from 'zyw-ai-mcp-host/routes';
import '../../_init'; // 导入初始化文件，确保MCP服务器已初始化

export { GET };

3. 健康检查路由（app/api/mcp/health/route.ts）

import { GET } from 'zyw-ai-mcp-host/routes/health';
import '../../_init';

export { GET };

4. 工具调用路由（app/api/mcp/tools/[toolName]/route.ts）

import { POST } from 'zyw-ai-mcp-host/routes/tools';
import '../../../_init';

export { POST };

5. 在应用中使用MCP服务器和工具

import MCP from 'zyw-ai-mcp-host';

// 同时使用外部MCP服务器和宿主服务器
async function useMCPTools() {
  // 添加外部MCP服务器
  await MCP.addServer('https://external-mcp-server.com');
  
  // 聊天时同时使用外部和宿主MCP工具
  const result = await MCP.chat([
    { role: 'system', content: '你是一个有用的助手。' },
    { role: 'user', content: '请提供项目信息，并查询天气。' }
  ], {
    includeAllTools: true, // 包括所有可用工具
  });
  
  return result;
}

流式响应

本库支持流式响应，让您的应用可以逐步显示AI回复：

import MCP from 'zyw-ai-mcp-host';

const { stream, messagesPromise } = await MCP.chatStream([
  { role: 'system', content: '你是一个有用的助手。' },
  { role: 'user', content: '请帮我查询天气。' }
], {
  mcpTags: ['weather'], // 使用标记为 'weather' 的 MCP 工具
});

// 处理流式响应
for await (const chunk of stream) {
  console.log(chunk.content);
  // 向前端发送每一块内容
}

// 获取完整的消息记录（包括工具调用）
const messages = await messagesPromise;

创建 MCP 服务器项目

本库还支持通过GitHub一键创建MCP项目：

import { getGitHubClient, config } from 'zyw-ai-mcp-host';

// 设置 GitHub Token
config({
  github: {
    token: 'your-github-token',
    owner: 'your-github-username',
  },
});

// 创建 MCP 项目
const githubClient = getGitHubClient();
const repoUrl = await githubClient.createMCPProject({
  name: 'My MCP Server',
  description: '我的 MCP 服务器示例',
  repoUrl: 'https://github.com/username/my-mcp-server',
  isPublic: true,
  tags: ['example', 'demo'],
  tools: [
    {
      name: 'weather',
      description: '获取指定城市的天气信息',
      parameters: {
        type: 'object',
        properties: {
          city: { type: 'string', description: '城市名称' },
        },
        required: ['city'],
      },
    },
  ],
});

console.log(`MCP 项目已创建: ${repoUrl}`);

完整的配置选项

import { config } from 'zyw-ai-mcp-host';

config({
  // OpenAI 配置
  openai: {
    apiKey: 'your-openai-api-key',
    baseUrl: 'https://api.openai.com/v1',
    model: 'gpt-4-turbo',
    timeout: 60000,
  },
  
  // MCP 服务配置
  mcp: {
    servers: ['https://your-mcp-server.com'],
    defaultServer: 'https://your-default-mcp-server.com',
    cacheExpiry: 3600, // 缓存过期时间（秒）
  },
  
  // GitHub 集成配置
  github: {
    token: 'your-github-token',
    owner: 'your-github-username',
    repo: 'your-repo-name',
    branch: 'main',
  },
  
  // 数据库配置
  database: {
    type: 'postgres', // 'postgres', 'redis', 或 'none'
    url: 'postgresql://user:password@localhost:5432/db',
  },
  
  // 流式传输设置
  streaming: true,
  
  // 缓存设置
  cache: {
    enabled: true,
    ttl: 3600, // 缓存生存时间（秒）
  },
  
  // 日志设置
  logging: {
    level: 'info', // 'debug', 'info', 'warn', 或 'error'
    enabled: true,
  },
});

最佳实践

初始化时机

在服务器端应用中，应该在应用启动时初始化宿主MCP服务器：

// 在Next.js中，可以在一个特定的初始化文件中完成
// 例如 lib/mcp-init.ts 或 app/api/_init.ts
import MCP from 'zyw-ai-mcp-host';

export function initMCPServer() {
  // 初始化代码...
}

// 在服务器启动时执行初始化
if (typeof window === 'undefined') {
  initMCPServer();
}

工具处理函数

工具处理函数应该是异步的，并处理可能的错误：

handler: async (params) => {
  try {
    // 实现您的工具逻辑...
    return { result: '成功的结果' };
  } catch (error) {
    console.error('工具执行失败:', error);
    throw new Error(error instanceof Error ? error.message : '未知错误');
  }
}

路由文件生成

路由文件生成应该在开发环境或部署过程中执行，而不是在每次请求时执行：

// 只在开发环境或部署过程中生成路由文件
if (process.env.GENERATE_ROUTES === 'true') {
  MCP.setupRoutes(process.cwd());
  console.log('MCP路由文件已生成');
}

贡献指南

欢迎贡献代码、报告问题或提出改进建议！

1. Fork 本仓库
2. 创建您的特性分支: git checkout -b feature/amazing-feature
3. 提交您的更改: git commit -m 'Add some amazing feature'
4. 推送到分支: git push origin feature/amazing-feature
5. 提交拉取请求

许可证

本项目采用 MIT 许可证。详情见 LICENSE 文件。

版本更新

v0.1.9

客户端兼容性增强

• 修复了客户端环境中 global is not defined 错误
• 添加了严格的环境检测机制，确保宿主服务器代码只在服务器端执行
• 提高了在混合渲染环境（SSR+CSR）中的稳定性
• 客户端代码导入时不会报错，但会显示适当的警告信息

v0.1.8

宿主服务器全局共享

• 修改了宿主服务器实例存储方式，使用 global 对象而非模块级变量
• 解决了在 Next.js 多路由下宿主服务器实例无法共享的问题
• 确保在多个 API 路由间共享同一个宿主服务器实例
• 改进了在 Next.js 开发模式下的稳定性

v0.1.7

宿主 Prisma 集成

• 添加了与宿主项目 Prisma 实例集成的功能
• 支持通过 config({ prisma: yourPrismaClient }) 设置宿主 Prisma
• 提供了 getHostPrismaClient() 和 hasHostPrismaClient() 方法
• 允许工具处理程序直接访问宿主项目的数据模型

v0.1.6

Next.js 兼容性增强

• 修复了在Next.js项目中出现的AsyncLocalStorage错误
• 为所有API路由添加了正确的运行时配置 runtime: 'nodejs'
• 改进了工具路由错误处理和日志记录
• 优化了路由处理程序的稳定性

v0.1.5

导出配置优化

• 修复了路由导出配置问题，使 import { GET } from 'zyw-ai-mcp-host/routes' 等导入路径正常工作
• 完善了 routes、routes/health 和 routes/tools 的导出配置
• 优化了构建配置，确保所有路由文件正确编译

v0.1.4

客户端/服务器端代码分离

• 修复了在客户端构建时 fs 模块导入错误的问题
• 实现了客户端和服务器端代码的完全分离
• 提供专用的服务器端入口点 zyw-ai-mcp-host/server
• 确保 API 密钥和敏感信息只在服务器端可用
• 改进了类型支持和错误提示

v0.1.3

安全性增强

• 修复了 OpenAI 客户端可能在浏览器环境中暴露 API 密钥的问题
• 添加了环境检测功能，防止在客户端直接调用 OpenAI API

与宿主项目 Prisma 集成

该库支持使用宿主项目的 Prisma 实例，这样可以避免创建额外的数据库连接，并允许库访问宿主项目的数据模型。

配置 Prisma 集成

import { PrismaClient } from '@prisma/client';
import { config } from 'zyw-ai-mcp-host';

// 使用宿主项目的 Prisma 实例
const prisma = new PrismaClient();

// 将 Prisma 实例传递给库
config({
  prisma: prisma,
  // 其他配置...
});

在库中使用 Prisma

在库内部，可以通过以下方式获取宿主项目的 Prisma 实例：

import { getHostPrismaClient, hasHostPrismaClient } from 'zyw-ai-mcp-host';

// 检查是否设置了 Prisma 实例
if (hasHostPrismaClient()) {
  // 获取 Prisma 实例
  const prisma = getHostPrismaClient();
  
  // 使用 Prisma 实例
  const user = await prisma.user.findUnique({
    where: { id: 1 }
  });
}

在工具处理程序中使用 Prisma

您可以在自定义工具的处理程序中使用宿主项目的 Prisma 实例：

import MCP, { getHostPrismaClient } from 'zyw-ai-mcp-host';

const hostServer = MCP.createHostServer({
  name: '我的MCP服务器',
  // 其他配置...
});

// 注册使用 Prisma 的工具
hostServer.registerTool({
  name: 'query-users',
  description: '查询用户信息',
  parameters: {
    type: 'object',
    properties: {
      userId: { type: 'number', description: '用户ID' },
    },
    required: ['userId'],
  },
  handler: async (params) => {
    const prisma = getHostPrismaClient();
    const user = await prisma.user.findUnique({
      where: { id: params.userId }
    });
    return user ? user : { error: '用户不存在' };
  },
});