{
  "markdown": "# SWAPI.build\n\nA free, open-source Star Wars API serving data about People, Films, Planets, Species, Starships, and Vehicles. Built with [Quarkus](https://quarkus.io/) and [GraalVM](https://www.graalvm.org/) for instant startup, minimal memory footprint, and out-of-the-box performance.\n\nInspired by the original [SWAPI](https://swapi.dev/) (created by Paul Hallett, maintained by Juriy Bura), this project was born out of the need for a Star Wars API that **never goes offline**. If you've ever had a live demo break because a third-party API went down, you know why this exists.\n\n## Quick Start\n\n**Prerequisites:** Java 25 and Maven (or use the included Maven Wrapper).\n\n```bash\ncd swapi-app\n./mvnw quarkus:dev\n```\n\nThe API and frontend will be available at **http://localhost:5432**.\n\n## API Endpoints\n\nBase path: `/api`\n\n| Resource | List All | By ID | Random | Search |\n|----------|----------|-------|--------|--------|\n| People | `GET /api/people` | `GET /api/people/:id` | `GET /api/people/random` | `GET /api/people?search=name` |\n| Films | `GET /api/films` | `GET /api/films/:id` | `GET /api/films/random` | `GET /api/films?search=title` |\n| Planets | `GET /api/planets` | `GET /api/planets/:id` | `GET /api/planets/random` | `GET /api/planets?search=name` |\n| Species | `GET /api/species` | `GET /api/species/:id` | `GET /api/species/random` | `GET /api/species?search=name` |\n| Starships | `GET /api/starships` | `GET /api/starships/:id` | `GET /api/starships/random` | `GET /api/starships?search=name` |\n| Vehicles | `GET /api/vehicles` | `GET /api/vehicles/:id` | `GET /api/vehicles/random` | `GET /api/vehicles?search=name` |\n\nIds are the record ids from each entity's `url` field (for films, `1` = A New Hope).\nSuccessful responses return `200`; unknown or non-numeric ids return `404`.\n\nAll responses are JSON. Example:\n\n```bash\ncurl http://localhost:5432/api/people/1\n```\n\n## OpenAPI\n\nThe full API contract is served at [`/openapi.json`](https://swapi.build/openapi.json)\n(OpenAPI 3.x, generated from the code — always in sync). The\n[documentation page](https://swapi.build/docs) renders from it, including a\n\"try it\" for every endpoint. Generate a client with, e.g.:\n\n    npx @openapitools/openapi-generator-cli generate -i https://swapi.build/openapi.json -g typescript-fetch\n\n## MCP Server\n\nswapi.build is also a remote [MCP](https://modelcontextprotocol.io) server over\n**Streamable HTTP**. Any Streamable HTTP client works: the stateless `2026-07-28`\nrevision sends self-contained requests, and earlier revisions negotiate a session\nthrough `initialize` — both are served on the same endpoint. The legacy HTTP+SSE\ntransport (`2024-11-05`) is not supported. First-party, read-only, no authentication:\n\n```\nhttps://swapi.build/mcp\n```\n\nFull setup guides: **[swapi.build/docs/mcp](https://swapi.build/docs/mcp)**\n\n| Tool | Arguments | Returns |\n|------|-----------|---------|\n| `sw_list` | `resource` | All entities of a resource |\n| `sw_get` | `resource`, `id` | One entity by id |\n| `sw_random` | `resource` | A random entity |\n| `sw_search` | `resource`, `query` | Name/title substring match |\n\n`resource` is one of `PEOPLE`, `FILMS`, `PLANETS`, `SPECIES`, `STARSHIPS`, `VEHICLES`.\nIds are the record ids from each entity's `url` field (for `FILMS`, `1` = A New Hope).\n\n<details>\n<summary><strong>Claude Code</strong></summary>\n\n```bash\nclaude mcp add --transport http swapi-build https://swapi.build/mcp\n```\n\nOr share via `.mcp.json` at the repo root:\n\n```json\n{\n  \"mcpServers\": {\n    \"swapi-build\": { \"type\": \"http\", \"url\": \"https://swapi.build/mcp\" }\n  }\n}\n```\n\nVerify: `claude mcp list` → `swapi-build ✔ Connected`.\n</details>\n\n<details>\n<summary><strong>Claude Desktop &amp; claude.ai</strong></summary>\n\nSettings → Connectors → **Add custom connector** → name `swapi-build`, URL\n`https://swapi.build/mcp`. No authentication needed. Verify in any chat via the **+** menu → Connectors.\n</details>\n\n<details>\n<summary><strong>OpenAI Codex</strong></summary>\n\n```bash\ncodex mcp add swapi-build --url https://swapi.build/mcp\n```\n\nOr in `~/.codex/config.toml` (shared by CLI, IDE extension and ChatGPT desktop):\n\n```toml\n[mcp_servers.swapi-build]\nurl = \"https://swapi.build/mcp\"\n```\n\nVerify: `codex mcp list`.\n</details>\n\n<details>\n<summary><strong>GitHub Copilot (VS Code)</strong></summary>\n\n`.vscode/mcp.json` (top-level key is `servers`):\n\n```json\n{\n  \"servers\": {\n    \"swapi-build\": { \"type\": \"http\", \"url\": \"https://swapi.build/mcp\" }\n  }\n}\n```\n\nOr Command Palette → **MCP: Add Server**. Verify via the **Configure Tools** button in Copilot Chat.\nOn Business/Enterprise, the \"MCP servers in Copilot\" org policy must be enabled.\n</details>\n\n<details>\n<summary><strong>IBM Bob</strong></summary>\n\n`~/.bob/settings/mcp_settings.json` (global) or `.bob/mcp.json` (project):\n\n```json\n{\n  \"mcpServers\": {\n    \"swapi-build\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"https://swapi.build/mcp\",\n      \"disabled\": false\n    }\n  }\n}\n```\n\nOr Bob panel → MCP tab → **Edit Global MCP**. Bob detects the tools automatically.\n</details>\n\n> The server scales to zero when idle — if the very first connection attempt fails, retry once\n> (the native binary starts in tens of milliseconds; the platform may take a bit longer to\n> provision the container; subsequent calls are fast, whether your client is stateless or\n> session-based).\n\n## Client examples\n\n- [`examples/java/langchain4j-mcp-client`](examples/java/langchain4j-mcp-client) — ask\n  questions in natural language; the tools come from the MCP server above, so the example\n  defines none.\n- [`examples/java/quarkus-rest-client`](examples/java/quarkus-rest-client) — call the REST\n  API from Java with a typed client.\n\n## Project Structure\n\n```\nswapi-app/\n  Dockerfile.vercel           # Native container image used by Vercel deploys\n  src/main/\n    java/com/eldermoraes/     # Backend (Quarkus + Jakarta REST)\n      film/                   # Film model, service, resource\n      people/                 # People model, service, resource\n      planet/                 # Planet model, service, resource\n      specie/                 # Specie model, service, resource\n      starship/               # Starship model, service, resource\n      vehicle/                # Vehicle model, service, resource\n      mcp/                    # MCP server tools (sw_list, sw_get, sw_random, sw_search)\n      SWObject.java           # Base model class\n      SWService.java          # Service interface\n      ApiResource.java        # Root /api endpoint\n      ApplicationPath.java    # Jakarta REST base path (/api)\n    resources/\n      data/                   # Static JSON data files\n      application.properties  # Quarkus configuration\n    webui/                    # Frontend (TypeScript + Vite)\n      src/\n        api.ts                # API client with request management\n        main.ts               # SPA router\n        pages/                # Page renderers (home, resource, docs, mcp, about, privacy, terms)\n        json-highlight.ts     # JSON syntax highlighting for result panels\n        style.css             # Site styles\n        types.ts              # TypeScript interfaces for API resources\n        constants.ts          # Shared resource metadata\n        utils.ts              # Shared utilities (escapeHtml)\n  src/test/\n    java/com/eldermoraes/     # Regression suite (REST contracts, MCP tools, forwarded headers)\n```\n\nEach backend domain (film, people, planet, etc.) follows the same pattern:\n\n- **Model** (e.g., `Film.java`): POJO with `@RegisterForReflection` for native image support\n- **Service** (e.g., `FilmService.java`): loads data from JSON at startup, caches in memory\n- **Resource** (e.g., `FilmResource.java`): Jakarta REST controller with `@RunOnVirtualThread`\n\n## Build\n\n```bash\ncd swapi-app\n\n# Development mode (live reload)\n./mvnw quarkus:dev\n\n# Production JAR\n./mvnw package\njava -jar target/quarkus-app/quarkus-run.jar\n\n# Native executable (requires GraalVM or container build)\n./mvnw package -Dnative\n./mvnw package -Dnative -Dquarkus.native.container-build=true\n```\n\nThe frontend is automatically built and bundled by [Quinoa](https://docs.quarkiverse.io/quarkus-quinoa/dev/index.html) during the Maven build. No separate `npm` step is needed.\n\n## Deployment\n\nThe app runs on [Vercel](https://vercel.com/) as a native (GraalVM/Mandrel) container image, built from `swapi-app/Dockerfile.vercel`. DNS is managed on Cloudflare (DNS-only records pointing to Vercel). Deploys are done with `npx vercel deploy --prod` from the `swapi-app/` directory.\n\n## Tech Stack\n\n- **Runtime:** [Quarkus 3.33](https://quarkus.io/) on Java 25 with Virtual Threads\n- **MCP server:** [Quarkiverse MCP Server](https://docs.quarkiverse.io/quarkus-mcp-server/dev/index.html) — Streamable HTTP, stateless and session-based clients\n- **Serialization:** Jakarta REST + JSON-B\n- **Native image:** GraalVM via Mandrel builder\n- **Frontend:** TypeScript + [Vite](https://vite.dev/), served by Quinoa\n\n## Contributing\n\nPull requests are always welcome. Whether it's fixing a bug, improving the docs, or adding new features, jump in and help make the best Star Wars API in the galaxy even better.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/my-change`)\n3. Make your changes (with tests) and run the suite: `cd swapi-app && ./mvnw test`\n4. Commit and push\n5. Open a Pull Request\n\n## Changelog and releases\n\nRelease history lives in [CHANGELOG.md](CHANGELOG.md). Tagged releases are on the\n[Releases page](https://github.com/eldermoraes/swapi.build/releases). The version\nserved in `/openapi.json` (`info.version`) is always the latest released version.\nThe release process itself is documented in [docs/RELEASE.md](docs/RELEASE.md).\n\n## Credits\n\n- Original [SWAPI](https://swapi.dev/) by **Paul Hallett**, maintained by **Juriy Bura**\n- Star Wars data from community-driven sources such as [Wookieepedia](https://starwars.fandom.com/)\n- All Star Wars content and imagery are property of **Lucasfilm Ltd.** and **Disney**. This project is not affiliated with or endorsed by Lucasfilm or Disney.\n\n## License\n\nLicensed under the [Apache License 2.0](LICENSE). The website also publishes a\n[Privacy Policy](https://swapi.build/privacy) and [Terms of Use](https://swapi.build/terms).\n",
  "bytes": 10282,
  "sha": "5341b3542a9238ed0016aa3e07a90a93e5168996efd9d844da830ff84eb7e281",
  "repo_slug": "eldermoraes/swapi.build",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_build_swapi_star_wars_65e3f8e6/readme"
}