Star Wars API & MCP server (swapi.build)

SWAPI.build

一个免费、开源的 Star Wars API，提供人物、电影、星球、物种、星际飞船和载具的数据。基于 Quarkus 和 GraalVM 构建，具备即时启动、极低内存占用和开箱即用的高性能。

本项目受到最初的 SWAPI（由 Paul Hallett 创建，由 Juriy Bura 维护）启发，旨在解决 Star Wars API 永不离线的需求。如果你曾因第三方 API 宕机而导致线上演示中断，就会明白本项目存在的意义。

快速开始

前置条件： Java 25 和 Maven（或使用随附的 Maven Wrapper）。

cd swapi-app
./mvnw quarkus:dev

API 和前端将在 http://localhost:5432 上提供服务。

API 端点

基础路径：/api

ID 是各实体 url 字段中的记录 ID（对于电影，1 = A New Hope）。 成功响应返回 200；未知或非数字 ID 返回 404。

GET /api/stats 返回过去 24 小时（?period=24h，按小时）、7 天（默认，按天； 使用 &granularity=hour 按小时统计）或 30 天（?period=30d，按天）的匿名请求计数，按路由（例如 /api/people/{id} 或 /mcp）和分组（REST API、MCP、页面、SEO、其他）统计；同时提供之前同等时间窗口的数据以供比较，并在 performance 中提供按路由和分组统计的服务端响应时间（请求数、平均值、最小值、最大值、标准差，以及以毫秒为单位的近似 p50/p95/p99，不包括网络耗时）。统计时不记录 IP 地址或客户端详情。/stats 页面展示相同的数据，并提供筛选器、趋势图、排名和性能部分。

所有响应均为 JSON。示例：

curl http://localhost:5432/api/people/1

OpenAPI

完整的 API 契约位于 /openapi.json （OpenAPI 3.x，根据代码生成，始终保持同步）。文档页面 根据该契约呈现内容，并为每个端点提供“试用”功能。例如，可使用以下命令生成客户端：

npx @openapitools/openapi-generator-cli generate -i https://swapi.build/openapi.json -g typescript-fetch

MCP 服务

swapi.build 也是一个基于 Streamable HTTP 的远程 MCP 服务。任何 Streamable HTTP 客户端都可以使用：无状态的 2026-07-28 修订版会发送独立完整的请求，较早的修订版则通过 initialize 协商会话——两者由同一端点提供服务。不支持旧版 HTTP+SSE 传输（2024-11-05）。官方提供，只读，无需身份验证：

https://swapi.build/mcp

完整设置指南：swapi.build/docs/mcp

resource 的值为 PEOPLE、FILMS、PLANETS、SPECIES、STARSHIPS、VEHICLES 之一。 Id 是每个实体 url 字段中的记录 id（对于 FILMS，1 = A New Hope）。

缓存： Quarkiverse MCP Server 2.0.0 会在无状态发现和工具列表响应中发送必需的 ttlMs: 0 和 cacheScope: "public" 字段。TTL 为零表示立即过期；未配置正数的有效期。 其缓存提示 适用于发现、列表方法和 resources/read，不适用于 tools/call。 此处的 Star Wars 数据通过工具公开，因此不会启用工具结果缓存，包括 sw_random。REST／边缘缓存是单独的机制。

claude mcp add --transport http swapi-build https://swapi.build/mcp

{
  "mcpServers": {
    "swapi-build": { "type": "http", "url": "https://swapi.build/mcp" }
  }
}

codex mcp add swapi-build --url https://swapi.build/mcp

[mcp_servers.swapi-build]
url = "https://swapi.build/mcp"

{
  "servers": {
    "swapi-build": { "type": "http", "url": "https://swapi.build/mcp" }
  }
}

{
  "mcpServers": {
    "swapi-build": {
      "type": "streamable-http",
      "url": "https://swapi.build/mcp",
      "disabled": false
    }
  }
}

服务在空闲时会缩容至零——如果首次连接尝试失败，请重试一次 （原生二进制会在几十毫秒内启动；平台可能需要更长时间来配置容器；后续调用很快，无论客户端使用无状态还是基于会话的方式）。

浏览器中的 WebMCP（实验性）

网站通过 WebMCP 提供 sw_list、sw_get、sw_search 和 sw_random。 工具名称和参数与远程 MCP 工具一致，包括大写的资源名称。每个浏览器工具都会更新可见的浏览器，并在 JSON 结果中返回完整记录，其中包含 ok、data、resource 和 path。 浏览器结果封装与远程 MCP 传输不同。

