@dfinity/caffeine-mcp-server

@dfinity/caffeine-mcp-server

MCP (Model Context Protocol) server for Caffeine AI tools. This package provides a set of tools for interacting with Caffeine AI projects through the Model Context Protocol.

Features

• Deploy projects to public domains
• Manage project files (push/pull)
• Set project names
• Create new projects
• Get project information
• And more...

Configuration [BETA]

1. Get invitation code to Caffeine AI

2. Generating your API Key here

3.1. MCP Server setup - Automatic (Cline)

Modify your API Provider in Cline's settings.

• API Provider: OpenAI Compatible
• Base URL: https://beta.caffeine.ai
• API Key: {your_api_key}
• Model ID: NA

3.2. MCP Server setup - Manual (Cline or Claude Desktop)

Add this to your cline_mcp_settings.json or claude_desktop_config.json:

{
  "mcpServers": {
    "@dfinity/caffeine-mcp-server": {
      "command": "npx",
      "args": [
        "@dfinity/caffeine-mcp-server"
      ],
      "env": {
        "CAFFEINE_API_KEY": "{your_api_key}",
        "CAFFEINE_BASE_URL": "https://beta.caffeine.ai"
      },
      "autoApprove": [
        "deploy",
        "get_projects",
        "get_project_metadata"
      ]
    }
  }
}

Available Tools

create_project

Create a new project with an initial prompt. The workspace folder handling depends on its current state:

• Empty folder: Uses the current workspace directly
• Caffeine project: Creates a sibling folder (requires folderName)
• Non-empty folder: Creates a subfolder (requires folderName)

Inputs:

• workspaceFolder (string, required): The root folder where the project will be created
• initialPrompt (string, required): The initial prompt to create the project with
• folderName (string, optional): Name for the new project folder (required if workspace is not empty)

Response:

{
  projectId: string;  // UUID of created project
}

Important Notes:

• If the workspace is not empty or contains a Caffeine project, you must provide a folderName
• For Caffeine projects, the new folder is created next to the current workspace
• For non-empty folders, the new folder is created inside the current workspace

deploy

Deploy the project to a public domain (lasts 45 minutes)

Inputs:

• workspaceFolder (string, required): The root folder of the local copy of the caffeine project. The folder must contain a caffeine.json file with a projectId.

Response:

{
  ok?: {
    url: string,           // Public URL where project is deployed
    output: {
      frontend_canister_id: string,  // Frontend canister identifier
      frontend_timestamp: string,    // Frontend deployment timestamp
      backend_canister_id: string,   // Backend canister identifier
      backend_timestamp: string      // Backend deployment timestamp
    },
    github?: {              // Optional GitHub deployment info
      githubId: number,    // GitHub repository ID
      githubHtmlUrl: string // GitHub repository URL
    },
    saveFailed?: boolean    // Whether saving deployment info failed
  },
  error?: {
    message: string,
    code: DeployErrorCode,
    location: "frontend" | "backend" | "github" | "general"
  }
}

Important Notes:

• Only deploys files that are on the caffeine server
• To deploy local changes, push files first using push_files

download

Download a project. The workspace folder handling follows the same rules as create_project:

• Empty folder: Uses the current workspace directly
• Caffeine project: Creates a sibling folder (requires folderName)
• Non-empty folder: Creates a subfolder (requires folderName)

Inputs:

• projectId (string, required): The ID of the project to download
• workspaceFolder (string, required): The target folder where the project will be downloaded
• folderName (string, optional): Name for the new project folder (required if workspace is not empty)
• clone (boolean, required): If true, creates a copy of the project before downloading. Must be true if the project is not owned by the user.

Important Notes:

• If the workspace is not empty or contains a Caffeine project, you must provide a folderName
• For Caffeine projects, the new folder is created next to the current workspace
• For non-empty folders, the new folder is created inside the current workspace

get_project

Get full project details including files and the whole event log ("Initialize", "Prompt", "Deploy").

Inputs:

• workspaceFolder (string, required): The root folder of the local copy of the caffeine project. The folder must contain a caffeine.json file with a projectId.

get_project_metadata

Get metadata for the current project. This includes the initalPrompt, a url to the caffeine web chat of the project and last modification information.

Inputs:

• workspaceFolder (string, required): The root folder of the local copy of the caffeine project. The folder must contain a caffeine.json file with a projectId.

Important Notes:

• Prefer this tool over get_project if the desired information is available here. This response is much smaller

get_projects

Get a list of projects (own or featured)

Inputs:

• type (enum, required): Type of projects to fetch ('own' or 'featured')

Response:

{
  count: string,            // Number of projects in current page
  countTotal: string,       // Total number of projects
  rows: Array<{
    id: string,           // Project ID
    name: string,         // Project name
    userId: string,       // Owner's user ID
    featured: boolean,    // Whether project is featured
    initialPrompt: string, // Initial prompt used to create project
    backendCanisterId: string, // Backend canister ID
    frontendCanisterId: string, // Frontend canister ID
    deploymentCount: number,    // Number of deployments
    githubUrl: string | null,   // Associated GitHub URL
    deploymentUrl: string | null, // Current deployment URL
    url: string | null,          // Project URL
    category: string,            // Project category
    systemPrompt: string,        // System prompt configuration
    createdAt: Date             // Creation timestamp
  }>
}

Important Notes:

• 'own' type requires authentication
• 'featured' type returns publicly available projects

pull_files

Pull files from Caffeine server and write them to local workspace

Inputs:

• workspaceFolder (string, required): The root folder of the local copy of the caffeine project. The folder must contain a caffeine.json file with a projectId.
• overwrite_local_changes (boolean, optional): Whether to overwrite local changes

Response:

{
  pulledFiles: string[],    // Array of file paths that were pulled
  metadata: {              // Last modification details after pull
    projectEventId: string, // ID of last modification event
    createdAt: number     // Timestamp of last modification
  }
}

Important Notes:

• Never set overwrite_local_changes to true without explicit user confirmation
• If user agrees to overwrite local changes, set to true once, then false for subsequent calls
• Uses gitignore for file filtering

push_files

Push files from workspace to Caffeine backend

Inputs:

• workspaceFolder (string, required): The root folder of the local copy of the caffeine project. The folder must contain a caffeine.json file with a projectId.

Response:

{
  success: boolean,         // Whether push was successful
  pushedFiles: string[],    // Array of file paths that were pushed
}

Important Notes:

• Automatically filters files using gitignore
• Only pushes modified files since last synchronization

set_project_name

Set the name of the project in the Caffeine API

Inputs:

• workspaceFolder (string, required): The root folder of the local copy of the caffeine project. The folder must contain a caffeine.json file with a projectId.
• name (string, required): The new name for the project

Response:

{
  ok?: {
    projectName: string      // The new name that was set
  },
  error?: string            // Error message if operation failed
}

Development

• Clone the repository
• Install dependencies:

npm install

• Build the project:

npm run build

• Run the MCP inspector for development:

npm run inspector

License

MIT