happy-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jared Spencer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# happy-mcp-server
+
+An MCP (Model Context Protocol) server that lets AI assistants observe and control active Happy Coder sessions. It connects to the Happy relay server via end-to-end encrypted channels, enabling remote session monitoring, message sending, permission management, and session control.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm i -g happy-mcp-server
+```
+
+### 2. Authenticate
+
+```bash
+happy-mcp auth
+```
+
+Scan the QR code with the Happy mobile app to pair your account.
+
+### 3. Configure Your MCP Client
+
+Add `happy-mcp` to your MCP client configuration. See [MCP Configuration](#mcp-configuration) below.
+
+## Configuration
+
+Environment variables customize server behavior:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `HAPPY_SERVER_URL` | `https://api.cluster-fluster.com` | Happy relay server URL. |
+| `HAPPY_MCP_COMPUTERS` | `os.hostname()` | Comma-separated list of computer hostnames to filter sessions and machines. Use `*` to show all computers. |
+| `HAPPY_MCP_PROJECT_PATHS` | `process.cwd()` | Comma-separated list of project path prefixes to filter sessions. Use `*` to show all paths. |
+| `HAPPY_MCP_LOG_LEVEL` | `warn` | Log level: `debug`, `info`, `warn`, or `error`. Logs are written to stderr. |
+| `HAPPY_MCP_ENABLE_START` | `true` | Set to `false` to disable the `start_session` tool. |
+
+## MCP Configuration
+
+<details>
+<summary><b>Claude Code</b></summary>
+
+Add to `.mcp.json` in your project root or configure via CLI:
+
+```bash
+claude mcp add --transport stdio happy -- happy-mcp
+```
+
+Or manually add to `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "happy": {
+      "type": "stdio",
+      "command": "happy-mcp"
+    }
+  }
+}
+```
+
+**With custom environment variables:**
+
+```json
+{
+  "mcpServers": {
+    "happy": {
+      "type": "stdio",
+      "command": "happy-mcp",
+      "env": {
+        "HAPPY_MCP_COMPUTERS": "*",
+        "HAPPY_MCP_PROJECT_PATHS": "*"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Claude Desktop</b></summary>
+
+Add to your Claude Desktop config:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "happy": {
+      "type": "stdio",
+      "command": "happy-mcp"
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
+
+Add to `.cursor/mcp.json` in your project or global config:
+
+```json
+{
+  "mcpServers": {
+    "happy": {
+      "command": "happy-mcp"
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Windsurf</b></summary>
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "happy": {
+      "command": "happy-mcp"
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>VS Code with Continue</b></summary>
+
+Add to `~/.continue/config.json`:
+
+```json
+{
+  "experimental": {
+    "modelContextProtocolServers": [
+      {
+        "transport": {
+          "type": "stdio",
+          "command": "happy-mcp"
+        }
+      }
+    ]
+  }
+}
+```
+
+</details>
+
+## License
+
+MIT

package/dist/api/client.d.ts

@@ -0,0 +1,39 @@
+import type { Credentials } from '../auth/crypto.js';
+import type { Config } from '../config.js';
+import type { RawSession, RawMachine } from '../session/types.js';
+export declare class ApiClient {
+    private http;
+    private credentials;
+    private config;
+    constructor(credentials: Credentials, config: Config);
+    get token(): string;
+    listActiveSessions(): Promise<RawSession[]>;
+    listMachines(): Promise<RawMachine[]>;
+    getSessionMessages(sessionId: string, afterSeq?: number, limit?: number): Promise<{
+        messages: Array<{
+            id: string;
+            seq: number;
+            content: {
+                t: string;
+                c: string;
+            };
+            localId?: string;
+            createdAt: number;
+            updatedAt: number;
+        }>;
+        hasMore: boolean;
+    }>;
+    sendMessages(sessionId: string, messages: Array<{
+        content: string;
+        localId: string;
+    }>): Promise<{
+        messages: Array<{
+            id: string;
+            seq: number;
+            localId: string;
+            createdAt: number;
+            updatedAt: number;
+        }>;
+    }>;
+    deleteSession(sessionId: string): Promise<void>;
+}

package/dist/api/client.js

@@ -0,0 +1,49 @@
+import axios from 'axios';
+import { refreshToken } from '../auth/refresh.js';
+export class ApiClient {
+    http;
+    credentials;
+    config;
+    constructor(credentials, config) {
+        this.credentials = credentials;
+        this.config = config;
+        this.http = axios.create({
+            baseURL: config.serverUrl,
+            headers: { Authorization: `Bearer ${credentials.token}` },
+            timeout: 30_000,
+        });
+        // 401 interceptor for automatic token refresh
+        this.http.interceptors.response.use(undefined, async (error) => {
+            if (error.response?.status === 401 && !error.config._retried) {
+                error.config._retried = true;
+                const newToken = await refreshToken(this.credentials, this.config);
+                this.http.defaults.headers.common['Authorization'] = `Bearer ${newToken}`;
+                error.config.headers['Authorization'] = `Bearer ${newToken}`;
+                return this.http.request(error.config);
+            }
+            throw error;
+        });
+    }
+    get token() {
+        return this.credentials.token;
+    }
+    async listActiveSessions() {
+        const res = await this.http.get('/v2/sessions/active');
+        return res.data.sessions ?? res.data ?? [];
+    }
+    async listMachines() {
+        const res = await this.http.get('/v1/machines');
+        return res.data ?? [];
+    }
+    async getSessionMessages(sessionId, afterSeq = 0, limit = 100) {
+        const res = await this.http.get(`/v3/sessions/${encodeURIComponent(sessionId)}/messages`, { params: { after_seq: afterSeq, limit } });
+        return res.data;
+    }
+    async sendMessages(sessionId, messages) {
+        const res = await this.http.post(`/v3/sessions/${encodeURIComponent(sessionId)}/messages`, { messages }, { timeout: 60_000 });
+        return res.data;
+    }
+    async deleteSession(sessionId) {
+        await this.http.delete(`/v1/sessions/${encodeURIComponent(sessionId)}`);
+    }
+}

package/dist/auth/credentials.d.ts

@@ -0,0 +1,22 @@
+import type { Credentials } from './crypto.js';
+export type { Credentials } from './crypto.js';
+/**
+ * Read credentials from disk.
+ * Returns null if file doesn't exist or is invalid.
+ * Derives contentKeyPair from secret on load.
+ */
+export declare function readCredentials(path: string): Credentials | null;
+/**
+ * Write credentials to disk with 0600 permissions.
+ * Creates parent directory with 0700 if needed.
+ */
+export declare function writeCredentials(path: string, token: string, secret: Uint8Array, serverUrl?: string): void;
+/**
+ * Validate that credentials file has safe permissions (0600).
+ * Throws if group or world readable.
+ */
+export declare function validateFilePermissions(path: string): void;
+/**
+ * Remove credentials file.
+ */
+export declare function clearCredentials(path: string): void;

package/dist/auth/credentials.js

@@ -0,0 +1,80 @@
+import { readFileSync, writeFileSync, mkdirSync, statSync, unlinkSync } from 'fs';
+import { dirname } from 'path';
+import { encodeBase64, decodeBase64, deriveContentKeyPair } from './crypto.js';
+import { logger } from '../logger.js';
+/**
+ * Read credentials from disk.
+ * Returns null if file doesn't exist or is invalid.
+ * Derives contentKeyPair from secret on load.
+ */
+export function readCredentials(path) {
+    try {
+        const raw = readFileSync(path, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed.token || !parsed.secret) {
+            logger.warn('Credentials file missing token or secret');
+            return null;
+        }
+        const secret = decodeBase64(parsed.secret);
+        if (secret.length !== 32) {
+            logger.warn('Credentials secret is not 32 bytes');
+            return null;
+        }
+        const contentKeyPair = deriveContentKeyPair(secret);
+        return { token: parsed.token, secret, contentKeyPair };
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return null; // File doesn't exist, first run
+        }
+        logger.warn('Failed to read credentials:', err.message);
+        return null;
+    }
+}
+/**
+ * Write credentials to disk with 0600 permissions.
+ * Creates parent directory with 0700 if needed.
+ */
+export function writeCredentials(path, token, secret, serverUrl) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const data = JSON.stringify({
+        token,
+        secret: encodeBase64(secret),
+        ...(serverUrl ? { serverUrl } : {}),
+        pairedAt: new Date().toISOString(),
+    }, null, 2);
+    writeFileSync(path, data, { mode: 0o600 });
+    logger.info('Credentials written to', path);
+}
+/**
+ * Validate that credentials file has safe permissions (0600).
+ * Throws if group or world readable.
+ */
+export function validateFilePermissions(path) {
+    try {
+        const stat = statSync(path);
+        const mode = stat.mode & 0o777;
+        if (mode & 0o077) {
+            throw new Error(`Credentials file ${path} has unsafe permissions ${mode.toString(8)}. ` +
+                `Expected 0600. Fix with: chmod 600 ${path}`);
+        }
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+}
+/**
+ * Remove credentials file.
+ */
+export function clearCredentials(path) {
+    try {
+        unlinkSync(path);
+        logger.info('Credentials cleared');
+    }
+    catch {
+        // ignore if doesn't exist
+    }
+}

package/dist/auth/crypto.d.ts

@@ -0,0 +1,118 @@
+import nacl from 'tweetnacl';
+export declare function encodeBase64(buf: Uint8Array): string;
+export declare function decodeBase64(base64: string): Uint8Array;
+export declare function encodeBase64Url(buf: Uint8Array): string;
+export declare function decodeBase64Url(base64url: string): Uint8Array;
+export declare function hmacSha512(key: Uint8Array, data: Uint8Array): Uint8Array;
+interface KeyTreeState {
+    key: Uint8Array;
+    chainCode: Uint8Array;
+}
+/**
+ * Derive root of key tree.
+ * CRITICAL: key = encode(usage + ' Master Seed'), data = seed
+ * Verified against upstream: packages/happy-agent/src/encryption.ts
+ */
+export declare function deriveSecretKeyTreeRoot(seed: Uint8Array, usage: string): KeyTreeState;
+/**
+ * Derive child key from chain code.
+ * data = [0x00, ...encode(index)]
+ */
+export declare function deriveSecretKeyTreeChild(chainCode: Uint8Array, index: string): KeyTreeState;
+/**
+ * Derive key at path. Root + iterate children.
+ * Test vectors:
+ *   deriveKey(encode("test seed"), "test usage", [])
+ *     => E6E55652456F9FE47D6FF46CA3614E85B499F77E7B340FBBB1553307CEDC1E74
+ *   deriveKey(encode("test seed"), "test usage", ["child1", "child2"])
+ *     => 1011C097D2105D27362B987A631496BBF68B836124D1D072E9D1613C6028CF75
+ */
+export declare function deriveKey(seed: Uint8Array, usage: string, path: string[]): Uint8Array;
+/**
+ * CRITICAL: Has a SHA-512 step to match libsodium's crypto_box_seed_keypair behavior.
+ * 1. Derive seed via HMAC tree
+ * 2. SHA-512(seed)[0:32] = box secret key
+ * 3. nacl.box.keyPair.fromSecretKey(boxSecretKey)
+ *
+ * Source: packages/happy-agent/src/encryption.ts:deriveContentKeyPair
+ */
+export declare function deriveContentKeyPair(secret: Uint8Array): nacl.BoxKeyPair;
+/**
+ * Generate auth challenge for token refresh.
+ * CRITICAL: Uses nacl.sign.keyPair.fromSeed(secret) with the RAW account secret.
+ * NOT the derived content keypair (which is Curve25519, not Ed25519).
+ *
+ * Source: packages/happy-agent/src/encryption.ts:authChallenge
+ */
+export declare function authChallenge(secret: Uint8Array): {
+    challenge: Uint8Array;
+    publicKey: Uint8Array;
+    signature: Uint8Array;
+};
+/**
+ * Decrypt a NaCl box bundle: [ephemeralPubKey(32)][nonce(24)][ciphertext]
+ * Returns decrypted Uint8Array or null on failure.
+ *
+ * Source: packages/happy-agent/src/encryption.ts
+ */
+export declare function decryptBoxBundle(bundle: Uint8Array, recipientSecretKey: Uint8Array): Uint8Array | null;
+/**
+ * Encrypt data for a public key using NaCl box.
+ * Returns: [ephemeralPubKey(32)][nonce(24)][ciphertext]
+ */
+export declare function encryptForPublicKey(data: Uint8Array, recipientPublicKey: Uint8Array): Uint8Array;
+/**
+ * Encrypt with AES-256-GCM.
+ * Bundle format: [version(1)=0x00][nonce(12)][ciphertext(N)][authTag(16)]
+ */
+export declare function encryptAesGcm(key: Uint8Array, data: unknown): Uint8Array;
+/**
+ * Decrypt AES-256-GCM bundle.
+ * Returns parsed JSON or null on failure.
+ */
+export declare function decryptAesGcm(key: Uint8Array, bundle: Uint8Array): unknown | null;
+/**
+ * Encrypt with NaCl SecretBox.
+ * Bundle format: [nonce(24)][ciphertext]
+ */
+export declare function encryptSecretBox(key: Uint8Array, data: unknown): Uint8Array;
+/**
+ * Decrypt NaCl SecretBox bundle.
+ * Returns parsed JSON or null on failure.
+ */
+export declare function decryptSecretBox(key: Uint8Array, bundle: Uint8Array): unknown | null;
+export type EncryptionVariant = 'dataKey' | 'legacy';
+export interface SessionEncryption {
+    key: Uint8Array;
+    variant: EncryptionVariant;
+}
+/**
+ * Encrypt data using the appropriate variant.
+ */
+export declare function encrypt(key: Uint8Array, variant: EncryptionVariant, data: unknown): Uint8Array;
+/**
+ * Decrypt data using the appropriate variant.
+ */
+export declare function decrypt(key: Uint8Array, variant: EncryptionVariant, bundle: Uint8Array): unknown | null;
+/**
+ * Encrypt data and return base64 string.
+ */
+export declare function encryptToBase64(encryption: SessionEncryption, data: unknown): string;
+/**
+ * Decrypt base64-encoded data.
+ */
+export declare function decryptFromBase64(encryption: SessionEncryption, base64: string): unknown | null;
+export interface Credentials {
+    token: string;
+    secret: Uint8Array;
+    contentKeyPair: nacl.BoxKeyPair;
+}
+/**
+ * Resolve session encryption key.
+ * CRITICAL: Strip version byte (first byte) before NaCl box decryption.
+ * Pass contentKeyPair.secretKey, NOT the full keypair.
+ *
+ * Source: packages/happy-agent/src/api.ts:resolveSessionEncryption
+ */
+export declare function resolveSessionEncryption(dataEncryptionKey: string | null | undefined, credentials: Credentials): SessionEncryption;
+export {};