happy-mcp-server 1.1.2 → 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,7 +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 { listComputersSchema, listSessionsSchema, getSessionSchema, watchSessionSchema, sendMessageSchema, approvePermissionSchema, denyPermissionSchema, interruptSessionSchema, answerQuestionSchema, startSessionSchema, } from './tools/schemas.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: [{
@@ -32,6 +33,7 @@ const TOOL_STUBS = [
     ['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],
 ];
 /**
@@ -47,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);

package/dist/tools/answer_question.js

@@ -2,7 +2,7 @@ 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.', answerQuestionSchema, 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,7 +1,7 @@
 import { logger } from '../logger.js';
 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.', approvePermissionSchema, 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,7 +1,7 @@
 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.', denyPermissionSchema, 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

@@ -47,7 +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.', getSessionSchema, 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,7 +1,7 @@
 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.', interruptSessionSchema, 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,6 +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.', listComputersSchema, 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,6 +1,6 @@
 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.', listSessionsSchema, 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

@@ -74,6 +74,9 @@ export declare const answerQuestionSchema: {
     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;

package/dist/tools/schemas.js

@@ -71,6 +71,10 @@ export const answerQuestionSchema = {
     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)'),

package/dist/tools/send_message.js

@@ -1,7 +1,7 @@
 import { encryptToBase64 } from '../auth/crypto.js';
 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.', sendMessageSchema, 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

@@ -8,7 +8,7 @@ export function registerStartSession(server, _api, relay, sessionManager, config
             ? 'The working directory for the new session'
             : `The working directory for the new session. Allowed paths: ${config.projectPaths.join(', ')}`),
     };
-    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, 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,7 +1,7 @@
 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.', watchSessionSchema, 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.2",
+  "version": "1.2.0",
   "description": "MCP server for observing and controlling Happy Coder sessions",
   "author": {
     "name": "Jared Spencer",