foundryvtt-mcp 0.11.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +90 -19
  2. package/package.json +4 -1
package/README.md CHANGED
@@ -1,6 +1,9 @@
1
1
  # FoundryVTT MCP Server
2
2
 
3
- A Model Context Protocol (MCP) server that integrates with FoundryVTT, allowing AI assistants to interact with your tabletop gaming sessions through natural language.
3
+ [![npm version](https://img.shields.io/npm/v/foundryvtt-mcp)](https://www.npmjs.com/package/foundryvtt-mcp)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
5
+
6
+ A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that integrates with FoundryVTT, allowing AI assistants to interact with your tabletop gaming sessions through natural language.
4
7
 
5
8
  ## Features
6
9
 
@@ -17,23 +20,93 @@ A Model Context Protocol (MCP) server that integrates with FoundryVTT, allowing
17
20
 
18
21
  ### Prerequisites
19
22
 
20
- - Node.js 18+
23
+ - Node.js 18+ (or [Bun](https://bun.sh/))
21
24
  - FoundryVTT server running with an active world
22
- - MCP-compatible AI client (Claude Desktop, etc.)
25
+ - MCP-compatible AI client (Claude Desktop, Claude Code, VS Code, etc.)
26
+
27
+ ### Installation
23
28
 
24
- ### Setup
29
+ Run directly without installing — no clone needed:
25
30
 
26
31
  ```bash
27
- git clone <repository-url>
32
+ bunx foundryvtt-mcp
33
+ ```
34
+
35
+ Or with npx:
36
+
37
+ ```bash
38
+ npx -y foundryvtt-mcp
39
+ ```
40
+
41
+ ### Client Configuration
42
+
43
+ #### Claude Desktop / Claude Code
44
+
45
+ Add to your MCP configuration (`claude_desktop_config.json` or `.mcp.json`):
46
+
47
+ ```json
48
+ {
49
+ "mcpServers": {
50
+ "foundryvtt": {
51
+ "command": "bunx",
52
+ "args": ["foundryvtt-mcp"],
53
+ "env": {
54
+ "FOUNDRY_URL": "http://localhost:30000",
55
+ "FOUNDRY_USERNAME": "your_username",
56
+ "FOUNDRY_PASSWORD": "your_password"
57
+ }
58
+ }
59
+ }
60
+ }
61
+ ```
62
+
63
+ #### VS Code
64
+
65
+ Add to your VS Code MCP settings:
66
+
67
+ ```json
68
+ {
69
+ "servers": {
70
+ "foundryvtt": {
71
+ "command": "bunx",
72
+ "args": ["foundryvtt-mcp"],
73
+ "env": {
74
+ "FOUNDRY_URL": "http://localhost:30000",
75
+ "FOUNDRY_USERNAME": "your_username",
76
+ "FOUNDRY_PASSWORD": "your_password"
77
+ }
78
+ }
79
+ }
80
+ }
81
+ ```
82
+
83
+ ### Development Setup
84
+
85
+ For local development or contributing:
86
+
87
+ ```bash
88
+ git clone https://github.com/laurigates/foundryvtt-mcp.git
28
89
  cd foundryvtt-mcp
29
- npm install
30
- npm run setup-wizard
90
+ bun install
91
+ bun run setup-wizard
31
92
  ```
32
93
 
33
94
  The setup wizard will detect your FoundryVTT server, test connectivity, and generate your `.env` configuration.
34
95
 
35
96
  To configure manually, see the [Configuration Guide](docs/guides/configuration.md).
36
97
 
98
+ ## Environment Variables
99
+
100
+ | Variable | Required | Description |
101
+ |----------|----------|-------------|
102
+ | `FOUNDRY_URL` | Yes | FoundryVTT server URL (e.g., `http://localhost:30000`) |
103
+ | `FOUNDRY_USERNAME` | Yes | FoundryVTT user account |
104
+ | `FOUNDRY_PASSWORD` | Yes | FoundryVTT user password |
105
+ | `FOUNDRY_USER_ID` | No | Bypass username-to-ID resolution |
106
+ | `FOUNDRY_API_KEY` | No | REST API module key (enables diagnostics tools) |
107
+ | `LOG_LEVEL` | No | `debug`, `info`, `warn`, or `error` (default: `info`) |
108
+ | `FOUNDRY_TIMEOUT` | No | Request timeout in ms (default: `10000`) |
109
+
37
110
  ## Usage
38
111
 
39
112
  Ask your AI assistant things like:
@@ -94,23 +167,25 @@ Ask your AI assistant things like:
94
167
  - `foundry://world/settings` — world and campaign settings
95
168
  - `foundry://system/diagnostics` — system diagnostics (requires REST API module)
96
169
 
97
- ## Configuration
98
-
99
- Copy `.env.example`, set `FOUNDRY_URL`, `FOUNDRY_USERNAME`, and `FOUNDRY_PASSWORD`, then run `npm run build && npm start`.
100
-
101
- Full environment variable reference: [Configuration Guide](docs/guides/configuration.md)
102
-
103
170
  ## Troubleshooting
104
171
 
105
172
  ```bash
106
- npm run test-connection # Test FoundryVTT connectivity
107
- npm run setup-wizard # Re-run interactive setup
173
+ bunx foundryvtt-mcp test-connection # Test FoundryVTT connectivity
174
+ bunx foundryvtt-mcp setup-wizard # Re-run interactive setup
108
175
  ```
109
176
 
110
177
  Detailed guide: [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
111
178
 
112
179
  ## Development
113
180
 
181
+ ```bash
182
+ bun run build # Compile TypeScript
183
+ bun run dev # Development mode with hot reload
184
+ bun test # Unit tests (Vitest)
185
+ bun run test:e2e # E2E tests (Playwright)
186
+ bun run lint # Lint code (Biome)
187
+ ```
188
+
114
189
  See [Development Guide](docs/guides/development.md) for project structure, adding tools, testing, and building.
115
190
 
116
191
  ## Roadmap
@@ -121,10 +196,6 @@ See [Feature Tracker](docs/blueprint/feature-tracker.md) for completed and plann
121
196
 
122
197
  See [CONTRIBUTING.md](CONTRIBUTING.md).
123
198
 
124
- ## Integration
125
-
126
- See [Integration Guide](docs/guides/integration.md) for Claude Desktop config and custom MCP client examples.
127
-
128
199
  ## License
129
200
 
130
201
  MIT License — see [LICENSE](LICENSE) for details.
package/package.json CHANGED
@@ -1,8 +1,11 @@
1
1
  {
2
2
  "name": "foundryvtt-mcp",
3
- "version": "0.11.0",
3
+ "version": "1.0.0",
4
4
  "description": "Model Context Protocol server for FoundryVTT integration",
5
5
  "main": "dist/index.js",
6
+ "bin": {
7
+ "foundryvtt-mcp": "dist/index.js"
8
+ },
6
9
  "type": "module",
7
10
  "scripts": {
8
11
  "build": "tsc",