familiar-vtt 0.1.0

package/dist/server/shared/protocol.d.ts

@@ -0,0 +1,184 @@
+import { z } from 'zod';
+/** Protocol header used for identification */
+export declare const PROTOCOL_HEADER = "familiar";
+/** All supported message types over WebSocket */
+export declare const MessageType: {
+    /** Query from MCP server → Foundry module */
+    readonly QUERY: "mcp-query";
+    /** Response from Foundry module → MCP server */
+    readonly RESPONSE: "mcp-response";
+    /** Ping from server → module */
+    readonly PING: "ping";
+    /** Pong from module → server */
+    readonly PONG: "pong";
+};
+export type MessageType = (typeof MessageType)[keyof typeof MessageType];
+/** Query payload sent from MCP server to Foundry module */
+export declare const queryMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"mcp-query">;
+    id: z.ZodString;
+    data: z.ZodObject<{
+        method: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        method: string;
+        params?: Record<string, unknown> | undefined;
+    }, {
+        method: string;
+        params?: Record<string, unknown> | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    type: "mcp-query";
+    id: string;
+    data: {
+        method: string;
+        params?: Record<string, unknown> | undefined;
+    };
+}, {
+    type: "mcp-query";
+    id: string;
+    data: {
+        method: string;
+        params?: Record<string, unknown> | undefined;
+    };
+}>;
+/** Response payload sent from Foundry module to MCP server */
+export declare const responseMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"mcp-response">;
+    id: z.ZodString;
+    data: z.ZodObject<{
+        success: z.ZodBoolean;
+        result: z.ZodOptional<z.ZodUnknown>;
+        error: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        success: boolean;
+        error?: string | undefined;
+        result?: unknown;
+    }, {
+        success: boolean;
+        error?: string | undefined;
+        result?: unknown;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    type: "mcp-response";
+    id: string;
+    data: {
+        success: boolean;
+        error?: string | undefined;
+        result?: unknown;
+    };
+}, {
+    type: "mcp-response";
+    id: string;
+    data: {
+        success: boolean;
+        error?: string | undefined;
+        result?: unknown;
+    };
+}>;
+/** Ping message */
+export declare const pingMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ping">;
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "ping";
+    id: string;
+}, {
+    type: "ping";
+    id: string;
+}>;
+/** Pong message */
+export declare const pongMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"pong">;
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "pong";
+    id: string;
+}, {
+    type: "pong";
+    id: string;
+}>;
+/** Union of all valid WebSocket messages */
+export declare const socketMessageSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"mcp-query">;
+    id: z.ZodString;
+    data: z.ZodObject<{
+        method: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        method: string;
+        params?: Record<string, unknown> | undefined;
+    }, {
+        method: string;
+        params?: Record<string, unknown> | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    type: "mcp-query";
+    id: string;
+    data: {
+        method: string;
+        params?: Record<string, unknown> | undefined;
+    };
+}, {
+    type: "mcp-query";
+    id: string;
+    data: {
+        method: string;
+        params?: Record<string, unknown> | undefined;
+    };
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"mcp-response">;
+    id: z.ZodString;
+    data: z.ZodObject<{
+        success: z.ZodBoolean;
+        result: z.ZodOptional<z.ZodUnknown>;
+        error: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        success: boolean;
+        error?: string | undefined;
+        result?: unknown;
+    }, {
+        success: boolean;
+        error?: string | undefined;
+        result?: unknown;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    type: "mcp-response";
+    id: string;
+    data: {
+        success: boolean;
+        error?: string | undefined;
+        result?: unknown;
+    };
+}, {
+    type: "mcp-response";
+    id: string;
+    data: {
+        success: boolean;
+        error?: string | undefined;
+        result?: unknown;
+    };
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"ping">;
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "ping";
+    id: string;
+}, {
+    type: "ping";
+    id: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"pong">;
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "pong";
+    id: string;
+}, {
+    type: "pong";
+    id: string;
+}>]>;
+export type QueryMessage = z.infer<typeof queryMessageSchema>;
+export type ResponseMessage = z.infer<typeof responseMessageSchema>;
+export type PingMessage = z.infer<typeof pingMessageSchema>;
+export type PongMessage = z.infer<typeof pongMessageSchema>;
+export type SocketMessage = z.infer<typeof socketMessageSchema>;

