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
安装依赖项```bash
npm install
### 在HTTP模式下运行(默认)```bash
npx ts-node index.ts
- 服务器将监听
http://localhost:3000/mcp(或设置在PORT环境变量)。
在stdio模式下运行(适用于CLI客户端)
- 服务器会自动为基于CLI的MCP客户端启动stdio传输。
HTTP请求示例
列出工具:```bash
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":{}}'
**搜索字符:**```bash
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获取行星:```bash
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获取电影:**```bash
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````typescript
// 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. 安装依赖项:```bash
cd test-client
npm install
- 在中设置您的OpenAI API密钥
.env文件:```env
OPENAI_API_KEY=sk-...
1. 启动MCP服务器(在父目录中):```bash
npx ts-node index.ts
- 运行测试客户端:
bash node --loader ts-node/esm ./swapi-client.ts
- 您应该看到LLM的答案,其中可能包括从SWAPI MCP工具中获取的信息。
- 您还可以指向
server_url如果您想从外部localhost进行测试,请访问公共ngrok URL。
备注
- 服务器对于HTTP请求是无状态的(没有会话管理)。
- CORS已启用
mcp-session-id头球 - 有关MCP的更多详细信息,请参阅 TypeScript SDK文档.
