Skip to main content
Glama
jx3box-mcp

jx3box-mcp

by zenenznze
README.md
# jx3box-mcp

Read-only [MCP](https://modelcontextprotocol.io) server (and a small CLI) for the
public **JX3BOX** (魔盒,剑网3 / JX3) endpoints: posts, macro guides, build (配装)
pages and Node v2 game data.

- **No API key, account, cookie or token.** Every request goes to the public
  JX3BOX APIs with a plain `User-Agent`. Nothing is collected or stored.
- **No dependencies.** Pure Node.js (>= 18.17) ESM; `npx` or a global install is enough.
- **Read-only.** The tools fetch and parse; they never write to JX3BOX.

Not affiliated with or endorsed by JX3BOX / 剑网3. Data and rate limits belong to
JX3BOX; respect their terms and do not hammer the API.

## Install

```bash
npx -y jx3box-mcp            # MCP stdio server, no install step
# or
npm install -g jx3box-mcp
```

## Use as an MCP server

MCP client configuration (Claude Desktop, Codex, Cursor, Magpie Library, …):

```json
{
  "mcpServers": {
    "jx3box": {
      "command": "npx",
      "args": ["-y", "jx3box-mcp"]
    }
  }
}
```

Magpie Library has the same shape:

```bash
magpie library mcp add jx3box npx -y jx3box-mcp
```

Tools:

| Tool | What it returns |
| --- | --- |
| `jx3box_get_post` | A post by ID or `jx3box.com/macro|bps|pz/ID` URL: metadata, full text, raw HTML, macro/build fields |
| `jx3box_get_macro` | A macro post's scripts, instructions, talent data and metadata |
| `jx3box_search` | CMS search over posts: keyword, kind (`all|macro|bps|pz`), subtype, season, pagination |
| `jx3box_get_build` | A build (配装) page by post URL or ID |
| `jx3box_get_game_data` | Documented `/api/node/v2` game data, e.g. `endpoint: "item"` |

The server speaks MCP over stdio (newline-delimited JSON-RPC); `Content-Length`
framed clients are accepted too.

## CLI

```bash
npx -y jx3box-mcp --help          # MCP server help
npx -y jx3box get 110420
npx -y jx3box get https://www.jx3box.com/macro/110420 --format json
npx -y jx3box search macro --keyword 冰心诀 --season 苍生铸世 --limit 10
npx -y jx3box search all --keyword 配装 --format json
```

## Data sources

- CMS posts: `https://cms.jx3box.com/api/cms/post/{id}`, `/posts` (search),
  `/app/pz/{id}` (builds)
- Game data: `https://node.jx3box.com/api/node/v2/{endpoint}`

HTTP and API errors are surfaced as tool errors; there is no automatic retry and
no attempt to bypass access controls.

## Development

```bash
npm test        # unit tests, no network
```

The tests inject a fake `fetch`, so they never touch JX3BOX.

## License

MIT. See [LICENSE](LICENSE).