package/dist/server/shared/protocol.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { MODULE_ID } from './constants.js';
+/** Protocol header used for identification */
+export const PROTOCOL_HEADER = MODULE_ID;
+// ============================================
+// Message Types
+// ============================================
+/** All supported message types over WebSocket */
+export const MessageType = {
+    /** Query from MCP server → Foundry module */
+    QUERY: 'mcp-query',
+    /** Response from Foundry module → MCP server */
+    RESPONSE: 'mcp-response',
+    /** Ping from server → module */
+    PING: 'ping',
+    /** Pong from module → server */
+    PONG: 'pong',
+};
+// ============================================
+// Message Schemas (Zod)
+// ============================================
+/** Query payload sent from MCP server to Foundry module */
+export const queryMessageSchema = z.object({
+    type: z.literal(MessageType.QUERY),
+    id: z.string(),
+    data: z.object({
+        method: z.string(),
+        params: z.record(z.unknown()).optional(),
+    }),
+});
+/** Response payload sent from Foundry module to MCP server */
+export const responseMessageSchema = z.object({
+    type: z.literal(MessageType.RESPONSE),
+    id: z.string(),
+    data: z.object({
+        success: z.boolean(),
+        result: z.unknown().optional(),
+        error: z.string().optional(),
+    }),
+});
+/** Ping message */
+export const pingMessageSchema = z.object({
+    type: z.literal(MessageType.PING),
+    id: z.string(),
+});
+/** Pong message */
+export const pongMessageSchema = z.object({
+    type: z.literal(MessageType.PONG),
+    id: z.string(),
+});
+/** Union of all valid WebSocket messages */
+export const socketMessageSchema = z.discriminatedUnion('type', [
+    queryMessageSchema,
+    responseMessageSchema,
+    pingMessageSchema,
+    pongMessageSchema,
+]);
+//# sourceMappingURL=protocol.js.map

package/dist/server/shared/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../src/shared/protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,8CAA8C;AAC9C,MAAM,CAAC,MAAM,eAAe,GAAG,SAAS,CAAC;AAEzC,+CAA+C;AAC/C,gBAAgB;AAChB,+CAA+C;AAE/C,iDAAiD;AACjD,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,6CAA6C;IAC7C,KAAK,EAAE,WAAW;IAClB,gDAAgD;IAChD,QAAQ,EAAE,cAAc;IACxB,gCAAgC;IAChC,IAAI,EAAE,MAAM;IACZ,gCAAgC;IAChC,IAAI,EAAE,MAAM;CACJ,CAAC;AAIX,+CAA+C;AAC/C,wBAAwB;AACxB,+CAA+C;AAE/C,2DAA2D;AAC3D,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC;IAClC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACb,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;QAClB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;KACzC,CAAC;CACH,CAAC,CAAC;AAEH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC;IACrC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACb,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;QACpB,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;QAC9B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC7B,CAAC;CACH,CAAC,CAAC;AAEH,mBAAmB;AACnB,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC;IACjC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;CACf,CAAC,CAAC;AAEH,mBAAmB;AACnB,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC;IACjC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;CACf,CAAC,CAAC;AAEH,4CAA4C;AAC5C,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IAC9D,kBAAkB;IAClB,qBAAqB;IACrB,iBAAiB;IACjB,iBAAiB;CAClB,CAAC,CAAC"}

package/dist/server/shared/types.d.ts

@@ -0,0 +1,21 @@
+/** Unique message correlation ID */
+export type MessageId = string;
+/** Result of a successful Foundry query */
+export interface QueryResult {
+    success: true;
+    result: unknown;
+}
+/** Result of a failed Foundry query */
+export interface QueryError {
+    success: false;
+    error: string;
+}
+/** Union result type from Foundry queries */
+export type QueryResponse = QueryResult | QueryError;
+/** Handler function signature for Foundry module query handlers */
+export type QueryHandler = (params?: Record<string, unknown>) => Promise<QueryResponse>;
+/** MCP tool content block (text response) */
+export interface McpTextContent {
+    type: 'text';
+    text: string;
+}

