cyrus-mcp-tools 0.1.1 → 0.2.0

package/README.md

@@ -9,6 +9,7 @@ MCP tools for Cyrus - including Linear file uploads and other utilities.
 
 This MCP server provides tools for Cyrus, currently including:
 - File uploads to Linear's cloud storage for use in issues, comments, and other content
+- Agent session creation for tracking AI/bot activity on Linear issues
 
 ## Features
 
@@ -67,9 +68,9 @@ Add the following to your MCP settings file:
 
 ## Usage
 
-### Available Tool
+### Available Tools
 
-The server provides a single tool:
+The server provides the following tools:
 
 #### `linear_upload_file`
 
@@ -87,6 +88,19 @@ Upload a file to Linear and get an asset URL.
 - `size`: File size in bytes
 - `contentType`: MIME type of the uploaded file
 
+#### `linear_agent_session_create`
+
+Create an agent session on a Linear issue to track AI/bot activity.
+
+**Parameters:**
+- `issueId` (required): The ID or identifier of the Linear issue (e.g., "ABC-123" or UUID)
+- `externalLink` (optional): URL of an external agent-hosted page associated with this session
+
+**Returns:**
+- `success`: Whether the operation was successful
+- `agentSessionId`: The ID of the created agent session
+- `lastSyncId`: The identifier of the last sync operation
+
 ### Example Usage
 
 Once configured, you can use prompts like:

package/dist/services/linear-service.js

@@ -457,7 +457,7 @@ export class LinearService {
             description: args.description,
             content: args.content,
             teamIds: teamIds,
-            state: args.state,
+            // state: args.state, // TODO: v58 removed state, need to use statusId instead
             startDate: args.startDate ? new Date(args.startDate) : undefined,
             targetDate: args.targetDate ? new Date(args.targetDate) : undefined,
             leadId: args.leadId,
@@ -941,7 +941,7 @@ export class LinearService {
                 name: args.name,
                 description: args.description,
                 content: args.content,
-                state: args.state,
+                // state: args.state as any, // TODO: v58 removed state, need to use statusId instead
                 startDate: args.startDate ? new Date(args.startDate) : undefined,
                 targetDate: args.targetDate ? new Date(args.targetDate) : undefined,
                 leadId: args.leadId,

package/dist/tools/definitions/agent-session-tool.js

@@ -0,0 +1,39 @@
+/**
+ * Tool for creating an agent session on a Linear issue.
+ * This creates a new agent session that tracks AI/bot activity on an issue.
+ */
+export const createAgentSessionToolDefinition = {
+    name: 'linear_agent_session_create',
+    description: 'Create an agent session on a Linear issue to track AI/bot activity.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            issueId: {
+                type: 'string',
+                description: 'The ID or identifier of the Linear issue (e.g., "ABC-123" or UUID)'
+            },
+            externalLink: {
+                type: 'string',
+                description: 'Optional URL of an external agent-hosted page associated with this session'
+            }
+        },
+        required: ['issueId']
+    },
+    output_schema: {
+        type: 'object',
+        properties: {
+            success: {
+                type: 'boolean',
+                description: 'Whether the operation was successful'
+            },
+            agentSessionId: {
+                type: 'string',
+                description: 'The ID of the created agent session'
+            },
+            lastSyncId: {
+                type: 'number',
+                description: 'The identifier of the last sync operation'
+            }
+        }
+    }
+};

package/dist/tools/definitions/index.js

@@ -1,7 +1,9 @@
 import { uploadFileToolDefinition } from "./upload-tool.js";
+import { createAgentSessionToolDefinition } from "./agent-session-tool.js";
 // All tool definitions
 export const allToolDefinitions = [
     uploadFileToolDefinition,
+    createAgentSessionToolDefinition,
 ];
 // Export all tool definitions individually
-export { uploadFileToolDefinition };
+export { uploadFileToolDefinition, createAgentSessionToolDefinition };

