SWAPI MCP Server

A Model Context Protocol (MCP) server that wraps the Star Wars API (SWAPI) as MCP tools, allowing LLMs and clients to search for Star Wars characters, planets, and films.

Features

• MCP-compliant server using the official TypeScript SDK

• Exposes four tools:

  • search_character: Search for a Star Wars character by name

  • get_planet: Get detailed planet info by ID

  • get_film: Get detailed film info by ID

  • get_internal_character_fact: Get private internal-only character facts (demo data)

• Exposes prompt templates:

  • analyze-character

  • compare-characters

  • explore-planet

• Exposes prompt compatibility tools for clients that only support tools:

  • prompt_analyze_character

  • prompt_compare_characters

  • prompt_explore_planet

• Supports HTTP (stateless, streamable) and optional stdio transport

• Includes unit, integration, and smoke tests

Related MCP server: starwars

Code Structure

• index.ts: Main entry point. Exports app/server builders, registers tools, and configures HTTP/stdio transports.

• test-client/: Example OpenAI client that demonstrates how to call the MCP server as a tool from an LLM.

• tests/: Unit tests, MCP HTTP integration tests, and smoke test script.

Tool Details

search_character

• Input: { name: string }

• Description: Searches SWAPI for characters matching the given name.

• Returns: JSON-formatted list of matching characters.

get_planet

• Input: { id: string }

• Description: Fetches detailed info for a planet by its SWAPI ID.

• Returns: JSON-formatted planet details.

get_film

• Input: { id: string }

• Description: Fetches detailed info for a film by its SWAPI ID.

• Returns: JSON-formatted film details.

get_internal_character_fact

• Input: { name: string }

• Description: Fetches a private character fact from a simulated internal system (not from SWAPI).

• Returns: JSON with source, visibility, character, and fact.

prompt_analyze_character

• Input: { characterName: string }

• Description: Returns the analyze-character prompt text as tool output.

prompt_compare_characters

• Input: { character1: string, character2: string }

• Description: Returns the compare-characters prompt text as tool output.

prompt_explore_planet

• Input: { planetId: string }

• Description: Returns the explore-planet prompt text as tool output.

Prompt Templates

The server also exposes MCP prompt templates via prompt endpoints:

• analyze-character with argument characterName

• compare-characters with arguments character1, character2

• explore-planet with argument planetId

Some chat surfaces only call MCP tools and do not directly invoke prompt endpoints. In those cases, use the prompt_* compatibility tools above.

How It Works

• Uses the @modelcontextprotocol/sdk to create an MCP server.

• Each tool is registered with an input schema (using zod) and an async handler that fetches data from SWAPI.

• The server can be accessed via HTTP POST requests to /mcp or via stdio (for CLI clients).

Running the Server

Prerequisites

• Node.js v22 or newer

• npm

Install dependencies

npm install

Environment variables

• PORT (default 3100)

• ENABLE_HTTP (default 1; set 0 to disable HTTP transport)

• ENABLE_STDIO (default 0; set 1 to enable stdio transport)

• TRUST_PROXY (default 1; set 0 to disable trusting proxy headers)

• ALLOWED_ORIGINS (comma-separated CORS allowlist, defaults to http://localhost:3100,http://localhost:5173)

Run in HTTP mode (default)

npm run dev

• The server will listen on http://localhost:3100/mcp (or the port set in the PORT environment variable).

Run in stdio mode (for CLI clients)

ENABLE_HTTP=0 ENABLE_STDIO=1 npm run dev

Run both transports

ENABLE_STDIO=1 npm run dev

Build and run compiled output

npm run build
npm start

Use From Another VS Code Instance (Same Machine)

This is the easiest way to use this MCP server from a second local VS Code window.

Option A (recommended): Register as a stdio MCP server

1. Open a second VS Code instance.

2. Open the workspace where you want to use this MCP server.

3. Open Command Palette and run MCP: Add Server.

4. Choose a local/command (stdio) server type.

5. Use these values:

   • Name: swapi-local

   • Command: node

   • Args: --import, tsx, index.ts

   • Working directory: /path/to/swapi-mcp-server

   • Environment variables:

     • ENABLE_HTTP=0

     • ENABLE_STDIO=1

6. Save the MCP server configuration and reload the second VS Code window if prompted.

7. In Chat, verify the server is available (for example via MCP server/tools list UI, then call a tool like search_character).

If your VS Code MCP setup uses a JSON config file, this is the equivalent stdio config:

{
  "servers": {
    "swapi-local": {
      "type": "stdio",
      "command": "node",
      "args": ["--import", "tsx", "index.ts"],
      "cwd": "/path/to/swapi-mcp-server",
      "env": {
        "ENABLE_HTTP": "0",
        "ENABLE_STDIO": "1"
      }
    }
  }
}

Minimal server entry (using placeholder path):

{
  "swapi-local": {
    "type": "stdio",
    "command": "node",
    "args": ["--import", "tsx", "index.ts"],
    "cwd": "/path/to/swapi-mcp-server",
    "env": {
      "ENABLE_HTTP": "0",
      "ENABLE_STDIO": "1"
    }
  }
}

If you see Cannot find module .../dist/index.js in MCP logs, your server was launched with a command that expects a built artifact. Use the direct stdio command shown above, or run npm run build before using npm start.

Option B: Register as an HTTP MCP server

1. In this repository, start the server in a terminal:

npm run dev

2. In the second VS Code instance, add an MCP server using URL:

http://localhost:3100/mcp

3. Save and test by calling a tool from Chat.

If your VS Code MCP setup uses JSON config, this is the equivalent HTTP config:

{
  "servers": {
    "swapi-http": {
      "type": "http",
      "url": "http://localhost:3100/mcp"
    }
  }
}

Example HTTP Request

List tools:

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

Search for a character:

curl -N -X POST http://localhost:3100/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
  }'

