milkyway-codex-mcp 1.0.0

package/README.md

@@ -0,0 +1,98 @@
+# MilkyWay Codex MCP Server
+
+An MCP (Model Context Protocol) server that provides AI assistants with accurate WoW 3.3.5a (WotLK) addon development reference data. Powered by the [MilkyWay Codex](https://milkyway-codex.vercel.app/) dataset.
+
+## Reference Data
+
+| Category | Count | Description |
+|----------|-------|-------------|
+| API Functions | 2,137 | Lua API functions with signatures, parameters, returns, examples |
+| Events | 558 | Game events with payload parameters |
+| Widgets | 38 | UI widget types with methods, inheritance, script handlers |
+| CVars | 449 | Console variables with defaults and descriptions |
+| Data Types | 33 | Enums and flag types (anchorPoint, unitId, etc.) |
+| Combat Log Events | 48 | Combat log sub-events with argument tables |
+| Secure Templates | 14 | Secure frame templates with attributes |
+| Categories | 100 | API function categories |
+
+## Setup
+
+### Using the MCP server
+
+1. **Add the server to your AI assistant.** Edit your MCP config file and add the `milkyway-codex` entry under `mcpServers`:
+
+   ```json
+   {
+     "mcpServers": {
+       "milkyway-codex": {
+         "command": "npx",
+         "args": ["-y", "milkyway-codex-mcp"]
+       }
+     }
+   }
+   ```
+
+   The first time you use it, `npx` will download and run the package. No clone or install required.
+
+   **Config file locations:**
+
+   | Client | Config path |
+   |--------|-------------|
+   | Cursor | `~/.cursor/mcp.json` or project `.cursor/mcp.json` |
+   | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
+   | Rovo Dev | `~/.rovodev/mcp.json`; add `milkyway-codex` to `allowedMcpServers` in `~/.rovodev/config.yml` |
+
+2. **Restart your AI assistant** so it picks up the new MCP config.
+
+## Tools
+
+### `search`
+Global search across all reference data (functions, events, widgets, CVars, data types, secure templates, combat log events). Supports filtering by type and category.
+
+### `get_function`
+Get complete API function documentation: signature, parameters, return values, code examples, protection status, and related functions.
+
+### `get_event`
+Get complete event documentation: description, payload parameters, category, and related events.
+
+### `get_widget`
+Get complete widget type documentation: methods, inherited methods, script handlers, and inheritance chain.
+
+### `get_data_type`
+Get data type documentation with all enumerated values.
+
+### `get_cvar`
+Get console variable details. Supports partial name matching.
+
+### `get_combat_log_event`
+Get combat log sub-event details, or call without arguments for a full system overview.
+
+### `get_secure_template`
+Get secure frame template documentation with attributes and examples.
+
+### `list_categories`
+List all API function categories with function counts.
+
+### `list_widgets`
+List all UI widget types with brief descriptions.
+
+## Syncing Data
+
+The MCP server ships with pre-built JSON data files in `src/data/`. If the codex source data is updated, regenerate them:
+
+```bash
+npm run sync-data
+```
+
+This reads from `milkyway-codex/src/data/*.ts` and writes JSON to `src/data/`.
+
+## Token Efficiency
+
+The server is designed to minimize token usage in AI conversations:
+
+- **Search before fetch** -- `search` returns brief summaries (name + truncated description) so the AI can identify the right entry before requesting full details with a `get_*` tool.
+- **Scored ranking** -- Search results are ranked by relevance (exact match > prefix > contains > description match), putting the most useful results first and reducing follow-up queries.
+- **Scoped lookups** -- Each `get_*` tool returns only the requested entry rather than dumping entire datasets. A `get_function` call returns one function's docs, not all 2,137.
+- **Filtered search** -- Optional `type` and `category` filters narrow results server-side, avoiding large result sets the AI would need to sift through.
+- **Compact listings** -- `list_categories` and `list_widgets` return brief one-line summaries, not full documentation for every entry.
+- **Fuzzy suggestions** -- When a lookup misses, the server returns "did you mean?" suggestions so the AI can self-correct in one turn instead of re-searching.