package/dist/server/shared/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/server/shared/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/shared/types.ts"],"names":[],"mappings":""}

package/module.json

@@ -0,0 +1,21 @@
+{
+  "id": "familiar",
+  "title": "Familiar",
+  "description": "<p>Your AI familiar for Foundry VTT. AI DM assistant with 124 tools — manages scenes, combat, tokens, music, and more.</p>",
+  "version": "0.1.0",
+  "compatibility": {
+    "minimum": "12",
+    "verified": "13"
+  },
+  "authors": [
+    {
+      "name": "Ryan Jansen",
+      "url": "https://github.com/Ryanjansen92"
+    }
+  ],
+  "esmodules": ["main.js"],
+  "socket": true,
+  "url": "https://github.com/Ryanjansen92/familiar",
+  "bugs": "https://github.com/Ryanjansen92/familiar/issues",
+  "license": "LICENSE"
+}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "familiar-vtt",
+  "version": "0.1.0",
+  "description": "Your AI familiar for Foundry VTT — AI DM assistant",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "familiar-vtt": "dist/server/server/index.js"
+  },
+  "scripts": {
+    "build": "npm run build:server && npm run build:module",
+    "build:server": "tsc -p tsconfig.server.json",
+    "build:module": "esbuild src/module/main.ts --bundle --format=esm --outfile=dist/module/main.js --platform=browser --target=es2022 --minify --sourcemap",
+    "build:mcp-package": "esbuild src/server/index.ts --bundle --platform=node --format=esm --outfile=dist/mcp-package/index.mjs --external:bufferutil --external:utf-8-validate --minify --banner:js=\"#!/usr/bin/env node\"",
+    "deploy": "npm run build && node --input-type=module -e \"import fs from 'fs';const d=process.env.LOCALAPPDATA+'/FoundryVTT/Data/modules/familiar';fs.mkdirSync(d,{recursive:true});fs.copyFileSync('dist/module/main.js',d+'/main.js');fs.copyFileSync('module.json',d+'/module.json');console.log('Deployed to '+d)\"",
+    "dev": "tsx watch src/server/index.ts",
+    "inspect": "npx @modelcontextprotocol/inspector tsx src/server/index.ts",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit -p tsconfig.server.json && tsc --noEmit -p tsconfig.module.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "knip": "knip",
+    "lockfile-lint": "lockfile-lint --path package-lock.json --type npm --allowed-hosts npm --validate-https",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "pino": "^10.3.1",
+    "ws": "^8.18.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.4.1",
+    "@commitlint/config-conventional": "^20.4.1",
+    "@types/node": "^22.15.0",
+    "@types/ws": "^8.18.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/eslint-plugin": "^1.6.7",
+    "esbuild": "^0.25.0",
+    "eslint": "^9.38.0",
+    "eslint-plugin-depend": "^1.4.0",
+    "eslint-plugin-no-secrets": "^2.2.2",
+    "eslint-plugin-promise": "^7.2.1",
+    "eslint-plugin-regexp": "^3.0.0",
+    "eslint-plugin-security": "^3.0.1",
+    "eslint-plugin-sonarjs": "^3.0.7",
+    "eslint-plugin-unicorn": "^63.0.0",
+    "husky": "^9.1.7",
+    "jiti": "^2.6.1",
+    "knip": "^5.83.1",
+    "lint-staged": "^16.2.7",
+    "lockfile-lint": "^5.0.0",
+    "prettier": "^3.5.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.55.0",
+    "vitest": "^3.2.0"
+  },
+  "keywords": [
+    "foundry-vtt",
+    "familiar",
+    "mcp",
+    "dnd",
+    "tabletop",
+    "ai",
+    "claude"
+  ],
+  "lint-staged": {
+    "*.ts": [
+      "eslint --no-warn-ignored --max-warnings 0",
+      "prettier --check"
+    ]
+  },
+  "license": "MIT"
+}