happy-mcp-server 1.1.1 → 1.2.0

package/README.md

@@ -92,6 +92,171 @@ Environment variables customize server behavior:
 | `HAPPY_MCP_SESSION_CACHE_TTL` | `300` | Session cache TTL in seconds |
 | `HAPPY_MCP_ENABLE_START` | `true` | Set to `false` to disable the `start_session` tool. |
 
+## Available Tools
+
+When authenticated, happy-mcp-server exposes 11 MCP tools grouped into three categories. When unauthenticated, only the `authentication_status` tool is available to initiate QR-based pairing.
+
+### Tool Summary
+
+| Tool | Category | Description |
+|------|----------|-------------|
+| [`list_computers`](#list_computers) | Discovery | List available computers filtered by `HAPPY_MCP_COMPUTERS` |
+| [`list_sessions`](#list_sessions) | Discovery | List active sessions with status and pending permissions |
+| [`get_session`](#get_session) | Discovery | Get detailed info and recent messages for a session |
+| [`watch_session`](#watch_session) | Discovery | Wait for session state changes (idle, permission pending) |
+| [`send_message`](#send_message) | Session Control | Send a message to a session; optionally change permission mode |
+| [`start_session`](#start_session) | Session Control | Start a new session on a remote machine |
+| [`stop_session`](#stop_session) | Session Control | Stop and archive a running session |
+| [`interrupt_session`](#interrupt_session) | Session Control | Abort current activity without terminating the session |
+| [`approve_permission`](#approve_permission) | Permission Management | Approve a pending permission request |
+| [`deny_permission`](#deny_permission) | Permission Management | Deny a pending permission request |
+| [`answer_question`](#answer_question) | Permission Management | Answer an `AskUserQuestion` prompt from a session |
+
+---
+
+### Discovery Tools
+
+#### `list_computers`
+
+List available computers filtered by `HAPPY_MCP_COMPUTERS`. Shows hostname, online status, and active session count. Use before `start_session` to find available machines.
+
+No parameters.
+
+---
+
+#### `list_sessions`
+
+List all active Happy Coder sessions. Shows session ID, project path, hostname, status (`active`/`idle`/`waiting_permission`), and pending permissions.
+
+Results are pre-filtered by `HAPPY_MCP_COMPUTERS` and `HAPPY_MCP_PROJECT_PATHS` unless those variables are set to `*`.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `filter` | object | No | — | Filter criteria |
+| `filter.status` | enum | No | — | Filter by session status: `active`, `idle`, or `waiting_permission` |
+| `filter.computer` | string | No | — | Filter by computer hostname |
+| `filter.projectPath` | string | No | — | Filter by project path prefix |
+
+---
+
+#### `get_session`
+
+Get detailed information about a specific session including recent messages, metadata, and pending permissions.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `sessionId` | string | Yes | — | Session ID (from `list_sessions`) |
+| `includeMessages` | boolean | No | `true` | Whether to include recent messages |
+| `lastN` | number | No | `20` | Number of recent messages to return |
+| `after` | string | No | — | ISO 8601 timestamp — only return messages after this time |
+
+---
+
+#### `watch_session`
+
+Watch one or more sessions for state changes. Returns immediately if any session is idle or has pending permissions. Otherwise waits up to 5 minutes for a state change. If sessions are still active when the timeout is reached, returns current status — call again to continue watching.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `sessionIds` | string[] | Yes | — | One or more session IDs to watch |
+| `timeoutSeconds` | number | No | `300` | Maximum wait time in seconds |
+
+---
+
+### Session Control Tools
+
+#### `send_message`
+
+Send a message to a Happy Coder session. The message appears as a user message in the session. If the session is actively generating, the message is queued and processed when the session is ready. Can optionally change the permission mode.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `sessionId` | string | Yes | — | Session ID to send the message to |
+| `message` | string | Yes | — | Message text to send |
+| `meta` | object | No | — | Optional metadata |
+| `meta.permissionMode` | enum | No | — | Permission mode: `default`, `acceptEdits`, `bypassPermissions`, `plan`, `read-only`, `safe-yolo`, `yolo` |
+| `meta.allowedTools` | string[] | No | — | Tools to allow |
+| `meta.disallowedTools` | string[] | No | — | Tools to disallow |
+
+---
+
+#### `start_session`
+
+Start a new Happy Coder session on a remote machine. Requires the machine to be online. Use `list_computers` to find available machines.
+
+> Disabled when `HAPPY_MCP_ENABLE_START=false`.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `computer` | string | Yes | — | Machine ID (from `list_computers`) |
+| `projectPath` | string | Yes | — | Working directory for the new session |
+| `initialMessage` | string | No | — | Message to send after the session starts |
+| `permissionMode` | enum | No | — | Permission mode: `default`, `acceptEdits`, `bypassPermissions`, `plan`, `read-only`, `safe-yolo`, `yolo` |
+| `agent` | enum | No | `claude` | AI agent to use: `claude`, `codex`, or `gemini` |
+
+---
+
+#### `stop_session`
+
+Stop and archive a running Happy Coder session. Gracefully terminates the CLI process — the session becomes inactive but its message history is preserved. Use this when you are done with a session and want to free up resources.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `sessionId` | string | Yes | — | Session ID to stop |
+
+---
+
+#### `interrupt_session`
+
+Interrupt a running Claude Code session to stop its current activity. Sends an abort signal equivalent to pressing Escape — the session stays alive and can accept new messages afterward. Use this when a session is actively generating output and you need it to stop.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `sessionId` | string | Yes | — | Session ID to interrupt |
+
+---
+
+### Permission Management Tools
+
+#### `approve_permission`
+
+Approve a pending permission request in a session. Permission requests appear in `get_session` and `watch_session` results.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `sessionId` | string | Yes | — | Session ID |
+| `requestId` | string | Yes | — | Permission request ID to approve, or `"all_pending"` to approve all |
+| `mode` | enum | No | — | Permission mode to set after approval: `default`, `acceptEdits`, `bypassPermissions`, `plan`, `read-only`, `safe-yolo`, `yolo` |
+| `allowTools` | string[] | No | — | List of tools to allow |
+| `decision` | enum | No | `approved` | Approval decision: `approved` or `approved_for_session` |
+
+---
+
+#### `deny_permission`
+
+Deny a pending permission request in a session. Can also abort the entire session.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `sessionId` | string | Yes | — | Session ID |
+| `requestId` | string | Yes | — | Permission request ID to deny |
+| `reason` | string | No | — | Feedback text explaining why the request was denied |
+| `decision` | enum | No | `denied` | Denial type: `denied` or `abort` |
+
+---
+
+#### `answer_question`
+
+Answer a question (`AskUserQuestion`) from a session. Approves the pending permission and sends a user message with the answer.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `sessionId` | string | Yes | — | Session ID |
+| `requestId` | string | Yes | — | Question request ID from pending permissions |
+| `answers` | object | Yes | — | Map of question header to selected answer |
+
+---
+
 ## HTTP Transport
 
 When running `happy-mcp-server serve`, the server exposes MCP over HTTP instead of stdio. This mode is useful for custom clients, testing, or programmatic access.

package/dist/server.js

@@ -9,6 +9,8 @@ import { registerDenyPermission } from './tools/deny_permission.js';
 import { registerAnswerQuestion } from './tools/answer_question.js';
 import { registerStartSession } from './tools/start_session.js';
 import { registerInterruptSession } from './tools/interrupt_session.js';
+import { registerStopSession } from './tools/stop_session.js';
+import { listComputersSchema, listSessionsSchema, getSessionSchema, watchSessionSchema, sendMessageSchema, approvePermissionSchema, denyPermissionSchema, interruptSessionSchema, answerQuestionSchema, startSessionSchema, stopSessionSchema, } from './tools/schemas.js';
 const AUTH_ERROR = {
     isError: true,
     content: [{
@@ -23,15 +25,16 @@ const AUTH_RETRY = {
         }],
 };
 const TOOL_STUBS = [
-    ['list_computers', 'List available computers filtered by HAPPY_MCP_COMPUTERS.'],
-    ['list_sessions', 'List all active Happy Coder sessions.'],
-    ['get_session', 'Get detailed state of a specific session.'],
-    ['watch_session', 'Watch sessions for real-time updates.'],
-    ['send_message', 'Send a message to a session.'],
-    ['approve_permission', 'Approve a pending permission request.'],
-    ['deny_permission', 'Deny a pending permission request.'],
-    ['interrupt_session', 'Interrupt a running session to stop its current activity.'],
-    ['answer_question', 'Answer a question from a session.'],
+    ['list_computers', 'List available computers filtered by HAPPY_MCP_COMPUTERS.', listComputersSchema],
+    ['list_sessions', 'List all active Happy Coder sessions.', listSessionsSchema],
+    ['get_session', 'Get detailed state of a specific session.', getSessionSchema],
+    ['watch_session', 'Watch sessions for real-time updates.', watchSessionSchema],
+    ['send_message', 'Send a message to a session.', sendMessageSchema],
+    ['approve_permission', 'Approve a pending permission request.', approvePermissionSchema],
+    ['deny_permission', 'Deny a pending permission request.', denyPermissionSchema],
+    ['interrupt_session', 'Interrupt a running session to stop its current activity.', interruptSessionSchema],
+    ['stop_session', 'Stop and archive a running session.', stopSessionSchema],
+    ['answer_question', 'Answer a question from a session.', answerQuestionSchema],
 ];
 /**
  * Register all real tool handlers on an McpServer instance.
@@ -46,6 +49,7 @@ export function registerAllTools(server, config, api, relay, sessionManager) {
     registerApprovePermission(server, relay, sessionManager);
     registerDenyPermission(server, relay, sessionManager);
     registerInterruptSession(server, relay, sessionManager);
+    registerStopSession(server, relay, sessionManager);
     registerAnswerQuestion(server, api, relay, sessionManager);
     if (config.enableStart) {
         registerStartSession(server, api, relay, sessionManager, config);
@@ -73,11 +77,11 @@ export function createUnauthenticatedServer(config, onToolCallWhileUnauthenticat
     };
     function registerStubs() {
         stubRegistrations = [];
-        for (const [name, desc] of TOOL_STUBS) {
-            stubRegistrations.push(server.tool(name, desc, {}, stubHandler));
+        for (const [name, desc, schema] of TOOL_STUBS) {
+            stubRegistrations.push(server.tool(name, desc, schema, stubHandler));
         }
         if (config.enableStart) {
-            stubRegistrations.push(server.tool('start_session', 'Start a new Happy Coder session.', {}, stubHandler));
+            stubRegistrations.push(server.tool('start_session', 'Start a new Happy Coder session.', startSessionSchema, stubHandler));
         }
     }
     // Start with stubs

package/dist/tools/answer_question.js

@@ -1,12 +1,8 @@
-import { z } from 'zod';
 import { randomUUID } from 'crypto';
 import { encryptToBase64 } from '../auth/crypto.js';
+import { answerQuestionSchema } from './schemas.js';
 export function registerAnswerQuestion(server, api, relay, sessionManager) {
-    return server.tool('answer_question', 'Answer a question (AskUserQuestion) from a session. Approves the pending permission and sends a user message with the answer.', {
-        sessionId: z.string().describe('The session ID'),
-        requestId: z.string().describe('The question request ID from pending permissions'),
-        answers: z.record(z.string(), z.string()).describe('Map of question header to selected answer'),
-    }, async ({ sessionId, requestId, answers }) => {
+    return server.tool('answer_question', 'Answer a question (AskUserQuestion) from a session. Approves the pending permission and sends a user message with the answer.', answerQuestionSchema, { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async ({ sessionId, requestId, answers }) => {
         try {
             // Check relay is connected (REQUIRED for answer_question)
             if (!relay.connected) {

package/dist/tools/approve_permission.js

@@ -1,15 +1,7 @@
-import { z } from 'zod';
 import { logger } from '../logger.js';
-const PERMISSION_MODES = ['default', 'acceptEdits', 'bypassPermissions', 'plan', 'read-only', 'safe-yolo', 'yolo'];
-const DECISIONS = ['approved', 'approved_for_session'];
+import { approvePermissionSchema } from './schemas.js';
 export function registerApprovePermission(server, relay, sessionManager) {
-    return server.tool('approve_permission', 'Approve a pending permission request in a session. Permission requests are shown in get_session and watch_session results.', {
-        sessionId: z.string().describe('The session ID'),
-        requestId: z.string().describe('The permission request ID to approve, or "all_pending" to approve all'),
-        mode: z.enum(PERMISSION_MODES).optional().describe('Permission mode to set after approval'),
-        allowTools: z.array(z.string()).optional().describe('List of tools to allow'),
-        decision: z.enum(DECISIONS).optional().default('approved').describe('Approval decision type'),
-    }, async ({ sessionId, requestId, mode, allowTools, decision }) => {
+    return server.tool('approve_permission', 'Approve a pending permission request in a session. Permission requests are shown in get_session and watch_session results.', approvePermissionSchema, { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async ({ sessionId, requestId, mode, allowTools, decision }) => {
         try {
             if (!relay.connected) {
                 const msg = relay.state === 'connecting'

package/dist/tools/deny_permission.js

@@ -1,12 +1,7 @@
-import { z } from 'zod';
 import { logger } from '../logger.js';
+import { denyPermissionSchema } from './schemas.js';
 export function registerDenyPermission(server, relay, sessionManager) {
-    return server.tool('deny_permission', 'Deny a pending permission request in a session. Can also abort the entire session.', {
-        sessionId: z.string().describe('The session ID'),
-        requestId: z.string().describe('The permission request ID to deny'),
-        reason: z.string().optional().describe('Feedback text explaining why the request was denied'),
-        decision: z.enum(['denied', 'abort']).optional().default('denied').describe('Denial type: denied (reject this request) or abort (stop the session)'),
-    }, async ({ sessionId, requestId, reason, decision }) => {
+    return server.tool('deny_permission', 'Deny a pending permission request in a session. Can also abort the entire session.', denyPermissionSchema, { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async ({ sessionId, requestId, reason, decision }) => {
         try {
             if (!relay.connected) {
                 const msg = relay.state === 'connecting'

package/dist/tools/get_session.js

@@ -1,5 +1,5 @@
-import { z } from 'zod';
 import { decodeBase64, decrypt } from '../auth/crypto.js';
+import { getSessionSchema } from './schemas.js';
 function renderMessage(msg) {
     const envelope = msg.content;
     if (!envelope)
@@ -47,12 +47,7 @@ function renderMessage(msg) {
     return { id: msg.id, role, content: text, timestamp: new Date(msg.createdAt).toISOString() };
 }
 export function registerGetSession(server, api, sessionManager) {
-    return server.tool('get_session', 'Get detailed information about a specific session including recent messages, metadata, and pending permissions.', {
-        sessionId: z.string().describe('The session ID to get details for'),
-        includeMessages: z.boolean().optional().default(true).describe('Whether to include messages'),
-        lastN: z.number().optional().default(20).describe('Number of recent messages to include'),
-        after: z.string().optional().describe('ISO 8601 timestamp — only return messages after this time'),
-    }, async ({ sessionId, includeMessages, lastN, after }) => {
+    return server.tool('get_session', 'Get detailed information about a specific session including recent messages, metadata, and pending permissions.', getSessionSchema, { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async ({ sessionId, includeMessages, lastN, after }) => {
         try {
             const session = sessionManager.get(sessionId);
             if (!session) {

package/dist/tools/interrupt_session.js

@@ -1,9 +1,7 @@
-import { z } from 'zod';
 import { logger } from '../logger.js';
+import { interruptSessionSchema } from './schemas.js';
 export function registerInterruptSession(server, relay, sessionManager) {
-    return server.tool('interrupt_session', 'Interrupt a running Claude Code session to stop its current activity. This sends an abort signal equivalent to pressing Escape — the session stays alive and can accept new messages afterward. Use this when a session is actively generating output and you need it to stop.', {
-        sessionId: z.string().describe('The session ID to interrupt'),
-    }, async ({ sessionId }) => {
+    return server.tool('interrupt_session', 'Interrupt a running Claude Code session to stop its current activity. This sends an abort signal equivalent to pressing Escape — the session stays alive and can accept new messages afterward. Use this when a session is actively generating output and you need it to stop.', interruptSessionSchema, { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async ({ sessionId }) => {
         try {
             if (!relay.connected) {
                 const msg = relay.state === 'connecting'

package/dist/tools/list_computers.js

@@ -1,5 +1,6 @@
+import { listComputersSchema } from './schemas.js';
 export function registerListComputers(server, sessionManager, config) {
-    return server.tool('list_computers', 'List available computers filtered by HAPPY_MCP_COMPUTERS. Shows hostname, online status, and active session count. Use before start_session to find available machines.', {}, async () => {
+    return server.tool('list_computers', 'List available computers filtered by HAPPY_MCP_COMPUTERS. Shows hostname, online status, and active session count. Use before start_session to find available machines.', listComputersSchema, { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async () => {
         try {
             const allMachines = sessionManager.getAllMachines();
             const machines = allMachines

package/dist/tools/list_sessions.js

@@ -1,12 +1,6 @@
-import { z } from 'zod';
+import { listSessionsSchema } from './schemas.js';
 export function registerListSessions(server, sessionManager, config) {
-    return server.tool('list_sessions', 'List all active Happy Coder sessions. Shows session ID, project path, hostname, status (active/idle/waiting_permission), and pending permissions.', {
-        filter: z.object({
-            status: z.enum(['active', 'idle', 'waiting_permission']).optional().describe('Filter by session status'),
-            computer: z.string().optional().describe('Filter by computer hostname'),
-            projectPath: z.string().optional().describe('Filter by project path prefix'),
-        }).optional(),
-    }, async ({ filter }) => {
+    return server.tool('list_sessions', 'List all active Happy Coder sessions. Shows session ID, project path, hostname, status (active/idle/waiting_permission), and pending permissions.', listSessionsSchema, { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async ({ filter }) => {
         try {
             const computerFilter = filter?.computer ? [filter.computer] : config.computers;
             const pathFilter = filter?.projectPath ? [filter.projectPath] : config.projectPaths;

package/dist/tools/schemas.d.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+/**
+ * Centralized Zod schemas for all MCP tools.
+ * These schemas are the single source of truth for tool input validation.
+ * They are used both for real tool registration and for stub registration
+ * to ensure clients always see correct parameter schemas.
+ */
+export declare const PERMISSION_MODES: readonly ["default", "acceptEdits", "bypassPermissions", "plan", "read-only", "safe-yolo", "yolo"];
+export declare const APPROVAL_DECISIONS: readonly ["approved", "approved_for_session"];
+export declare const DENIAL_DECISIONS: readonly ["denied", "abort"];
+export declare const AGENTS: readonly ["claude", "codex", "gemini"];
+export declare const listComputersSchema: {};
+export declare const listSessionsSchema: {
+    filter: z.ZodOptional<z.ZodObject<{
+        status: z.ZodOptional<z.ZodEnum<["active", "idle", "waiting_permission"]>>;
+        computer: z.ZodOptional<z.ZodString>;
+        projectPath: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        status?: "active" | "idle" | "waiting_permission" | undefined;
+        computer?: string | undefined;
+        projectPath?: string | undefined;
+    }, {
+        status?: "active" | "idle" | "waiting_permission" | undefined;
+        computer?: string | undefined;
+        projectPath?: string | undefined;
+    }>>;
+};
+export declare const getSessionSchema: {
+    sessionId: z.ZodString;
+    includeMessages: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    lastN: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    after: z.ZodOptional<z.ZodString>;
+};
+export declare const DEFAULT_TIMEOUT_SECONDS = 300;
+export declare const watchSessionSchema: {
+    sessionIds: z.ZodArray<z.ZodString, "many">;
+    timeoutSeconds: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+};
+export declare const sendMessageSchema: {
+    sessionId: z.ZodString;
+    message: z.ZodString;
+    meta: z.ZodOptional<z.ZodObject<{
+        permissionMode: z.ZodOptional<z.ZodEnum<["default", "acceptEdits", "bypassPermissions", "plan", "read-only", "safe-yolo", "yolo"]>>;
+        allowedTools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        permissionMode?: "default" | "acceptEdits" | "bypassPermissions" | "plan" | "read-only" | "safe-yolo" | "yolo" | undefined;
+        allowedTools?: string[] | undefined;
+        disallowedTools?: string[] | undefined;
+    }, {
+        permissionMode?: "default" | "acceptEdits" | "bypassPermissions" | "plan" | "read-only" | "safe-yolo" | "yolo" | undefined;
+        allowedTools?: string[] | undefined;
+        disallowedTools?: string[] | undefined;
+    }>>;
+};
+export declare const approvePermissionSchema: {
+    sessionId: z.ZodString;
+    requestId: z.ZodString;
+    mode: z.ZodOptional<z.ZodEnum<["default", "acceptEdits", "bypassPermissions", "plan", "read-only", "safe-yolo", "yolo"]>>;
+    allowTools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    decision: z.ZodDefault<z.ZodOptional<z.ZodEnum<["approved", "approved_for_session"]>>>;
+};
+export declare const denyPermissionSchema: {
+    sessionId: z.ZodString;
+    requestId: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+    decision: z.ZodDefault<z.ZodOptional<z.ZodEnum<["denied", "abort"]>>>;
+};
+export declare const interruptSessionSchema: {
+    sessionId: z.ZodString;
+};
+export declare const answerQuestionSchema: {
+    sessionId: z.ZodString;
+    requestId: z.ZodString;
+    answers: z.ZodRecord<z.ZodString, z.ZodString>;
+};
+export declare const stopSessionSchema: {
+    sessionId: z.ZodString;
+};
+export declare const startSessionSchema: {
+    computer: z.ZodString;
+    projectPath: z.ZodString;
+    initialMessage: z.ZodOptional<z.ZodString>;
+    permissionMode: z.ZodOptional<z.ZodEnum<["default", "acceptEdits", "bypassPermissions", "plan", "read-only", "safe-yolo", "yolo"]>>;
+    agent: z.ZodDefault<z.ZodOptional<z.ZodEnum<["claude", "codex", "gemini"]>>>;
+};

package/dist/tools/schemas.js

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+/**
+ * Centralized Zod schemas for all MCP tools.
+ * These schemas are the single source of truth for tool input validation.
+ * They are used both for real tool registration and for stub registration
+ * to ensure clients always see correct parameter schemas.
+ */
+// Permission modes (used across multiple tools)
+export const PERMISSION_MODES = ['default', 'acceptEdits', 'bypassPermissions', 'plan', 'read-only', 'safe-yolo', 'yolo'];
+// Decision types for approve_permission
+export const APPROVAL_DECISIONS = ['approved', 'approved_for_session'];
+// Decision types for deny_permission
+export const DENIAL_DECISIONS = ['denied', 'abort'];
+// AI agents for start_session
+export const AGENTS = ['claude', 'codex', 'gemini'];
+// list_computers (no parameters)
+export const listComputersSchema = {};
+// list_sessions
+export const listSessionsSchema = {
+    filter: z.object({
+        status: z.enum(['active', 'idle', 'waiting_permission']).optional().describe('Filter by session status'),
+        computer: z.string().optional().describe('Filter by computer hostname'),
+        projectPath: z.string().optional().describe('Filter by project path prefix'),
+    }).optional(),
+};
+// get_session
+export const getSessionSchema = {
+    sessionId: z.string().describe('The session ID to get details for'),
+    includeMessages: z.boolean().optional().default(true).describe('Whether to include messages'),
+    lastN: z.number().optional().default(20).describe('Number of recent messages to include'),
+    after: z.string().optional().describe('ISO 8601 timestamp — only return messages after this time'),
+};
+// watch_session
+export const DEFAULT_TIMEOUT_SECONDS = 300; // 5 minutes
+export const watchSessionSchema = {
+    sessionIds: z.array(z.string()).describe('One or more session IDs to watch'),
+    timeoutSeconds: z.number().optional().default(DEFAULT_TIMEOUT_SECONDS).describe('Max wait time in seconds (default 300)'),
+};
+// send_message
+export const sendMessageSchema = {
+    sessionId: z.string().describe('The session ID to send the message to'),
+    message: z.string().describe('The message text to send'),
+    meta: z.object({
+        permissionMode: z.enum(PERMISSION_MODES).optional(),
+        allowedTools: z.array(z.string()).optional(),
+        disallowedTools: z.array(z.string()).optional(),
+    }).optional(),
+};
+// approve_permission
+export const approvePermissionSchema = {
+    sessionId: z.string().describe('The session ID'),
+    requestId: z.string().describe('The permission request ID to approve, or "all_pending" to approve all'),
+    mode: z.enum(PERMISSION_MODES).optional().describe('Permission mode to set after approval'),
+    allowTools: z.array(z.string()).optional().describe('List of tools to allow'),
+    decision: z.enum(APPROVAL_DECISIONS).optional().default('approved').describe('Approval decision type'),
+};
+// deny_permission
+export const denyPermissionSchema = {
+    sessionId: z.string().describe('The session ID'),
+    requestId: z.string().describe('The permission request ID to deny'),
+    reason: z.string().optional().describe('Feedback text explaining why the request was denied'),
+    decision: z.enum(DENIAL_DECISIONS).optional().default('denied').describe('Denial type: denied (reject this request) or abort (stop the session)'),
+};
+// interrupt_session
+export const interruptSessionSchema = {
+    sessionId: z.string().describe('The session ID to interrupt'),
+};
+// answer_question
+export const answerQuestionSchema = {
+    sessionId: z.string().describe('The session ID'),
+    requestId: z.string().describe('The question request ID from pending permissions'),
+    answers: z.record(z.string(), z.string()).describe('Map of question header to selected answer'),
+};
+// stop_session
+export const stopSessionSchema = {
+    sessionId: z.string().describe('The session ID to stop'),
+};
+// start_session (uses a generic description for projectPath)
+export const startSessionSchema = {
+    computer: z.string().describe('The machine ID (from list_computers)'),
+    projectPath: z.string().describe('The working directory for the new session'),
+    initialMessage: z.string().optional().describe('Initial message to send after session starts'),
+    permissionMode: z.enum(PERMISSION_MODES).optional().describe('Permission mode for the session'),
+    agent: z.enum(AGENTS).optional().default('claude').describe('The AI agent to use'),
+};

package/dist/tools/send_message.js

@@ -1,16 +1,7 @@
-import { z } from 'zod';
 import { encryptToBase64 } from '../auth/crypto.js';
-const PERMISSION_MODES = ['default', 'acceptEdits', 'bypassPermissions', 'plan', 'read-only', 'safe-yolo', 'yolo'];
+import { sendMessageSchema } from './schemas.js';
 export function registerSendMessage(server, relay, sessionManager) {
-    return server.tool('send_message', 'Send a message to a Happy Coder session. The message will appear as a user message in the session. If the session is actively generating, the message will be queued and processed when the session is ready. Can optionally change the permission mode.', {
-        sessionId: z.string().describe('The session ID to send the message to'),
-        message: z.string().describe('The message text to send'),
-        meta: z.object({
-            permissionMode: z.enum(PERMISSION_MODES).optional(),
-            allowedTools: z.array(z.string()).optional(),
-            disallowedTools: z.array(z.string()).optional(),
-        }).optional(),
-    }, async ({ sessionId, message, meta }) => {
+    return server.tool('send_message', 'Send a message to a Happy Coder session. The message will appear as a user message in the session. If the session is actively generating, the message will be queued and processed when the session is ready. Can optionally change the permission mode.', sendMessageSchema, { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async ({ sessionId, message, meta }) => {
         try {
             // Check relay connectivity
             if (!relay.connected) {

package/dist/tools/start_session.js

@@ -1,15 +1,14 @@
 import { z } from 'zod';
-const PERMISSION_MODES = ['default', 'acceptEdits', 'bypassPermissions', 'plan', 'read-only', 'safe-yolo', 'yolo'];
+import { startSessionSchema } from './schemas.js';
 export function registerStartSession(server, _api, relay, sessionManager, config) {
-    return server.tool('start_session', 'Start a new Happy Coder session on a remote machine. Requires the machine to be online. Use list_computers to find available machines.', {
-        computer: z.string().describe('The machine ID (from list_computers)'),
+    // Create a dynamic schema with config-specific projectPath description
+    const dynamicSchema = {
+        ...startSessionSchema,
         projectPath: z.string().describe(config.projectPaths.includes('*')
             ? 'The working directory for the new session'
             : `The working directory for the new session. Allowed paths: ${config.projectPaths.join(', ')}`),
-        initialMessage: z.string().optional().describe('Initial message to send after session starts'),
-        permissionMode: z.enum(PERMISSION_MODES).optional().describe('Permission mode for the session'),
-        agent: z.enum(['claude', 'codex', 'gemini']).optional().default('claude').describe('The AI agent to use'),
-    }, async ({ computer, projectPath, initialMessage, permissionMode, agent }) => {
+    };
+    return server.tool('start_session', 'Start a new Happy Coder session on a remote machine. Requires the machine to be online. Use list_computers to find available machines.', dynamicSchema, { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async ({ computer, projectPath, initialMessage, permissionMode, agent }) => {
         try {
             if (!relay.connected) {
                 const msg = relay.state === 'connecting'

package/dist/tools/stop_session.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { RelayClient } from '../relay/client.js';
+import type { SessionManager } from '../session/manager.js';
+export declare function registerStopSession(server: McpServer, relay: RelayClient, sessionManager: SessionManager): RegisteredTool;

package/dist/tools/stop_session.js

@@ -0,0 +1,27 @@
+import { logger } from '../logger.js';
+import { stopSessionSchema } from './schemas.js';
+export function registerStopSession(server, relay, sessionManager) {
+    return server.tool('stop_session', 'Stop and archive a running Happy Coder session. This gracefully terminates the CLI process — the session becomes inactive but its message history is preserved. Use this when you\'re done with a session and want to free up resources.', stopSessionSchema, { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }, async ({ sessionId }) => {
+        try {
+            if (!relay.connected) {
+                const msg = relay.state === 'connecting'
+                    ? 'Relay is still connecting. Please try again in a few seconds.'
+                    : 'Relay is disconnected.';
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify({
+                                error: relay.state === 'connecting' ? 'RelayConnecting' : 'RelayDisconnected',
+                                message: msg,
+                            }) }] };
+            }
+            const session = sessionManager.get(sessionId);
+            if (!session) {
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: 'SessionNotFound', message: `Session ${sessionId} not found` }) }] };
+            }
+            await relay.sessionRpc(sessionId, 'killSession', {});
+            logger.info(`[audit] Session STOPPED: session=${sessionId}`);
+            return { content: [{ type: 'text', text: JSON.stringify({ success: true, sessionId, message: 'Session stopped successfully. The CLI process has been terminated.' }, null, 2) }] };
+        }
+        catch (err) {
+            return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: 'StopSessionFailed', message: err.message }) }] };
+        }
+    });
+}

package/dist/tools/watch_session.js

@@ -1,11 +1,7 @@
-import { z } from 'zod';
-const DEFAULT_TIMEOUT_SECONDS = 300; // 5 minutes
+import { watchSessionSchema } from './schemas.js';
 const MAX_WAIT_MS = 300_000; // 5 min max wait
 export function registerWatchSession(server, relay, sessionManager) {
-    return server.tool('watch_session', 'Watch one or more sessions for state changes. Returns immediately if any session is idle or has pending permissions. Otherwise waits up to 5 minutes for a state change. If sessions are still active, returns current status -- call again to continue watching.', {
-        sessionIds: z.array(z.string()).describe('One or more session IDs to watch'),
-        timeoutSeconds: z.number().optional().default(DEFAULT_TIMEOUT_SECONDS).describe('Max wait time in seconds (default 300)'),
-    }, async ({ sessionIds, timeoutSeconds }, extra) => {
+    return server.tool('watch_session', 'Watch one or more sessions for state changes. Returns immediately if any session is idle or has pending permissions. Otherwise waits up to 5 minutes for a state change. If sessions are still active, returns current status -- call again to continue watching.', watchSessionSchema, { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async ({ sessionIds, timeoutSeconds }, extra) => {
         try {
             // Validate all session IDs exist
             const missing = sessionIds.filter(id => !sessionManager.get(id));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "happy-mcp-server",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "MCP server for observing and controlling Happy Coder sessions",
   "author": {
     "name": "Jared Spencer",