Task Trellis MCP

Instructions

Implementation Reference

• src/server.ts:219-251 (handler)

  Main execution logic for the 'activate' tool: parses arguments, updates server configuration (mode, planningRootFolder, remote settings), and returns activation confirmation.
  if (toolName === "activate") { const { mode, projectRoot, apiToken, url, remoteProjectId } = args as { mode: "local" | "remote"; projectRoot?: string; apiToken?: string; url?: string; remoteProjectId?: string; }; // Update server config based on activate parameters serverConfig.mode = mode; if (mode === "local" && projectRoot) { serverConfig.planningRootFolder = path.join(projectRoot, ".trellis"); } else if (mode === "remote") { if (url) serverConfig.remoteRepositoryUrl = url; if (apiToken) serverConfig.remoteRepositoryApiToken = apiToken; if (remoteProjectId) serverConfig.remoteProjectId = remoteProjectId; } return { content: [ { type: "text", text: `Activated in ${mode} mode. Server config updated: ${JSON.stringify( serverConfig, null, 2, )}`, }, ], }; }
• src/tools/activateTool.ts:38-64 (schema)

  JSON schema defining the input parameters for the 'activate' tool, including mode (local/remote), projectRoot, apiToken, url, and remoteProjectId.
  inputSchema: { type: "object", properties: { mode: { type: "string", enum: ["local", "remote"], description: "Mode to activate (local or remote)", }, projectRoot: { type: "string", description: "Project root path (required for local mode)", }, apiToken: { type: "string", description: "API token (required for remote mode)", }, url: { type: "string", description: "URL for remote mode (optional, for non-standard URLs)", }, remoteProjectId: { type: "string", description: "Remote project ID (required for remote mode)", }, }, required: ["mode"], },
• src/server.ts:176-197 (registration)

  Registers the list of available tools for ListToolsRequestSchema, conditionally including 'activateTool' if local mode lacks planningRootFolder configuration.
  server.setRequestHandler(ListToolsRequestSchema, () => { const tools: unknown[] = [ createObjectTool, updateObjectTool, getObjectTool, deleteObjectTool, listObjectsTool, appendObjectLogTool, appendModifiedFilesTool, claimTaskTool, getNextAvailableIssueTool, completeTaskTool, ]; // Only include activate tool if server is not properly configured from command line // (i.e., local mode without projectRootFolder specified) if (serverConfig.mode === "local" && !serverConfig.planningRootFolder) { tools.push(activateTool); } return { tools }; });
• src/tools/activateTool.ts:1-65 (registration)

  Tool registration object defining name 'activate', detailed description, and inputSchema; imported and conditionally pushed to tools list in server.ts.
  export const activateTool = { name: "activate", description: `Activates the task trellis system in local or remote mode Use this tool to initialize and configure the task trellis system for operation. Must be called before any other task management operations can be performed. Activation modes: - 'local': Uses local file system for task storage and management - 'remote': Connects to remote task trellis service via API Local mode requirements: - 'projectRoot': Absolute path to project directory where tasks will be stored - Creates local .task-trellis directory for data persistence - Suitable for single-user development workflows - No network dependencies once activated Remote mode requirements: - 'apiToken': Authentication token for remote service access - 'remoteProjectId': Unique identifier for remote project instance - 'url': Service endpoint (optional, uses default if not specified) - Enables collaborative task management across distributed teams - Requires network connectivity for all operations Activation process: 1. Validates mode-specific parameters and connectivity 2. Initializes data storage (local directory or remote connection) 3. Verifies authentication and permissions 4. Sets up task trellis schema and configuration 5. Prepares system for task creation and management Error conditions: - Invalid projectRoot path (local mode) - Authentication failure (remote mode) - Network connectivity issues (remote mode) - Insufficient file system permissions (local mode) Must be successfully completed before using any other task trellis tools. Re-activation with different parameters switches modes and resets system state.`, inputSchema: { type: "object", properties: { mode: { type: "string", enum: ["local", "remote"], description: "Mode to activate (local or remote)", }, projectRoot: { type: "string", description: "Project root path (required for local mode)", }, apiToken: { type: "string", description: "API token (required for remote mode)", }, url: { type: "string", description: "URL for remote mode (optional, for non-standard URLs)", }, remoteProjectId: { type: "string", description: "Remote project ID (required for remote mode)", }, }, required: ["mode"], }, } as const;
• src/tools/activateTool.ts:67-88 (helper)

  Unused stub handler function for activate tool (no-op echo); actual logic implemented directly in server.ts.
  export function handleActivate(args: unknown) { const { mode, projectRoot, apiToken, url } = args as { mode: "local" | "remote"; projectRoot?: string; apiToken?: string; url?: string; }; // No-op implementation - just return the received parameters return { content: [ { type: "text", text: `Activated: ${JSON.stringify( { mode, projectRoot, apiToken, url }, null, 2, )}`, }, ], }; }