src/
├── config/ # Zod-validated configuration
├── foundry/
│ ├── auth.ts # Socket.IO 4-step authentication
│ ├── client.ts # FoundryVTT client with worldData cache
│ └── types.ts # TypeScript interfaces + WorldData
├── tools/
│ ├── definitions.ts # Tool schemas by category
│ ├── router.ts # Tool request routing
│ ├── resources.ts # MCP resource definitions
│ └── handlers/ # Per-tool handler implementations
├── diagnostics/ # Optional REST API diagnostics
├── utils/ # Logger, cache utilities
└── index.ts # MCP server entry point
- Define tool schema in
src/tools/definitions.ts - Add handler in
src/tools/handlers/ - Wire the handler in
src/tools/router.ts - Add TypeScript types in
src/foundry/types.tsif needed - Test with your AI assistant
# Unit tests
npm test
# Watch mode
npm run test:watch
# Coverage report
npm run test:coverage
# Lint code
npm run lint
# E2E tests (requires running FoundryVTT)
npm run test:e2eTwo smoke tests verify the server boots end-to-end without a live FoundryVTT. They run in CI on every PR and catch failure modes that the mocked Vitest suite cannot:
npm run smoke # Spawn dist/index.js, verify the startup banner on stderr
npm run smoke:pack # npm pack -> install into a fresh consumer -> verify bannersmoke covers construction-time and import-time regressions (SDK shape
changes, ESM resolution). smoke:pack additionally validates that the
package.json files glob ships every runtime path the entrypoint needs —
the kind of regression that only surfaces for users running npx foundryvtt-mcp
or bunx foundryvtt-mcp, not for anyone running the source tree.
# Development build
npm run build
# Clean build
npm run clean && npm run build
# Development mode with hot reload
npm run devComplete API documentation is auto-generated from TypeScript source code and JSDoc comments.
npm run docs # Generate documentation into build/docs/ (gitignored)
npm run docs:serve # Generate and serve locally- FoundryClient API — complete client documentation with examples
- TypeScript Interfaces — all data structures and type definitions
- Configuration — environment variables and setup options
- Utilities — helper functions and logging
- Usage Examples — code samples for common operations
The documentation is automatically updated via GitHub Actions when source code changes.