Get a planet by ID:

curl -N -X POST http://localhost:3100/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
  }'

Get a film by ID:

curl -N -X POST http://localhost:3100/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
  }'

Test Client: OpenAI + MCP Integration

The test-client/ directory contains an example script (swapi-client.ts) that demonstrates how to call the MCP server as a tool from an OpenAI LLM (e.g., GPT-4o-mini).

How it works

• Uses the OpenAI SDK and MCP tool integration.

• Registers the MCP server as a tool for the LLM.

• Sends a prompt/question to the LLM, which can call the MCP tools to answer.

Example: test-client/swapi-client.ts

// tsx ./swapi-client.ts
import 'dotenv/config';
import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! });
const serverUrl = process.env.MCP_SERVER_URL ?? 'http://localhost:3100/mcp';
const model = process.env.OPENAI_MODEL ?? 'gpt-4o-mini';
const prompt = process.env.OPENAI_PROMPT ?? 'Where was Luke Skywalker born, how tall is he, and what does the internal profile say about his milk and tea preference? If the tool "get_internal_character_fact" is unavailable, answer exactly: INTERNAL FACT UNAVAILABLE.';
const useMcp = process.env.USE_MCP !== '0';

const tools = useMcp
  ? [
      {
        type: "mcp" as const,
        server_label: 'swapi',
        server_url: serverUrl,
        require_approval: 'never' as const,
      },
    ]
  : [];

const resp = await openai.responses.create({
  model,
  ...(useMcp ? { tools } : {}),
  input: prompt,
});

console.log(resp.output_text);

Running the test client

1. Install dependencies:

   cd test-client
   npm install

2. Set your OpenAI API key in a .env file:

   OPENAI_API_KEY=sk-...
     USE_MCP=1

3. Start the MCP server (in the parent directory):

   npm run dev

4. Run the test client:

   cd test-client
   npm run dev

Trace output for MCP demos

The test client prints a lightweight trace by default so you can explain the request path during demos.

Example trace output:

[trace +0.00s] Demo started | model=gpt-4o-mini, use_mcp=true
[trace +0.00s] Registered MCP server tool | server_label=swapi, server_url=https://your-ngrok-url/mcp
[trace +0.00s] Sending prompt to OpenAI Responses API | prompt="Where was Luke Skywalker born, how tall is he, and what does the internal profile say about his milk and tea preference? If the tool \"get_internal_character_fact\" is unavailable, answer exactly: INTERNAL FACT UNAVAILABLE."
[trace +1.12s] OpenAI response received | response_id=resp_...
[trace +1.12s] Structured response items received | count=4
[trace +1.12s] Output[0] | type=reasoning
[trace +1.12s] Output[1] | type=mcp_call, name=search_character, status=completed, server_label=swapi
[trace +1.12s] Output[2] | type=mcp_call, name=get_internal_character_fact, status=completed, server_label=swapi
[trace +1.12s] Output[3] | type=message, role=assistant
[trace +1.12s] Printing final answer to console
Luke Skywalker was born on Tatooine and is 172 centimeters tall. Internal fact: Luke likes his blue milk warm and his tea cold.

Trace options:

• USE_MCP=1 enables MCP tool usage (default).

• USE_MCP=0 runs the same prompt directly against the LLM, without MCP tools.

• MCP_TRACE=0 disables trace logs.

• MCP_TRACE_VERBOSE=1 prints full structured response items as JSON.

• OPENAI_PROMPT="..." overrides the default demo question.

Side-by-side demo: with MCP vs without MCP

Single command (runs both modes back-to-back):

cd test-client
npm run dev:compare

Run with MCP enabled:

cd test-client
USE_MCP=1 npm run dev

Run without MCP:

cd test-client
USE_MCP=0 npm run dev

Example responses for the same prompt:

