@cubelife/sdk 0.1.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # @cubelife/sdk
 
-Node.js SDK for CubeLife. Give your AI agent a living pixel-art character.
+Give your AI agent a living pixel-art character. Characters mirror agent state in real time, live in rooms, and have emotions.
 
 ## Install
 
@@ -15,16 +15,23 @@ import { CubeLifeClient } from '@cubelife/sdk';
 
 const client = new CubeLifeClient({ apiKey: 'your-agent-api-key' });
 
-// Report what your agent is doing
 await client.report('coding', { detail: 'Building the login page', sentiment: 'positive' });
-
-// Update progress
 await client.report('coding', { detail: 'Building the login page', progress: 0.5 });
-
-// Mark complete
 await client.report('complete', { detail: 'Login page shipped' });
 ```
 
+Your character appears at [life.cubeworld.co.za](https://life.cubeworld.co.za), in the desktop companion, or embedded in your own app via `<iframe>`.
+
+## MCP Server
+
+If you use Claude Code, Cursor, Windsurf, or any MCP-compatible tool, you can skip the SDK and use the CLI's built-in MCP server instead:
+
+```bash
+npx cubelife setup claude-code   # auto-configures MCP
+```
+
+The MCP server exposes `cubelife_report`, `cubelife_complete`, `cubelife_error`, and `cubelife_status` tools. See the [cubelife CLI](https://www.npmjs.com/package/cubelife) package.
+
 ## API
 
 ### `CubeLifeClient`
@@ -37,8 +44,8 @@ const client = new CubeLifeClient({ apiKey: 'your-key' });
 
 **Methods:**
 
-- `report(state, options?)` - Report agent state (`coding`, `reading`, `researching`, `designing`, `testing`, `reviewing`, `thinking`, `writing`, `error`, `complete`, `waiting`, `awaiting_input`)
-- `getState()` - Get current agent state
+- `report(state, options?)` - Report agent state
+- `getState()` - Get current agent state (returns sleeping status)
 - `navigate(destination)` - Move agent to a different room
 - `customise(options)` - Update character appearance (outfit, skin tone, accessories)
 - `setCreature(type)` - Switch agent to a creature form

package/dist/client.d.ts

@@ -26,8 +26,16 @@ interface AgentState {
     detail: string | null;
     progress: number | null;
     sentiment: Sentiment | null;
+    sleeping: boolean;
     updatedAt: number | null;
 }
+interface ReportResponse {
+    ok: boolean;
+    sleeping: boolean;
+    wokeUp: boolean;
+    burst?: boolean;
+    burstSparksRemaining?: number;
+}
 interface CubeLifeOptions {
     apiKey: string;
     baseUrl?: string;
@@ -45,19 +53,19 @@ export declare class CubeLifeClient {
     private readonly baseUrl;
     constructor(opts: CubeLifeOptions);
     getState(): Promise<AgentState>;
-    report(state: WorkState, opts?: ReportOptions): Promise<void>;
-    coding(detail?: string, progress?: number): Promise<void>;
-    reading(detail?: string): Promise<void>;
-    researching(detail?: string): Promise<void>;
-    designing(detail?: string): Promise<void>;
-    testing(detail?: string, progress?: number): Promise<void>;
-    reviewing(detail?: string): Promise<void>;
-    thinking(detail?: string): Promise<void>;
-    writing(detail?: string): Promise<void>;
-    error(detail?: string): Promise<void>;
-    complete(detail?: string): Promise<void>;
-    waiting(detail?: string): Promise<void>;
-    awaitingInput(detail?: string): Promise<void>;
+    report(state: WorkState, opts?: ReportOptions): Promise<ReportResponse>;
+    coding(detail?: string, progress?: number): Promise<ReportResponse>;
+    reading(detail?: string): Promise<ReportResponse>;
+    researching(detail?: string): Promise<ReportResponse>;
+    designing(detail?: string): Promise<ReportResponse>;
+    testing(detail?: string, progress?: number): Promise<ReportResponse>;
+    reviewing(detail?: string): Promise<ReportResponse>;
+    thinking(detail?: string): Promise<ReportResponse>;
+    writing(detail?: string): Promise<ReportResponse>;
+    error(detail?: string): Promise<ReportResponse>;
+    complete(detail?: string): Promise<ReportResponse>;
+    waiting(detail?: string): Promise<ReportResponse>;
+    awaitingInput(detail?: string): Promise<ReportResponse>;
     moveTo(roomId: string, zone?: string): Promise<void>;
     /** World-product only. Returns 403 for life projects. */
     navigateTo(worldRoomId: string, zone?: string): Promise<NavigationResult>;
@@ -65,4 +73,4 @@ export declare class CubeLifeClient {
 }
 type AgentForm = 'human' | 'creature';
 type HairStyle = 'none' | 'short' | 'long' | 'curly' | 'ponytail' | 'mohawk';
-export type { WorkState, Sentiment, ReportOptions, CubeLifeOptions, CharacterOptions, OutfitStyle, AccessoryStyle, NavigationResult, AgentState, AgentForm, HairStyle };
+export type { WorkState, Sentiment, ReportOptions, ReportResponse, CubeLifeOptions, CharacterOptions, OutfitStyle, AccessoryStyle, NavigationResult, AgentState, AgentForm, HairStyle };

package/dist/client.js

@@ -67,6 +67,7 @@ class CubeLifeClient {
             const err = await res.json().catch(() => ({}));
             throwApiError(res.status, err.error || 'Unknown error');
         }
+        return res.json();
     }
     async coding(detail, progress) {
         return this.report('coding', { detail, progress });

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { CubeLifeClient, CubeLifeError, RateLimitError } from './client';
-export type { WorkState, Sentiment, ReportOptions, CubeLifeOptions, CharacterOptions, OutfitStyle, AccessoryStyle, NavigationResult, AgentState, AgentForm, HairStyle, } from './client';
+export type { WorkState, Sentiment, ReportOptions, ReportResponse, CubeLifeOptions, CharacterOptions, OutfitStyle, AccessoryStyle, NavigationResult, AgentState, AgentForm, HairStyle, } from './client';
 export { CubeLifeAdmin } from './admin';
 export type { CubeLifeAdminOptions, AuthTokens, Project, Agent, Character, CreatureTraits, Personality, Room, ChestItem, Possession, Neighbourhood, WorldRoom, } from './admin';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubelife/sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "SDK for CubeLife — give your AI agent a living pixel-art character",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,7 +20,14 @@
     "agent",
     "pixel-art",
     "character",
-    "visualization"
+    "visualization",
+    "mcp",
+    "mcp-server",
+    "developer-tools",
+    "companion",
+    "claude",
+    "cursor",
+    "copilot"
   ],
   "license": "MIT",
   "repository": {