# Pokédex MCP Server

A local [Model Context Protocol](https://modelcontextprotocol.io) server that
exposes a public, read-only Gen I Pokédex knowledge base (National Pokédex
**#001–#025**) to Claude Desktop.

It fetches plain Markdown directly from the public GitHub repository
[`alexverdin/llm-pokedex-demo`](https://github.com/alexverdin/llm-pokedex-demo)
over `raw.githubusercontent.com` — **no authentication, no tokens, no git
clone, no database.** Downloaded files are held in an in-memory cache (default
TTL: 10 minutes) so repeated queries don't re-download.

## What it does

**Tools (7):**

| Tool | Description |
|------|-------------|
| `list_pokedex_entries` | All 25 entries `[{ id, name, types, file }]`. Optional `type` filter (case-insensitive substring). |
| `search_by_name` | Entries whose name contains `query` (case-insensitive). |
| `get_pokemon` | Get one entry by `id` (`"025"`) or `name` (`"pikachu"`). `format`: `"parsed"` (default), `"markdown"`, `"both"`. |
| `get_base_stats` | `{ hp, attack, defense, spAtk, spDef, speed, total }` as numbers. |
| `compare_pokemon` | Compare 2–6 `ids`; returns a Markdown table of types + all base stats. |
| `rank_by_stat` | Rank all 25 by `stat` (`hp\|attack\|defense\|spAtk\|spDef\|speed\|total`), `order` (`asc\|desc`, default `desc`), `limit` (default 5). |
| `get_evolution_chain` | Evolution section text for an id/name + related entries resolved by scanning other files. |

**Resources (2):**

- `pokedex://index` — raw `INDEX.md`.
- `pokedex://pokemon/{id}` — raw entry Markdown for a 3-digit id.

## Requirements

- **Node.js ≥ 20** (`node --version`).
- An MCP client — Claude Desktop and/or [OpenCode](https://opencode.ai).

## Installation

```bash
git clone https://github.com/alexverdin/mcp-pokedex-demo.git
cd mcp-pokedex-demo
npm install
npm run build
```

Verify it starts (Ctrl+C to stop — it waits for a client on stdio):

```bash
npm start
# stderr: pokedex-mcp running on stdio (repo: alexverdin/llm-pokedex-demo@main)
```

## Claude Desktop config

Add the server to `claude_desktop_config.json`:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

Use an **absolute path** to the built entry point (`dist/index.js`):

```json
{
  "mcpServers": {
    "pokedex": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/mcp-pokedex-demo/dist/index.js"]
    }
  }
}
```

Windows example (note the doubled backslashes):

```json
{
  "mcpServers": {
    "pokedex": {
      "command": "node",
      "args": ["C:\\Users\\you\\mcp-pokedex-demo\\dist\\index.js"]
    }
  }
}
```

**Restart Claude Desktop** (fully quit and reopen) after editing the config.
The server and its tools appear once Claude Desktop relaunches.

### Optional flags

Point the server at a fork or tune the cache by adding flags to `args`:

```json
"args": [
  "/ABSOLUTE/PATH/TO/dist/index.js",
  "--repo", "your-user/your-fork",
  "--branch", "main",
  "--ttl", "600000"
]
```

- `--repo` accepts `owner/repo` or a full `github.com` URL. Default: `alexverdin/llm-pokedex-demo`.
- `--branch` default: `main`.
- `--ttl` cache lifetime in ms. Default: `600000` (10 min).

## OpenCode config

[OpenCode](https://opencode.ai) reads MCP servers from an `opencode.json` file.
Add the server under the `mcp` block as a **local** (stdio) server, pointing
`command` at the built entry point (`dist/index.js`).

Config file locations (project config overrides global):

- **Global:** `%USERPROFILE%\.config\opencode\opencode.json`
- **Project:** `opencode.json` in the repo root

Use an **absolute path** with doubled backslashes on Windows:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pokedex": {
      "type": "local",
      "command": ["node", "C:\\ABSOLUTE\\PATH\\TO\\mcp-pokedex\\dist\\index.js"],
      "enabled": true
    }
  }
}
```

macOS / Linux example:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pokedex": {
      "type": "local",
      "command": ["node", "/ABSOLUTE/PATH/TO/mcp-pokedex/dist/index.js"],
      "enabled": true
    }
  }
}
```

Restart the OpenCode session after editing. The server's tools then appear in
the agent's tool list.

Optional flags (same as above) go in the `command` array after the script path:

```json
"command": [
  "node",
  "C:\\ABSOLUTE\\PATH\\TO\\mcp-pokedex\\dist\\index.js",
  "--repo", "your-user/your-fork",
  "--branch", "main",
  "--ttl", "600000"
]
```

## Example prompts

- "List all Pokédex entries that are Fire type."
- "Get the base stats for Pikachu."
- "Compare Bulbasaur, Charmander, and Squirtle."
- "What are the three fastest Pokémon in the Pokédex?"
- "Show me the evolution chain for Charmander."
- "Search for Pokémon whose name contains 'saur'."

## Troubleshooting

- **Server not showing up:** confirm the path in `args` is absolute and points at
  `dist/index.js` (not `src/`), and that you ran `npm run build`. Fully restart
  Claude Desktop.
- **`node: command not found`:** Claude Desktop must find `node` on PATH. Use an
  absolute path to the node binary in `command` if needed (e.g.
  `/usr/local/bin/node` or the output of `which node` / `where node`).
- **Wrong Node version:** requires Node ≥ 20 (`node --version`). ESM + global
  `fetch` depend on it.
- **Logs:**
  - macOS: `~/Library/Logs/Claude/mcp*.log`
  - Windows: `%APPDATA%\Claude\logs\mcp*.log`
  - The server writes its own diagnostics to **stderr** (stdout is reserved for
    the MCP protocol).
- **Network:** the only outbound host is `raw.githubusercontent.com`. A 404 for
  an entry usually means an out-of-range id (valid ids are `001`–`025`).

## Development

```bash
npm run dev     # tsx watch mode (rebuild-free)
npm run build   # compile to dist/
npm start       # run compiled server
```

## Testing with MCP Inspector

[MCP Inspector](https://github.com/modelcontextprotocol/inspector) lets you
call tools and read resources directly, no Claude Desktop / OpenCode needed.

```bash
npm run build
npx @modelcontextprotocol/inspector node dist/index.js
```

Terminal prints a URL with an auth token, e.g.:

```
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<token>
```

Open it in browser. Transport preset to stdio, command `node dist/index.js`.
Click **Connect**, then:

- **Tools** tab — pick a tool (e.g. `get_pokemon`), fill args (`id: "025"`), **Run**.
- **Resources** tab — read `pokedex://index` or `pokedex://pokemon/001`.

To test against a fork or non-default flags, append them after the script path:

```bash
npx @modelcontextprotocol/inspector node dist/index.js --repo your-user/your-fork --ttl 600000
```

Ctrl+C in the terminal stops both Inspector and the server.

## License

MIT — see [LICENSE](LICENSE).