Example trace with MCP (USE_MCP=1):

[trace +0.00s] Demo started | model=gpt-4o-mini, use_mcp=true
[trace +0.00s] Registered MCP server tool | server_label=swapi, server_url=https://your-ngrok-url/mcp
[trace +0.00s] Sending prompt to OpenAI Responses API | prompt="Where was Luke Skywalker born, how tall is he, and what does the internal profile say about his milk and tea preference? If the tool \"get_internal_character_fact\" is unavailable, answer exactly: INTERNAL FACT UNAVAILABLE."
[trace +1.12s] OpenAI response received | response_id=resp_...
[trace +1.12s] Structured response items received | count=4
[trace +1.12s] Output[0] | type=reasoning
[trace +1.12s] Output[1] | type=mcp_call, name=search_character, status=completed, server_label=swapi
[trace +1.12s] Output[2] | type=mcp_call, name=get_internal_character_fact, status=completed, server_label=swapi
[trace +1.12s] Output[3] | type=message, role=assistant
[trace +1.12s] Printing final answer to console
Luke Skywalker was born on Tatooine and is 172 centimeters tall. Internal fact: Luke likes his blue milk warm and his tea cold.

Example trace without MCP (USE_MCP=0):

[trace +0.00s] Demo started | model=gpt-4o-mini, use_mcp=false
[trace +0.00s] MCP tool integration disabled for this run
[trace +0.00s] Sending prompt to OpenAI Responses API | prompt="Where was Luke Skywalker born, how tall is he, and what does the internal profile say about his milk and tea preference? If the tool \"get_internal_character_fact\" is unavailable, answer exactly: INTERNAL FACT UNAVAILABLE."
[trace +0.98s] OpenAI response received | response_id=resp_...
[trace +0.98s] Structured response items received | count=2
[trace +0.98s] Output[0] | type=reasoning
[trace +0.98s] Output[1] | type=message, role=assistant
[trace +0.98s] Printing final answer to console
Luke Skywalker was born on Tatooine and is about 172 cm (5'8") tall. INTERNAL FACT UNAVAILABLE.

For demos, the key difference is the mcp_call item in the MCP trace, which shows the LLM called both SWAPI and internal systems instead of relying only on model knowledge.

MCP flow diagram

sequenceDiagram
  participant Console as test-client/swapi-client.ts
  participant OpenAI as OpenAI Responses API (LLM runtime)
  participant MCP as SWAPI MCP Server (/mcp)
  participant SWAPI as swapi.online API
  participant Internal as Internal Character Profile System

  Console->>OpenAI: responses.create(model, tools[mcp], input)
  OpenAI->>MCP: tools/list
  MCP-->>OpenAI: available tools
  OpenAI->>MCP: tools/call (search_character)
  MCP->>SWAPI: GET /people/?search=Luke
  SWAPI-->>MCP: character JSON
  MCP-->>OpenAI: tool result
  OpenAI->>MCP: tools/call (get_internal_character_fact)
  MCP->>Internal: Lookup Luke private preference
  Internal-->>MCP: Internal-only fact JSON
  MCP-->>OpenAI: tool result
  OpenAI-->>Console: final natural-language answer
  Console->>Console: print trace + answer

• You should see the LLM's answer, which may include information fetched from the SWAPI MCP tools.

• To test with a remote tunnel, set MCP_SERVER_URL in test-client/.env.

Troubleshooting: 424 error with localhost MCP URL

If you see this when running the test client:

Failed to run test client.
MCP server URL: http://localhost:3100/mcp
Reason: 424 Error retrieving tool list from MCP server: 'swapi'. Http status code: 400 (Bad Request)

the model runtime likely cannot reach your local machine at localhost. Expose your local MCP server with ngrok and use that public URL instead.

1. Start the MCP server (in this repository):

   npm run dev

2. In another terminal, start an ngrok tunnel to port 3100:

   ngrok http 3100

3. Copy the HTTPS forwarding URL from ngrok (for example, https://abcd-1234.ngrok-free.app).

4. Set MCP_SERVER_URL in test-client/.env to that URL plus /mcp:

   MCP_SERVER_URL=https://abcd-1234.ngrok-free.app/mcp

5. Run the test client again:

   cd test-client
   npm run dev

Notes:

• Use the HTTPS ngrok URL, not the HTTP one.

• Every time ngrok restarts, the forwarding URL may change (unless you use a reserved domain), so update MCP_SERVER_URL if needed.

• Keep both the MCP server and ngrok process running while testing.

Testing

Run all tests:

npm test

Run focused suites:

npm run test:unit
npm run test:integration
npm run smoke

Run full verification:

npm run verify

Notes

• The server is stateless for HTTP requests (no session management).

• CORS is enabled with an allowlist and exposes the mcp-session-id header.

• For more details on MCP, see the TypeScript SDK documentation.