@getgameframe/mcp

MCP server for Gameframe — connect AI coding tools to your game design vault.

Works with Claude Code, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible client. The server runs locally, talks to the Gameframe v2 API over HTTPS, and exposes your vault's documents, versions, branches, entities, and merge requests to your AI assistant.

This is a read-only server. It never modifies your vault.

Setup

1. Create an API token

Open Gameframe -> Settings -> API Tokens (/app/settings/api-tokens) and create a Personal Access Token. Gameframe tokens are vault-scoped: when you create a token you select the vault(s) it can access and the permission level (read, write, or admin). For this server, a token with read scope on the vault(s) you want to expose is sufficient.

Tokens start with gf_ak_ and are shown exactly once. Copy it immediately.

2. Configure your AI tool

Add the server to your project's .mcp.json (or your client's MCP config):

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

3. Optional: set a default vault

If you work primarily in one vault, set GAMEFRAME_DEFAULT_VAULT_ID so you don't have to pass vault_id on every call:

{
  "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.

Configuration

| Variable | Required | Description | | ---------------------------- | -------- | --------------------------------------------------------- | | GAMEFRAME_API_TOKEN | Yes | Personal access token (starts with gf_ak_) | | GAMEFRAME_API_URL | No | API base URL (defaults to https://api.getgameframe.com) | | GAMEFRAME_DEFAULT_VAULT_ID | No | Default vault ID for vault-scoped tools |

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

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

Resolution order: environment variables > config file.

Available tools

All tools are read-only.

Vaults

• gameframe_list_vaults — List all vaults the token can access (id, name, counts).

Documents

• gameframe_list_documents — List documents in a vault (cursor-paginated).
• gameframe_get_document_content — Read a document's body (current or a specific version).
• gameframe_search_documents — Search documents by name within a vault.

Versions

• gameframe_get_version_history — List a document's version history (cursor-paginated).

Branches

• gameframe_list_branches — List branches for a document.

Entities

• gameframe_get_document_entities — Get cached AI-extracted entities and relationships for a document (read-only; does not trigger a parse or consume AI credits).
• gameframe_search_entities — Search AI-extracted entities across a vault.

Merge requests

• gameframe_list_merge_requests — List merge requests (proposed design changes) in a vault, optionally filtered by status.

Resources

• gameframe://vault/{id}/tree — A flat, name-keyed index of every document in a vault.

Not yet supported

The following were considered but are not implemented, because the v2 Gameframe API does not currently expose a compatible endpoint:

• Version comparison / diff — there is no public two-version diff endpoint. Diffs exist only inside the merge-request flow.
• Write operations (create version, create document, create change request) — document writes in v2 are content-hash + multipart uploads and branch-based merge requests, not free-text JSON posts. A faithful write surface needs dedicated API support and is deferred.

Tools are only shipped when their backing endpoint exists. This server will never call an endpoint that is not part of the v2 API.

Requirements

• Node.js 22+
• A Gameframe account with at least one vault and a vault-scoped read token

Versioning note

Versions up to and including 0.2.0 on npm were the legacy Gameframe v1 server. From 0.3.0 onward this package is the rewritten server in the gameframe-v2 monorepo, targeting the Gameframe v2 API exclusively. If you are upgrading from 0.2.0: the write tools (create_document, create_version, create_change_request) and compare_versions are gone (see "Not yet supported"), and authentication now uses vault-scoped gf_ak_ personal access tokens.

Publishing

This package is published to npm as @getgameframe/mcp. Publishing is a manual maintainer step — it is intentionally not run by CI or any automated process.

To publish a release:

pnpm --filter @getgameframe/mcp build   # emit dist/
cd packages/mcp
npm publish --access public             # manual; requires npm auth with publish access to @getgameframe

License

MIT