# leekwars-mcp

Standard TypeScript MCP server scaffold.

## Structure

- `src/index.ts` - entrypoint
- `src/auth/` - MCP-owned LeekWars session handling
- `src/server/` - server bootstrap and request routing
- `src/tools/` - manifest-driven tool definitions and registry
- `src/tools/{core,auth,leek,fight,ai,items,reports}/` - tool manifests grouped by domain
- `src/resources/` - resource definitions
- `src/prompts/` - prompt definitions
- `src/config/` - runtime config
- `src/common/` - shared types/helpers
- `src/scripts/` - subprocess bridge for vendored LeekWars scripts
- `src/tools/_shared/` - vendored script helpers and shared assets

## Auth

The server now owns the LeekWars session.

Required env vars:
- `LEEKWARS_LOGIN`
- `LEEKWARS_PASSWORD`

Optional env vars:
- `LEEKWARS_AUTH_RETRY_DELAY_MS`
- `LEEKWARS_API_BASE_URL`
- `LEEKWARS_SCRIPTS_DIR` (defaults to `src/tools`)
- `LEEKWARS_SOCKET_URL`
- `LEEKWARS_SOCKET_PROTOCOLS` (comma-separated)
- `LEEKWARS_SOCKET_CONNECT_TIMEOUT_MS`
- `LEEKWARS_SOCKET_REQUEST_TIMEOUT_MS`
- `LEEKWARS_SOCKET_MAX_BUFFERED_EVENTS`
- `MCP_SERVER_NAME`

## Tool registry

Tools are manifest-driven from `src/tools/manifest.ts` and executed through `src/tools/registry.ts`.

Tool output kinds:
- `json` - stdout only
- `markdown` - stdout only
- `text` - stdout + stderr formatting

## Testing

- `npm test` - smoke tests for manifest loading, output formatting, and representative tool execution
- `npm run check` - typecheck only
- `npm run build` - compile to `dist/`

## Scripts

- `npm run dev` - run in watch mode
- `npm run start` - run compiled server

## Fight logs

`fetch_fight_logs` uses Playwright. If the browser binary is missing, install it with:

```bash
npx playwright install chromium
```

## Socket bridge

The socket bridge connects to `wss://leekwars.com/ws` by default (override with `LEEKWARS_SOCKET_URL`) and uses the LeekWars session auth headers. It exposes bridge tools:
- `socket_connect`
- `socket_status`
- `socket_send`
- `socket_call`
- `socket_recv`
- `socket_close`

## Encyclopedia tools

Encyclopedia search and page retrieval live in the separate `leekwars-mcp-encyclopedia` server.
Configure both MCP servers if you need both game actions and encyclopedia knowledge tools.