请使用启用了 WebMCP 且支持 document.modelContext API 的兼容浏览器。设置与演示指南 介绍了检查器、示例调用和取消行为。API 不可用时，网站仍可正常使用。网站中未嵌入模型 API 密钥或 AI 运行时。JavaScript 由 Quinoa 打包并在浏览器中运行，包括通过 Quarkus 原生可执行文件提供服务时。

客户端示例

• examples/java/langchain4j-mcp-client — 使用自然语言提问；工具来自上文的 MCP 服务，因此此示例未定义任何工具。
• examples/java/quarkus-rest-client — 使用类型化客户端从 Java 调用 REST API。

项目结构

swapi-app/
  src/main/
    java/com/eldermoraes/     # Backend (Quarkus + Jakarta REST)
      film/                   # Film model, service, resource
      people/                 # People model, service, resource
      planet/                 # Planet model, service, resource
      specie/                 # Specie model, service, resource
      starship/               # Starship model, service, resource
      vehicle/                # Vehicle model, service, resource
      mcp/                    # MCP server tools (sw_list, sw_get, sw_random, sw_search)
      SWObject.java           # Base model class
      SWService.java          # Service interface
      ApiResource.java        # Root /api endpoint
      ApplicationPath.java    # Jakarta REST base path (/api)
    resources/
      data/                   # Static JSON data files
      application.properties  # Quarkus configuration
    webui/                    # Frontend (TypeScript + Vite)
      src/
        api.ts                # API client with request management
        main.ts               # SPA router
        pages/                # Page renderers (home, resource, docs, mcp, about, privacy, terms)
        json-highlight.ts     # JSON syntax highlighting for result panels
        style.css             # Site styles
        types.ts              # TypeScript interfaces for API resources
        constants.ts          # Shared resource metadata
        utils.ts              # Shared utilities (escapeHtml)
  src/test/
    java/com/eldermoraes/     # Regression suite (REST contracts, MCP tools, forwarded headers)

每个后端领域（电影、人物、星球等）都遵循相同的模式：

• 模型（例如，Film.java）：带有 @RegisterForReflection 的 POJO，用于支持原生镜像
• 服务（例如，FilmService.java）：启动时从 JSON 加载数据，并缓存在内存中
• 资源（例如，FilmResource.java）：带有 @RunOnVirtualThread 的 Jakarta REST 控制器

构建

cd swapi-app

# Development mode (live reload)
./mvnw quarkus:dev

# Production JAR
./mvnw package
java -jar target/quarkus-app/quarkus-run.jar

# Native executable (requires GraalVM or container build)
./mvnw package -Dnative
./mvnw package -Dnative -Dquarkus.native.container-build=true

前端由 Quinoa 在 Maven 构建期间自动构建并打包。无需单独运行 npm。

部署

应用以原生（GraalVM/Mandrel）可执行文件的形式运行在 Oracle Cloud 上的可自托管服务器中，由 systemd 管理，并运行在 Caddy 后方（通过 Let's Encrypt 提供 TLS）。DNS 由 Cloudflare 管理（仅 DNS 记录指向该服务器）。发布 GitHub Release 会运行 .github/workflows/native-binary.yml：测试套件、构建原生可执行文件并附加到 Release、人工审批，然后通过 SSH 安装到服务器并执行生产环境探测。操作手册见 docs/DEPLOY.md。

技术栈

• 运行时： Java 25 上的 Quarkus 3.33，使用虚拟线程
• MCP 服务： Quarkiverse MCP Server — Streamable HTTP，支持无状态和基于会话的客户端
• 序列化： Jakarta REST + JSON-B
• 原生镜像： 通过 Mandrel 构建器使用 GraalVM
• 前端： TypeScript + Vite，由 Quinoa 提供服务

贡献

我们随时欢迎拉取请求。无论是修复错误、改进文档，还是添加新功能，都欢迎加入，共同打造银河系中最棒的 Star Wars API。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/my-change）
3. 进行更改（并添加测试），然后运行测试套件：cd swapi-app && ./mvnw test
4. 提交并推送
5. 发起 Pull Request

更新日志和发布

发布历史记录见 CHANGELOG.md。带标签的版本位于 Releases 页面。/openapi.json 中提供的版本（info.version）始终是最新发布的版本。 发布流程详见 docs/RELEASE.md。

致谢

• 原版 SWAPI 由 Paul Hallett 创建，现由 Juriy Bura 维护
• Star Wars 数据来自 Wookieepedia 等社区协作来源
• 所有 Star Wars 内容和图片均为 Lucasfilm Ltd. 和 Disney 的财产。本项目与 Lucasfilm 或 Disney 无关，也未获其认可。

许可证

本项目采用 Apache License 2.0 许可。网站还发布了隐私政策和使用条款。