npm package: @getgameframe/mcp
Description: MCP server for GameFrame — connect AI coding tools to your game design documents
Latest version: 0.2.0

# @getgameframe/mcp

MCP server for [GameFrame](https://getgameframe.com) — connect AI coding tools to your game design documents.

Works with Claude Code, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible client.

## Setup

### 1. Create an API token

Go to [GameFrame Settings > API Tokens](https://getgameframe.com/app/settings/api-tokens) and create a token with **read** scope.

### 2. Configure your AI tool

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "gameframe": {
      "command": "npx",
      "args": ["@getgameframe/mcp"],
      "env": {
        "GAMEFRAME_API_TOKEN": "gf_ak_your_token_here"
      }
    }
  }
}
```

Or for global access across all projects, add to `~/.claude/claude_desktop_config.json`.

### 3. Optional: Set a default vault

If you primarily work with one vault, set `GAMEFRAME_DEFAULT_VAULT_ID` to skip specifying it on every tool call:

```json
{
  "mcpServers": {
    "gameframe": {
      "command": "npx",
      "args": ["@getgameframe/mcp"],
      "env": {
        "GAMEFRAME_API_TOKEN": "gf_ak_...",
        "GAMEFRAME_DEFAULT_VAULT_ID": "your-vault-uuid"
      }
    }
  }
}
```

Find your vault ID by calling `gameframe_list_vaults` or from the URL in the GameFrame web app.

## Configuration

| Variable | Required | Description |
|----------|----------|-------------|
| `GAMEFRAME_API_TOKEN` | Yes | Personal access token (starts with `gf_ak_`) |
| `GAMEFRAME_API_URL` | No | API URL (defaults to production) |
| `GAMEFRAME_DEFAULT_VAULT_ID` | No | Default vault ID for all tool calls |

Alternatively, create `~/.gameframe/config.json`:

```json
{
  "token": "gf_ak_...",
  "defaultVaultId": "optional-vault-uuid"
}
```

Resolution order: environment variables > config file.

## Available Tools

### Vault Discovery
- **gameframe_list_vaults** — List all vaults you have access to

### Documents
- **gameframe_list_documents** — List documents in a vault (filter by file type)
- **gameframe_get_document_content** — Read document content (current or specific version)
- **gameframe_search_documents** — Search documents by title or content

### Version History
- **gameframe_get_version_history** — Get version history for a document
- **gameframe_compare_versions** — Diff two versions of a document

### Branches
- **gameframe_list_branches** — List branches for a document

### Entities
- **gameframe_get_document_entities** — Get AI-extracted entities (characters, items, mechanics)
- **gameframe_search_entities** — Search entities across a vault

### Change Requests
- **gameframe_get_change_requests** — List active change requests (quest log)

### Write Operations (require `write` scope)
- **gameframe_create_version** — Save a new version of a document with a change summary
- **gameframe_create_document** — Create a new document in a vault
- **gameframe_create_change_request** — Log a design change request in the quest log

> Write tools require a PAT with `write` scope. Create one at Settings > API Tokens with both `read` and `write` scopes selected.

## Resources

- **gameframe://vault/{id}/tree** — Browse the document tree of a vault

## Requirements

- Node.js 18+
- A GameFrame account with at least one vault

## License

MIT