MCP Lab

MCP Lab

此仓库是一个个人实验室，我一直在这里使用 TypeScript 摸索 Model Context Protocol SDK（@modelcontextprotocol/sdk）。主要目的是深入了解协议的工作原理、快速测试，并随着我逐渐熟悉这款工具，搭建更贴近实际的用例。

项目结构

.
├── 📂 mcp-server-dummies/   # Primeros pasos usando el SDK de MCP.
├── 📂 mcp-lab-text2sql/     # Caso de uso avanzado: Text-to-SQL sobre una base de datos SQLite.
├── 📂 mcp-client/           # Integración con OpenAI API para su integración con un Server MCP.

🧪 mcp-server-dummies

此项目包含一个基础实现，用于熟悉 MCP SDK。它旨在作为了解该协议的入门项目，适用于简单测试并帮助理解其工作原理（没有复杂功能）。

安装

说明

此项目需要 Node.js >= v20。

cd mcp-server-dummies
npm i

运行

npm run build     # Compila el proyecto con tsc
npm run dev       # Ejecuta el servidor con ts-node

作为调试工具，我们可以使用以下命令启动 MCP Inspector。此工具提供可视化界面，让我们能够更轻松、更直观地测试和调试 MCP 服务。

npm run test

该命令会在 http://localhost:6274 上启动与我们的 MCP 服务关联的 Inspector。

💬 mcp-lab-text2sql

第二个项目实现了一个 Text-to-SQL 系统：可以使用自然语言与 SQLite 数据库聊天。此 MCP 服务会公开必要的工具和资源，使我们的 LLM 能够与数据交互。

安装

说明

此项目需要 Node.js >= v20。

cd mcp-server-dummies
npm i

运行

npm run build     # Compila el proyecto con tsc
npm run dev       # Ejecuta el servidor con ts-node

作为调试工具，我们可以使用以下命令启动 MCP Inspector。此工具提供可视化界面，让我们能够更轻松、更直观地测试和调试 MCP 服务。

npm run test

该命令会在 http://localhost:6274 上启动与我们的 MCP 服务关联的 Inspector。

Claude Desktop

我们可以通过 Claude Desktop 测试 MCP 服务。要关联 MCP 服务，我们需要按如下方式修改 claude_desktop_config.json 文件：

{
    "mcpServers": {
        "mcp-lab-dummies": {
            "command": "node",
            "args": [
                "C://PATH//mcp-lab//mcp-server-dummies//dist//index.js"
            ]
        },
        "mcp-lab-text2sql": {
            "command": "node",
            "args": [
                "C://PATH//mcp-lab//mcp-server-text2sql//dist//index.js"
            ]
        }
    }
}

重要

请记得先在每个项目中运行 npm run build。

Windows 中的 claude_desktop_config.json 位于哪里？➡️ PATH//AppData//Roaming//Claude。

如需了解此配置文件的语法和位置，请参阅官方文档。

与 OpenAI 的兼容性

将 MCP 服务与 OpenAI 配合使用，在处理工具时效果很好。但如果我们想要使用资源，事情就会变得复杂得多。

说明

请注意：可以通过 OpenAI Agents SDK 原生使用 MCP 服务，不过目前该 SDK 仅提供 Python 版本。我这边使用的是 OpenAI TypeScript SDK 和 Responses API 进行测试。

好吧……我有一个 MCP 服务，其中公开了多个可在 Claude Desktop 中使用的工具。到目前为止一切顺利。但现在我想知道：能否在使用 OpenAI API 的 Agent 中使用同一个 MCP 服务？

首先，将 GPT 模型连接到我们的 MCP 服务并不兼容。@modelcontextprotocol 和 OpenAI 对工具的定义不同。这是否意味着无法使用它？也不尽然。我们来构建一个 MCP 客户端来实现这种集成。

重要

此规范兼容 OpenAI TypeScript SDK 4.95.0 版和 @modelcontextprotocol/sdk 1.9.0 版。

我们的 MCP 客户端中 getTools() 函数的返回类型：

import type { Tool } from "@modelcontextprotocol/sdk/types.js";

const mcpTool: Tool = {
  name: "getUser",
  description: "Get a user by ID",
  inputSchema: z.object({
    type: z.literal("object"),
    properties: z.object({
      id: z.string()
    })
  })
}

OpenAI Responses API 使用的工具类型：

OpenAI 文档

import OpenAI from "openai";

// El campo "parameters" es un JSON Schema

const openaiTool: OpenAI.Responses.Tool {
  "type": "function",
  "name": "getUser",
  "description": "Get a user by ID",
  "parameters": {
    "type": "object",
    "properties": {
      "id": { "type": "string" }
    },
    "required": ["id"],
    "additionalProperties": false
  },
  "strict": true
}

限制

在 MCP 服务中配置工具时，使用 Zod 为参数指定类型时，需要注意一些与 OpenAI 不兼容的选项：

所有参数都必须是必填项：

Invalid schema for function 'update-user-goal': In context=(), 'required' is required to be supplied and to be an array including every key in properties.

定义 int() 字段时，不能使用 max() 或 min()：

Invalid schema for function 'update-user-goal': In context=('properties', 'age', 'anyOf', '0'), 'minimum|maximun' is not permitted.

不能使用 default() 设置默认值：

BadRequestError: 400 Invalid schema for function 'update-user-goal': In context=('properties', 'hasPaid', 'anyOf', '0'), 'default' is not permitted.

演示 测试

说明

项目需要 Node.js >= v20 版本。

运行使用 OpenAI 的 LLM Agent 演示。

1. 在 mcp-server-dummies 目录中运行 npm run build，因为我们将使用该 MCP 服务。

2. 在 mcp-client 目录中运行 npm i 安装依赖。

3. 在 mcp-client 目录中使用命令 npm run dev 运行演示。

• 别忘了在 mcp-client 目录中创建 .env 文件，并填入有效的 OpenAI API 密钥：

  OPENAI_API_KEY=<openai_key>
  

📄 许可证

MIT © rperezll