Swapi MCP Server

SWAPI MCP服务器

一个模型上下文协议（MCP）服务器，它封装了 星球大战API（SWAPI） 作为MCP工具，允许LLM和客户搜索《星球大战》中的角色、行星和电影。

特性

• 符合MCP标准的服务器 使用官方的TypeScript SDK
• 显示三个工具：

- search_character：按名称搜索《星球大战》角色 - get_planet：通过ID获取详细的行星信息 - get_film：通过ID获取详细的电影信息

• 支持HTTP（无状态、可流式传输）和stdio传输

编码结构

• index.ts：主要入口点。设置MCP服务器，注册工具，并配置HTTP和stdio传输。
• test-client/：示例OpenAI客户端，演示如何从LLM调用MCP服务器作为工具。

工具详细信息

搜索字符

• 输入： { name: string }
• 说明： 在SWAPI中搜索与给定名称匹配的字符。
• 退货： JSON格式的匹配字符列表。

get_planet

• 输入： { id: string }
• 说明： 通过SWAPI ID获取行星的详细信息。
• 退货： JSON格式的行星详细信息。

get_film

• 输入： { id: string }
• 说明： 通过SWAPI ID获取电影的详细信息。
• 退货： JSON格式的电影细节。

运作原理

• 使用 @模型上下文协议/sdk 以创建MCP服务器。
• 每个工具都注册了一个输入模式（使用 动物圈)以及一个从SWAPI获取数据的异步处理程序。
• 可以通过HTTP POST请求访问服务器 /mcp 或通过stdio（用于CLI客户端）。

运行服务器

先决条件

• Node.js v18或更新版本
• npm

安装依赖项

npm install

在HTTP模式下运行（默认）

npx ts-node index.ts

• 服务器将监听 http://localhost:3000/mcp （或设置在 PORT 环境变量）。

在stdio模式下运行（适用于CLI客户端）

• 服务器会自动为基于CLI的MCP客户端启动stdio传输。

HTTP请求示例

列出工具：

curl -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":0,"method":"tools/list","params":{}}'

搜索字符：

curl -N -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "search_character",
      "arguments": { "name": "Luke" }
    },
    "id": 1
  }'

通过ID获取行星：

curl -N -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_planet",
      "arguments": { "id": "1" }
    },
    "id": 2
  }'

按ID获取电影：

curl -N -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_film",
      "arguments": { "id": "1" }
    },
    "id": 3
  }'

测试客户端：OpenAI+MCP集成

这 test-client/ 目录包含一个示例脚本(swapi-client.ts)这演示了如何从OpenAI LLM（例如GPT-4o-mini）调用MCP服务器作为工具。

运作原理

• 使用OpenAI SDK和MCP工具集成。
• 将MCP服务器注册为LLM的工具。
• 向LLM发送提示/问题，LLM可以调用MCP工具进行回答。

例子： test-client/swapi-client.ts

// node --loader ts-node/esm ./swapi-client.ts
import 'dotenv/config';
import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! });

const tools = [
  {
    type: "mcp" as const,
    server_label: 'swapi',
    server_url: 'http://localhost:3000/mcp', // this has to be accessible from your LLM
    require_approval: 'never' as const,
  },
];

const resp = await openai.responses.create({
  model: 'gpt-4o-mini',
  tools,
  input: 'Where was Luke Skywalker born and how tall is he?',
});

console.log(resp.output_text);

运行测试客户端

1. 安装依赖项：

   cd test-client
   npm install

1. 在中设置您的OpenAI API密钥 .env 文件：

   OPENAI_API_KEY=sk-...

1. 启动MCP服务器（在父目录中）：

   npx ts-node index.ts

1. 运行测试客户端：

   node --loader ts-node/esm ./swapi-client.ts

• 您应该看到LLM的答案，其中可能包括从SWAPI MCP工具中获取的信息。
• 您还可以指向 server_url 如果您想从外部localhost进行测试，请访问公共ngrok URL。

备注

• 服务器对于HTTP请求是无状态的（没有会话管理）。
• CORS已启用 mcp-session-id 头球
• 有关MCP的更多详细信息，请参阅 TypeScript SDK文档.