package/dist/tools/handlers/agent-session-handler.js

@@ -0,0 +1,51 @@
+import { isCreateAgentSessionArgs } from '../type-guards.js';
+/**
+ * Handler for creating an agent session on a Linear issue
+ */
+export function handleCreateAgentSession(linearService) {
+    return async (args) => {
+        if (!isCreateAgentSessionArgs(args)) {
+            throw new Error('Invalid arguments for agent_session_create');
+        }
+        try {
+            // Use raw GraphQL through the Linear client
+            // Access the underlying GraphQL client
+            const graphQLClient = linearService.client.client;
+            const mutation = `
+				mutation AgentSessionCreateOnIssue($input: AgentSessionCreateOnIssue!) {
+					agentSessionCreateOnIssue(input: $input) {
+						success
+						lastSyncId
+						agentSession {
+							id
+						}
+					}
+				}
+			`;
+            const variables = {
+                input: {
+                    issueId: args.issueId,
+                    ...(args.externalLink && { externalLink: args.externalLink })
+                }
+            };
+            console.log(`Creating agent session for issue ${args.issueId}`);
+            const response = await graphQLClient.rawRequest(mutation, variables);
+            const result = response.data.agentSessionCreateOnIssue;
+            if (!result.success) {
+                throw new Error('Failed to create agent session');
+            }
+            console.log(`Agent session created successfully: ${result.agentSession.id}`);
+            return {
+                success: result.success,
+                agentSessionId: result.agentSession.id,
+                lastSyncId: result.lastSyncId
+            };
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to create agent session: ${error.message}`);
+            }
+            throw error;
+        }
+    };
+}

package/dist/tools/handlers/index.js

@@ -1,4 +1,5 @@
 import { handleUploadFile } from "./upload-handler.js";
+import { handleCreateAgentSession } from "./agent-session-handler.js";
 /**
  * Registers all tool handlers for the MCP Linear uploads
  * @param linearService The Linear service instance
@@ -7,7 +8,8 @@ import { handleUploadFile } from "./upload-handler.js";
 export function registerToolHandlers(linearService) {
     return {
         linear_upload_file: handleUploadFile(linearService),
+        linear_agent_session_create: handleCreateAgentSession(linearService),
     };
 }
 // Export all handlers individually
-export { handleUploadFile };
+export { handleUploadFile, handleCreateAgentSession };

package/dist/tools/handlers/upload-handler.js

@@ -81,12 +81,14 @@ export function handleUploadFile(linearService) {
             const { uploadUrl, headers, assetUrl } = uploadPayload.uploadFile;
             // Step 2: Upload the file to the provided URL
             console.log(`Uploading file to Linear cloud storage...`);
-            console.log(`Headers from Linear:`, headers);
-            // Convert headers array to object, being careful with header names
-            const uploadHeaders = {};
-            // Only include headers that Linear explicitly provided
+            // Create headers following Linear's documentation exactly
+            const uploadHeaders = {
+                "Content-Type": contentType,
+                "Cache-Control": "public, max-age=31536000",
+            };
+            // Then add the headers from Linear's response
+            // These override any defaults we set above
             for (const header of headers) {
-                // Use the exact key provided by Linear
                 uploadHeaders[header.key] = header.value;
             }
             console.log(`Headers being sent:`, uploadHeaders);

package/dist/tools/type-guards.js

@@ -22,3 +22,18 @@ export function isUploadFileArgs(args) {
     }
     return true;
 }
+export function isCreateAgentSessionArgs(args) {
+    if (typeof args !== "object" || args === null) {
+        return false;
+    }
+    const obj = args;
+    // Required field
+    if (typeof obj.issueId !== "string") {
+        return false;
+    }
+    // Optional field
+    if (obj.externalLink !== undefined && typeof obj.externalLink !== "string") {
+        return false;
+    }
+    return true;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "cyrus-mcp-tools",
-	"version": "0.1.1",
-	"description": "MCP tools for Cyrus - including Linear file uploads and other utilities.",
+	"version": "0.2.0",
+	"description": "MCP tools for Cyrus - Linear file uploads, agent session creation, and other utilities.",
 	"main": "dist/index.js",
 	"type": "module",
 	"bin": {
@@ -25,9 +25,10 @@
 	"smithery": {
 		"name": "cyrus-mcp-tools",
 		"displayName": "Cyrus MCP Tools",
-		"description": "MCP tools for Cyrus including Linear file uploads",
+		"description": "MCP tools for Cyrus including Linear file uploads and agent session management",
 		"tools": [
-			"linear_upload_file"
+			"linear_upload_file",
+			"linear_agent_session_create"
 		]
 	},
 	"keywords": [

package/src/services/linear-service.ts

@@ -571,7 +571,7 @@ export class LinearService {
 			description: args.description,
 			content: args.content,
 			teamIds: teamIds,
-			state: args.state,
+			// state: args.state, // TODO: v58 removed state, need to use statusId instead
 			startDate: args.startDate ? new Date(args.startDate) : undefined,
 			targetDate: args.targetDate ? new Date(args.targetDate) : undefined,
 			leadId: args.leadId,
@@ -1125,7 +1125,7 @@ export class LinearService {
 				name: args.name,
 				description: args.description,
 				content: args.content,
-				state: args.state as any,
+				// state: args.state as any, // TODO: v58 removed state, need to use statusId instead
 				startDate: args.startDate ? new Date(args.startDate) : undefined,
 				targetDate: args.targetDate ? new Date(args.targetDate) : undefined,
 				leadId: args.leadId,

package/src/tools/definitions/agent-session-tool.ts

@@ -0,0 +1,41 @@
+import type { MCPToolDefinition } from '../../types.js';
+
+/**
+ * Tool for creating an agent session on a Linear issue.
+ * This creates a new agent session that tracks AI/bot activity on an issue.
+ */
+export const createAgentSessionToolDefinition: MCPToolDefinition = {
+	name: 'linear_agent_session_create',
+	description: 'Create an agent session on a Linear issue to track AI/bot activity.',
+	input_schema: {
+		type: 'object',
+		properties: {
+			issueId: {
+				type: 'string',
+				description: 'The ID or identifier of the Linear issue (e.g., "ABC-123" or UUID)'
+			},
+			externalLink: {
+				type: 'string',
+				description: 'Optional URL of an external agent-hosted page associated with this session'
+			}
+		},
+		required: ['issueId']
+	},
+	output_schema: {
+		type: 'object',
+		properties: {
+			success: {
+				type: 'boolean',
+				description: 'Whether the operation was successful'
+			},
+			agentSessionId: {
+				type: 'string',
+				description: 'The ID of the created agent session'
+			},
+			lastSyncId: {
+				type: 'number',
+				description: 'The identifier of the last sync operation'
+			}
+		}
+	}
+};

package/src/tools/definitions/index.ts

@@ -1,10 +1,12 @@
 import type { MCPToolDefinition } from "../../types.js";
 import { uploadFileToolDefinition } from "./upload-tool.js";
+import { createAgentSessionToolDefinition } from "./agent-session-tool.js";
 
 // All tool definitions
 export const allToolDefinitions: MCPToolDefinition[] = [
 	uploadFileToolDefinition,
+	createAgentSessionToolDefinition,
 ];
 
 // Export all tool definitions individually
-export { uploadFileToolDefinition };
+export { uploadFileToolDefinition, createAgentSessionToolDefinition };

package/src/tools/handlers/agent-session-handler.ts

@@ -0,0 +1,61 @@
+import { LinearService } from '../../services/linear-service.js';
+import { isCreateAgentSessionArgs } from '../type-guards.js';
+
+/**
+ * Handler for creating an agent session on a Linear issue
+ */
+export function handleCreateAgentSession(linearService: LinearService) {
+	return async (args: unknown) => {
+		if (!isCreateAgentSessionArgs(args)) {
+			throw new Error('Invalid arguments for agent_session_create');
+		}
+
+		try {
+			// Use raw GraphQL through the Linear client
+			// Access the underlying GraphQL client
+			const graphQLClient = (linearService as any).client.client;
+			
+			const mutation = `
+				mutation AgentSessionCreateOnIssue($input: AgentSessionCreateOnIssue!) {
+					agentSessionCreateOnIssue(input: $input) {
+						success
+						lastSyncId
+						agentSession {
+							id
+						}
+					}
+				}
+			`;
+
+			const variables = {
+				input: {
+					issueId: args.issueId,
+					...(args.externalLink && { externalLink: args.externalLink })
+				}
+			};
+
+			console.log(`Creating agent session for issue ${args.issueId}`);
+			
+			const response = await graphQLClient.rawRequest(mutation, variables);
+			
+			const result = response.data.agentSessionCreateOnIssue;
+			
+			if (!result.success) {
+				throw new Error('Failed to create agent session');
+			}
+
+			console.log(`Agent session created successfully: ${result.agentSession.id}`);
+
+			return {
+				success: result.success,
+				agentSessionId: result.agentSession.id,
+				lastSyncId: result.lastSyncId
+			};
+		} catch (error) {
+			if (error instanceof Error) {
+				throw new Error(`Failed to create agent session: ${error.message}`);
+			}
+			throw error;
+		}
+	};
+}

package/src/tools/handlers/index.ts

@@ -1,5 +1,6 @@
 import type { LinearService } from "../../services/linear-service.js";
 import { handleUploadFile } from "./upload-handler.js";
+import { handleCreateAgentSession } from "./agent-session-handler.js";
 
 // Define the handler function type
 type ToolHandler = (args: unknown) => Promise<unknown>;
@@ -14,8 +15,9 @@ export function registerToolHandlers(
 ): Record<string, ToolHandler> {
 	return {
 		linear_upload_file: handleUploadFile(linearService),
+		linear_agent_session_create: handleCreateAgentSession(linearService),
 	};
 }
 
 // Export all handlers individually
-export { handleUploadFile };
+export { handleUploadFile, handleCreateAgentSession };

package/src/tools/handlers/upload-handler.ts

@@ -106,14 +106,16 @@ export function handleUploadFile(linearService: LinearService) {
 
 			// Step 2: Upload the file to the provided URL
 			console.log(`Uploading file to Linear cloud storage...`);
-			console.log(`Headers from Linear:`, headers);
 
-			// Convert headers array to object, being careful with header names
-			const uploadHeaders: Record<string, string> = {};
+			// Create headers following Linear's documentation exactly
+			const uploadHeaders: Record<string, string> = {
+				"Content-Type": contentType,
+				"Cache-Control": "public, max-age=31536000",
+			};
 			
-			// Only include headers that Linear explicitly provided
+			// Then add the headers from Linear's response
+			// These override any defaults we set above
 			for (const header of headers) {
-				// Use the exact key provided by Linear
 				uploadHeaders[header.key] = header.value;
 			}
 			

package/src/tools/type-guards.ts

@@ -36,3 +36,28 @@ export function isUploadFileArgs(args: unknown): args is UploadFileArgs {
 
 	return true;
 }
+
+export interface CreateAgentSessionArgs {
+	issueId: string;
+	externalLink?: string;
+}
+
+export function isCreateAgentSessionArgs(args: unknown): args is CreateAgentSessionArgs {
+	if (typeof args !== "object" || args === null) {
+		return false;
+	}
+
+	const obj = args as any;
+
+	// Required field
+	if (typeof obj.issueId !== "string") {
+		return false;
+	}
+
+	// Optional field
+	if (obj.externalLink !== undefined && typeof obj.externalLink !== "string") {
+		return false;
+	}
+
+	return true;
+}