Mcp Starwars

用于 SWAPI 星球大战 API 的 MCP 服务。本项目的主要目标是展示如何使用 MCP 服务与 API 交互。

注意：此 MCP 服务使用的所有数据均从 SWAPI 文档](https://swapi.dev)获取。

🔧 功能

• 列出星球大战角色：获取角色数据，支持可选搜索筛选和自动分页
• 列出行星、电影、物种、载具和星际飞船：访问所有星球大战实体集合，并支持搜索
• 按 ID 获取实体详情：获取特定角色、行星、电影、物种、载具或星际飞船的详细信息
• 自动分页：通过一次 API 调用即可无缝获取所有页面的数据
• 内置缓存：通过智能缓存 API 响应来优化性能
• 缓存管理：清除缓存并查看缓存统计信息，以监控性能
• 基于工具的 MCP 集成：将此服务注册到 Model Context Protocol（MCP）工具（VS Code、Claude 等）

🧰 工具

1. get_people 🧑‍🤝‍🧑

• 说明：列出星球大战角色，支持自动分页和可选搜索
• 输入：
  • page（可选，数字）：要获取的页码（默认为 1）
  • search（可选，字符串）：要搜索的名称或部分名称
  • fetchAllPages（可选，布尔值）：是否自动获取所有结果页面（默认为 true）
• 返回：星球大战角色数据集合，包括姓名、身体属性、母星和相关实体

2. get_person_by_id 👤

• 描述：通过 ID 获取特定《星球大战》角色的详细信息
• 输入：
  • id（字符串或数字）：角色的唯一标识符
• 返回：所请求角色的完整数据，包括姓名、身体特征、母星和相关实体

3. get_planets 🪐

• 描述：列出《星球大战》中的行星，支持自动分页和可选搜索
• 输入：
  • page（可选数字）：要获取的页码（默认为 1）
  • search（可选字符串）：要搜索的行星名称或部分名称
  • fetchAllPages（可选布尔值）：是否自动获取所有结果页（默认为 true）
• 返回：《星球大战》行星数据集合，包括气候、地形、人口和相关实体

4. get_planet_by_id 🌍

• 描述：通过 ID 获取特定《星球大战》行星的详细信息
• 输入：
  • id（字符串或数字）：行星的唯一标识符
• 返回：所请求行星的完整数据，包括气候、地形、人口和相关实体

5. get_films 🎬

• 描述：列出《星球大战》电影，支持自动分页和可选搜索
• 输入：
  • page（可选数字）：要获取的页码（默认为 1）
  • search（可选字符串）：要搜索的电影标题或部分标题
  • fetchAllPages（可选布尔值）：是否自动获取所有结果页（默认为 true）
• 返回：《星球大战》电影数据集合，包括标题、集数 ID、导演和相关实体

6. get_film_by_id 📽️

• 描述：通过 ID 获取特定《星球大战》电影的详细信息
• 输入：
  • id（字符串或数字）：电影的唯一标识符
• 返回：所请求电影的完整数据，包括标题、集数 ID、导演和相关实体

7. get_species_list 👽

• 描述：列出《星球大战》中的物种，支持自动分页和可选搜索
• 输入：
  • page（可选数字）：要获取的页码（默认为 1）
  • search（可选字符串）：要搜索的物种名称或部分名称
  • fetchAllPages（可选布尔值）：是否自动获取所有结果页（默认为 true）
• 返回：《星球大战》物种数据集合，包括分类、身体特征和相关实体

8. get_species_by_id 🧬

• 描述：通过 ID 获取特定《星球大战》物种的详细信息
• 输入：
  • id（字符串或数字）：物种的唯一标识符
• 返回：所请求物种的完整数据，包括分类、身体特征和相关实体

9. get_vehicles 🚗

• 描述：列出《星球大战》载具，支持自动分页和可选搜索
• 输入：
  • page（可选数字）：要获取的页码（默认为 1）
  • search（可选字符串）：要搜索的载具名称或部分名称
  • fetchAllPages（可选布尔值）：是否自动获取所有结果页（默认为 true）
• 返回：《星球大战》载具数据集合，包括型号、制造商和规格

10. get_vehicle_by_id 🚙

• 描述：通过 ID 获取特定《星球大战》载具的详细信息
• 输入：
  • id（字符串或数字）：载具的唯一标识符
• 返回：所请求载具的完整数据，包括型号、制造商和规格

11. get_starships 🚀

• 描述：列出《星球大战》星际飞船，支持自动分页和可选搜索
• 输入：
  • page（可选数字）：要获取的页码（默认为 1）
  • search（可选字符串）：要搜索的星际飞船名称或部分名称
  • fetchAllPages（可选布尔值）：是否自动获取所有结果页（默认为 true）
• 返回：《星球大战》星际飞船数据集合，包括型号、制造商和规格

12. get_starship_by_id 🛸

• 描述：根据 ID 获取特定《星球大战》飞船的详细信息
• 输入：
  • id（字符串或数字）：飞船的唯一标识符
• 返回：所请求飞船的完整数据，包括型号、制造商和规格

13. clear_cache 🧹

• 描述：清除《星球大战》API 缓存（部分或全部）
• 输入：
  • endpoint（可选字符串）：要从缓存中清除的特定端点。留空则清除全部。
• 返回：确认已清除哪个缓存的消息

14. get_cache_stats 📊

• 描述：获取《星球大战》API 缓存使用情况的统计信息
• 输入：无
• 返回：缓存命中/未命中统计信息、大小和性能指标

🛠️ 设置

在 VS Code 中快速安装

要快速安装，请点击本 README 顶部的某个 VS Code 安装按钮。

在 VS Code 中手动安装

使用命令行

你可以使用以下命令手动安装《星球大战》MCP 服务：

适用于 VS Code Stable：

code --add-mcp '{"name":"starwars","command":"npx","args":["-y","@johnpapa/mcp-starwars"],"env":{}}'

适用于 VS Code Insiders：

code-insiders --add-mcp '{"name":"starwars","command":"npx","args":["-y","@johnpapa/mcp-starwars"],"env":{}}'

使用 VS Code 设置

1. 打开 VS Code 设置（文件 > 首选项 > 设置）
2. 点击右上角的“打开设置（JSON）”图标
3. 将以下配置添加到 settings.json 文件中：

"mcp": {
  "servers": {
    "starwars": {
      "command": "npx",
      "args": ["-y", "@johnpapa/mcp-starwars"],
      "env": {}
    }
  }
},
"chat.mcp.discovery.enabled": true

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装《星球大战》MCP 服务：

npx -y @smithery/cli install @johnpapa/mcp-starwars --client claude

使用 MCP Inspector 在本地运行 MCP 服务

如果你想在本地运行 MCP Inspector 来测试服务，请按以下步骤操作：

1. 克隆此代码仓库：

   git clone https://github.com/johnpapa/-mcp-starwars
   

2. 安装所需的依赖项并构建项目。

   npm install
   npm run build
   

3. （可选）要使用 MCP Inspector 试用服务，请运行以下命令：

   # Start the MCP Inspector
   npx @modelcontextprotocol/inspector node build/index.js
   

   在浏览器中访问控制台显示的 MCP Inspector URL。将 Arguments 改为 dist/index.js，然后选择 Connect。选择 List Tools 查看可用工具。

在 VS Code Insiders 中运行由 GitHub Copilot 托管的 MCP 服务

注意：如果你已在 Claude Desktop 中启用 MCP 服务，请在 VS Code 设置中添加 chat.mcp.discovery.enabled: true，这样它就会发现已有的 MCP 服务列表。

如果要将 MCP 服务关联到特定代码仓库，请创建 .vscode/mcp.json 文件并添加以下内容：

{
  "inputs": [],
  "servers": {
    "mcp-starwars": {
      "command": "npx",
      // "command": "node",
      "args": [
        "-y",
        "@johnpapa/mcp-starwars"
        // "_git/mcp-starwars/dist/index.js"
      ],
      "env": {}
    }
  }
}

如果要将 MCP 服务关联到所有代码仓库，请将以下内容添加到 VS Code 用户设置 JSON 中：

"mcp": {
  "servers": {
    "mcp-starwars": {
      "command": "npx",
      // "command": "node",
      "args": [
        "-y",
        "@johnpapa/mcp-starwars"
        // "/Users/papa/_git/mcp-starwars/dist/index.js"
        // "_git/mcp-starwars/dist/index.js"
      ],
      "env": {}
    }
  }
}
"chat.mcp.discovery.enabled": true,

在 GitHub Copilot 中使用工具

1. 现在 MCP 服务已可被发现，打开 GitHub Copilot 并选择 Agent 模式（不要选择 Chat 或 Edits）。

2. 点击 Copilot 聊天文本框中的“刷新”按钮，刷新服务列表。

3. 点击“🛠️”按钮，查看所有可用工具，包括此代码仓库中的工具。

4. 在聊天中输入一个自然地会调用某个工具的问题，例如：

   How do I set my VS Code accent colors?
   

   注意：如果你看到“抱歉，Responsible AI Service 已过滤此响应。请重新表述你的提示词并重试。”，请尝试再次运行或重新表述提示词。