familiar-vtt 0.1.0

package/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish to npm
+
+on:
+  workflow_dispatch: # Manual trigger from GitHub UI
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+
+      - run: npm ci
+
+      - run: npm run build
+
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "familiar": {
+      "command": "node",
+      "args": ["C:\\Users\\ryan_\\Projects\\familiar\\dist\\server\\server\\index.js"],
+      "env": {
+        "FAMILIAR_WS_PORT": "3005"
+      }
+    }
+  }
+}

package/ARCHITECTURE.md

@@ -0,0 +1,320 @@
+# Familiar Architecture
+
+Technical architecture documentation for the Familiar project.
+
+## Design Principles
+
+- **Single process** — one Node.js process, stdio transport for MCP, WebSocket to Foundry. No wrapper/backend split.
+- **System-agnostic core** — most tools work with any Foundry game system. Character formatting is D&D 5e for now, pluggable later.
+- **Integrate, don't rebuild** — use existing modules (Sequencer, Token Magic FX, etc.) via their APIs instead of reimplementing visual features.
+- **Full AI control** — every action a human DM can do in Foundry, the AI should be able to do via tools.
+- **Build → test → iterate** — implement one tool, test it live, fix issues, move on.
+- **Type-safe routing** — discriminated unions and exhaustive switches, not string-based dispatch.
+- **Modular tools** — each tool domain in its own file with a clean registration pattern.
+- **Minimal dependencies** — `@modelcontextprotocol/sdk`, `ws`, `zod`, `pino`. That's it.
+
+## Architecture Overview
+
+### Current Architecture (MCP)
+
+```
+Claude (or any MCP client)
+    ↓ stdio (MCP protocol)
+MCP Server (single Node.js process)
+    ↓ WebSocket (localhost)
+Foundry VTT Module (browser-side bridge)
+    ↓ Foundry API
+Game World (actors, scenes, items, journals)
+```
+
+### Future Architecture (Built-in, Plug & Play)
+
+```
+Foundry Module (browser)
+    ├── Built-in LLM client (calls AI provider API directly)
+    ├── Tool execution (same 124 tools, runs in browser)
+    ├── Chat UI in Foundry sidebar
+    └── Foundry API
+Game World
+```
+
+The future architecture eliminates the MCP server entirely. The Foundry module talks directly to the AI provider API. No Node.js, no separate process, no MCP config. Everything lives inside the Foundry module.
+
+**Both architectures will be supported** — MCP for power users who want Claude Code/Cursor integration, built-in for everyone else.
+
+## Two Components
+
+### 1. MCP Server (`src/server/`)
+
+Node.js process that:
+- Exposes MCP tools via stdio transport
+- Runs a WebSocket server (port 3005) waiting for the Foundry module to connect
+- Translates MCP tool calls → WebSocket queries → Foundry responses → MCP results
+
+### 2. Foundry Module (`src/module/`)
+
+Browser-side Foundry VTT module that:
+- Connects to the MCP server's WebSocket on world load
+- Receives queries and executes them against the Foundry API (`game.actors`, `game.scenes`, etc.)
+- Returns structured results back over WebSocket
+- GM-only access (non-GM users are silently ignored)
+
+## Shared Code (`src/shared/`)
+
+- `protocol.ts` — Zod-validated WebSocket message schemas (query, response, ping/pong)
+- `types.ts` — Shared TypeScript interfaces
+- `constants.ts` — Module ID, ports, timeouts
+
+## Project Structure
+
+```
+familiar/
+├── src/
+│   ├── server/                  # MCP server (Node.js)
+│   │   ├── index.ts             # Entry point: stdio transport + WebSocket server
+│   │   ├── config.ts            # Zod-validated env config
+│   │   ├── connector.ts         # WebSocket server ↔ Foundry module
+│   │   ├── logger.ts            # Pino logger (stderr)
+│   │   └── tools/               # MCP tool implementations
+│   │       ├── registry.ts      # Tool registration & routing
+│   │       ├── characters.ts    # Character read/write tools (14 tools)
+│   │       ├── combat.ts        # Initiative, conditions, HP tracking (8 tools)
+│   │       ├── scenes.ts        # Scene, token, weather, screen tools (17 tools)
+│   │       ├── canvas.ts        # Templates, tiles, drawings (12 tools)
+│   │       ├── canvas-environment.ts # Walls, lights, sounds, notes, doors (18 tools)
+│   │       ├── compendium.ts    # Compendium search & lookup (4 tools)
+│   │       ├── dice.ts          # Dice rolling (1 tool)
+│   │       ├── journals.ts      # Journal & quest tools (9 tools)
+│   │       ├── chat.ts          # Chat messages (2 tools)
+│   │       ├── playlists.ts     # Music & playlist control (6 tools)
+│   │       ├── tables.ts        # Rollable tables (3 tools)
+│   │       ├── cards.ts         # Card stacks & decks (5 tools)
+│   │       ├── macros.ts        # Macro CRUD & execution (4 tools)
+│   │       ├── effects.ts       # Active effect CRUD (4 tools)
+│   │       ├── items.ts         # Standalone item CRUD (2 tools)
+│   │       ├── folders.ts       # Folder management (3 tools)
+│   │       ├── regions.ts       # Region/trigger zones (3 tools)
+│   │       ├── ember-events.ts  # Ember campaign event tools (5 tools)
+│   │       ├── helpers.ts       # Shared tool helper utilities
+│   │       └── world.ts         # World info, pause & time (4 tools)
+│   ├── module/                  # Foundry VTT module (browser)
+│   │   ├── main.ts              # Module entry, lifecycle hooks, settings registration
+│   │   ├── connection.ts        # WebSocket client with reconnection
+│   │   ├── query-handler.ts     # Query routing → data access
+│   │   ├── query-handlers-sidebar.ts # Sidebar query handlers (chat, playlists, tables, cards, macros)
+│   │   ├── settings-app.ts      # AI Provider Settings UI (ApplicationV2)
+│   │   ├── providers.ts         # AI provider definitions (16 chat, 4 voice, 5 image)
+│   │   ├── ai/                  # Built-in LLM client (browser-side)
+│   │   │   ├── llm-client.ts    # Provider-agnostic LLM client with tool calling loop
+│   │   │   ├── tool-definitions.ts # All 124 tools in OpenAI function-calling format
+│   │   │   ├── streaming.ts     # SSE parser for ReadableStream
+│   │   │   ├── anthropic-adapter.ts # Anthropic Messages API ↔ OpenAI format adapter
+│   │   │   └── types.ts         # Chat message, tool call, streaming types
+│   │   ├── types/               # Foundry VTT type declarations
+│   │   │   ├── foundry.d.ts     # Core Foundry API types
+│   │   │   ├── foundry-appv2.d.ts    # ApplicationV2 type declarations
+│   │   │   ├── foundry-canvas.d.ts   # Canvas layer types
+│   │   │   ├── foundry-combat.d.ts   # Combat system types
+│   │   │   └── foundry-sidebar.d.ts  # Sidebar & UI types
+│   │   └── data/                # Foundry API data access
+│   │       ├── characters.ts    # Actor queries & mutations
+│   │       ├── scenes.ts        # Scene, token & weather queries
+│   │       ├── canvas.ts        # Templates, tiles, drawings
+│   │       ├── canvas-environment.ts # Walls, lights, sounds, notes, doors
+│   │       ├── compendium.ts    # Pack search & lookup
+│   │       ├── dice.ts          # Roll execution
+│   │       ├── journals.ts      # Journal CRUD
+│   │       ├── chat.ts          # Chat message access
+│   │       ├── playlists.ts     # Playlist & track control
+│   │       ├── tables.ts        # Rollable table queries
+│   │       ├── cards.ts         # Card stack operations
+│   │       ├── macros.ts        # Macro CRUD & execution
+│   │       ├── effects.ts       # Active effect CRUD
+│   │       ├── items.ts         # Standalone item CRUD
+│   │       ├── folders.ts       # Folder management
+│   │       ├── regions.ts       # Region/trigger zones
+│   │       ├── ember-events.ts  # Ember campaign event handlers
+│   │       ├── world.ts         # World info, time & pause
+│   │       └── screen.ts        # Screenshot capture
+│   └── shared/                  # Shared types & protocol
+│       ├── protocol.ts          # WebSocket message schemas (Zod)
+│       ├── types.ts             # Shared interfaces
+│       └── constants.ts         # IDs, ports, timeouts
+├── tests/                       # Vitest tests
+├── dist/                        # Build output
+│   ├── server/                  # Compiled MCP server
+│   └── module/                  # Bundled Foundry module (esbuild)
+├── package.json
+├── tsconfig.json
+├── tsconfig.server.json         # Server TypeScript config (Node.js)
+├── tsconfig.module.json         # Module TypeScript config (browser)
+├── eslint.config.ts
+├── vitest.config.ts
+└── CLAUDE.md                    # Project instructions
+```
+
+## Query Methods
+
+The WebSocket protocol uses method-based routing. Each method maps to a Foundry API operation. There are 124 methods total — the module-side handlers are organized by domain in `src/module/data/`. Key examples:
+
+| Domain | Methods | Module Handler |
+|--------|---------|---------------|
+| World & System | `get-world-info`, `toggle-pause`, `get-time`, `advance-time` | `data/world.ts` |
+| Characters | `get-character`, `list-characters`, `update-character`, etc. | `data/characters.ts` |
+| Scenes & Tokens | `get-current-scene`, `move-token`, `create-tokens`, `set-weather`, `pan-canvas`, etc. | `data/scenes.ts` |
+| Combat | `start-combat`, `roll-initiative`, `toggle-condition`, etc. | `data/combat.ts` |
+| Canvas | `create-template`, `create-tile`, `create-drawing`, etc. | `data/canvas.ts` |
+| Environment | `create-walls`, `create-light`, `toggle-door`, etc. | `data/canvas-environment.ts` |
+| Compendium | `search-compendium`, `get-compendium-entry`, etc. | `data/compendium.ts` |
+| Journals | `list-journals`, `search-journals`, `get-journal`, etc. | `data/journals.ts` |
+| Chat | `send-chat-message`, `get-recent-messages` | `data/chat.ts` |
+| Playlists | `play-playlist`, `play-track`, `stop-all-playlists`, etc. | `data/playlists.ts` |
+| Tables | `list-rollable-tables`, `roll-table`, etc. | `data/tables.ts` |
+| Cards | `list-card-stacks`, `draw-cards`, `shuffle-deck`, etc. | `data/cards.ts` |
+| Macros | `list-macros`, `create-macro`, `execute-macro`, `delete-macro` | `data/macros.ts` |
+| Active Effects | `list-effects`, `create-effect`, `update-effect`, `delete-effect` | `data/effects.ts` |
+| Items | `create-item`, `delete-item` | `data/items.ts` |
+| Folders | `list-folders`, `create-folder`, `delete-folder` | `data/folders.ts` |
+| Regions | `list-regions`, `create-region`, `delete-regions` | `data/regions.ts` |
+| Ember Events | `list-events`, `get-event`, `begin-event`, `complete-event`, `set-event-outcome` | `data/ember-events.ts` |
+| Dice | `roll-dice` | `data/dice.ts` |
+| Screen | `capture-screen` | `data/screen.ts` |
+
+## Tool Registration Pattern
+
+Tools use a typed registry pattern, not string-based dispatch:
+
+```typescript
+// src/server/tools/registry.ts
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { FoundryConnector } from '../connector.js';
+
+export type ToolRegistrar = (server: McpServer, connector: FoundryConnector) => void;
+
+// Each tool file exports a registrar
+// src/server/tools/characters.ts
+export const registerCharacterTools: ToolRegistrar = (server, connector) => {
+  server.tool(
+    'get-character',
+    'Get a character sheet by name or Foundry ID',
+    { identifier: z.string().describe('Character name or Foundry actor ID') },
+    async ({ identifier }) => {
+      const response = await connector.query('get-character', { identifier });
+      return {
+        content: [{ type: 'text', text: JSON.stringify(response.result, null, 2) }],
+      };
+    }
+  );
+  // ... more character tools
+};
+```
+
+## Configuration
+
+### Environment Variables (MCP Server)
+
+```bash
+FAMILIAR_WS_PORT=3005          # WebSocket port (default: 3005)
+FAMILIAR_LOG_LEVEL=info        # Log level: fatal|error|warn|info|debug|trace
+```
+
+### Claude Code MCP Config (`.mcp.json` or Claude Desktop config)
+
+```json
+{
+  "mcpServers": {
+    "familiar": {
+      "command": "node",
+      "args": ["dist/server/index.js"],
+      "env": {
+        "FAMILIAR_WS_PORT": "3005"
+      }
+    }
+  }
+}
+```
+
+### Foundry Module Installation
+
+Copy `dist/module/` to Foundry's `Data/modules/familiar/` directory along with `module.json`.
+
+## Foundry Module Details
+
+### Module Manifest (`module.json`)
+
+```json
+{
+  "id": "familiar",
+  "title": "Familiar",
+  "description": "Your AI familiar for Foundry VTT — AI DM assistant",
+  "version": "0.1.0",
+  "compatibility": {
+    "minimum": "12",
+    "verified": "13"
+  },
+  "authors": [{ "name": "Ryan Jansen" }],
+  "esmodules": ["main.js"],
+  "socket": true
+}
+```
+
+### Module Lifecycle
+
+1. `Hooks.once('init')` — Register module settings:
+   - MCP connection settings (port, auto-connect) — `config: true` (shown in default settings)
+   - AI provider settings (provider, API key, model, temperature, etc.) — `config: false` (custom UI via `registerMenu`)
+2. `Hooks.once('ready')` — If GM + auto-connect enabled → connect WebSocket to MCP server
+3. On WebSocket message → parse with Zod schema → route to handler → execute Foundry API → send response
+4. On disconnect → exponential backoff reconnect (up to 5 attempts)
+
+### Security
+
+- **GM-only**: All queries require `game.user.isGM` — non-GM users are silently ignored
+- **Write protection**: Destructive operations (delete, update) check permissions before execution
+- **No remote access**: WebSocket listens on localhost only by default
+
+## D&D 5e (2024) Specifics
+
+### Character Data Mapping
+
+The module translates Foundry's D&D 5e system data (`system.abilities`, `system.attributes`, etc.) into a clean, readable format for AI consumption:
+
+- **Abilities**: STR/DEX/CON/INT/WIS/CHA with scores, modifiers, saves
+- **HP**: Current, max, temp
+- **AC**: Total with breakdown
+- **Skills**: All skills with modifiers, proficiency, expertise
+- **Spells**: By level, with slots remaining, prepared status
+- **Items**: Inventory with attunement, equipped status, quantity
+- **Features**: Class features, racial traits, feats
+
+### Compendium Packs
+
+D&D 5e provides compendium packs for:
+- `dnd5e.monsters` — Creature stat blocks
+- `dnd5e.items` — Equipment, weapons, armor
+- `dnd5e.spells` — All spells
+- `dnd5e.classfeatures` — Class features
+- `dnd5e.races` — Ancestries/races
+
+The `search-compendium` tool searches across packs by name. The `get-compendium-entry` tool returns the full entry with all fields.
+
+## Dependencies
+
+### Runtime
+
+- `@modelcontextprotocol/sdk` — MCP protocol implementation
+- `ws` — WebSocket server (lightweight, no socket.io overhead)
+- `zod` — Schema validation for config & protocol
+- `pino` — Fast structured logging
+
+### Dev
+
+- `typescript`, `tsx` — TypeScript toolchain
+- `esbuild` — Fast bundler for Foundry module
+- `eslint` + plugins — Linting (security, sonarjs, unicorn, etc.)
+- `prettier` — Formatting
+- `vitest` — Testing
+- `husky` + `lint-staged` — Pre-commit hooks
+- `commitlint` — Conventional commit enforcement
+- `knip` — Dead code detection