refactor(kiloclaw): replace Linear CLI with Linear MCP server (#1635)

## Summary

A refactor targeting #1407:

After exploring other options for the Linear integration, the official
Linear MCP server turned out to be a better fit than the CLI. All
OpenClaw instances are already deployed with the `mcporter` package and
skill, which give KiloClaw MCP abilities anyways. Importantly, unlike
the CLI, mcporter also allows us to avoid ever writing our actual API
key to a file, which significantly reduces the overhead for managing
this integration. This PR targets feature/kiloclaw-linear-cli with the
scoped changes to switch-over to this MCP integration only, to simplify
the reviewer's experience.

## Changes

- Undo the changes to both `Dockerfile`s — the target branch will have
no diff after this PR merges.
- Strip all on-disk credential cleanup logic from `configureLinear()` —
no new files to manage anymore, so the function no longer needs
`BootstrapDeps`
- Add Linear MCP server entry to `writeMcporterConfig()` when
`LINEAR_API_KEY` is set; remove it when unset. Preserves existing
user-configured servers. The key is stored in the file as
`${LINEAR_API_KEY}` verbatim and read from the environment by mcporter.
- Replace CLI usage documentation in the TOOLS.md agent section with a
pointer to the Linear MCP server and mcporter skill
- Simplify `configureLinear` tests (no more fs/exec mocking) and add
`writeMcporterConfig` tests covering add, remove, preserve, and
multi-server scenarios

## Verification

- [x] `pnpm format:check` passes
- [x] `pnpm lint` passes
- [x] Tests pass (`vitest` in kiloclaw workspace)
- [x] E2E tested on a fresh instance

## New Loom — Kilo Team only
https://www.loom.com/share/5ca9897104e84a3baf560818b7a3bcf7

## Action for reviewer
Please let me know your preference for merge, whether it's into the
feature/kiloclaw-cli branch, or into main directly.

Author: evanjacobson

kiloclaw/Dockerfile

@@ -31,6 +31,8 @@ RUN apt-get update \
        | gpg --dearmor --output /usr/share/debsig/keyrings/AC2D62742012EA22/debsig.gpg \
     && apt-get update \
     && apt-get install -y --no-install-recommends gh 1password-cli \
+    && apt-get purge -y xz-utils \
+    && apt-get autoremove -y \
     && rm -rf /var/lib/apt/lists/* \
     && node --version \
     && npm --version
@@ -55,13 +57,6 @@ RUN npm install -g @steipete/summarize@0.12.0
 # Install Kilo CLI (agentic coding assistant for the terminal)
 RUN npm install -g @kilocode/cli@7.0.46
 
-# Install Linear CLI (issue tracker)
-RUN npm install -g @schpet/linear-cli@1.11.1
-
-# Clean up xz-utils now that Node.js and linear-cli are installed
-RUN apt-get purge -y xz-utils \
-    && apt-get autoremove -y \
-    && rm -rf /var/lib/apt/lists/*
 
 # Install Go (available at runtime for users to `go install` additional tools)
 ENV GO_VERSION=1.26.0

kiloclaw/Dockerfile.local

@@ -31,6 +31,8 @@ RUN apt-get update \
        | gpg --dearmor --output /usr/share/debsig/keyrings/AC2D62742012EA22/debsig.gpg \
     && apt-get update \
     && apt-get install -y --no-install-recommends gh 1password-cli=2.32.1-1 \
+    && apt-get purge -y xz-utils \
+    && apt-get autoremove -y \
     && rm -rf /var/lib/apt/lists/* \
     && node --version \
     && npm --version
@@ -56,14 +58,6 @@ RUN npm install -g mcporter@0.7.3
 # Install summarize (web page summarization CLI)
 RUN npm install -g @steipete/summarize@0.11.1
 
-# Install Linear CLI (issue tracker)
-RUN npm install -g @schpet/linear-cli@1.11.1
-
-# Clean up xz-utils now that Node.js and linear-cli are installed
-RUN apt-get purge -y xz-utils \
-    && apt-get autoremove -y \
-    && rm -rf /var/lib/apt/lists/*
-
 # Install Go (available at runtime for users to `go install` additional tools)
 ENV GO_VERSION=1.26.0
 RUN ARCH="$(dpkg --print-architecture)" \

kiloclaw/controller/src/bootstrap.test.ts

@@ -494,174 +494,38 @@ describe('configureGitHub', () => {
 describe('configureLinear', () => {
   it('logs configured when LINEAR_API_KEY is set', () => {
     const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-    const { deps } = fakeDeps();
     const env: Record<string, string | undefined> = {
       LINEAR_API_KEY: 'lin_api_test123',
     };
 
-    configureLinear(env, deps);
+    configureLinear(env);
 
     expect(env.LINEAR_API_KEY).toBe('lin_api_test123');
-    expect(logSpy).toHaveBeenCalledWith('Linear CLI configured via LINEAR_API_KEY');
+    expect(logSpy).toHaveBeenCalledWith('Linear MCP configured via LINEAR_API_KEY');
     logSpy.mockRestore();
   });
 
-  it('removes persisted config directory when no LINEAR_API_KEY', () => {
+  it('cleans up empty LINEAR_API_KEY and logs not configured', () => {
     const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-    const { deps, execCalls } = fakeDeps();
-    const env: Record<string, string | undefined> = {};
+    const env: Record<string, string | undefined> = {
+      LINEAR_API_KEY: '',
+    };
 
-    configureLinear(env, deps);
+    configureLinear(env);
 
     expect(env.LINEAR_API_KEY).toBeUndefined();
-    expect(execCalls).toContainEqual({
-      cmd: 'rm',
-      args: ['-rf', '/root/.config/linear'],
-      input: undefined,
-    });
-    expect(execCalls).toContainEqual({
-      cmd: 'rm',
-      args: ['-f', '/root/.linear.toml'],
-      input: undefined,
-    });
-    expect(logSpy).toHaveBeenCalledWith('Linear: not configured (credentials cleared)');
-    logSpy.mockRestore();
-  });
-
-  it('still removes ~/.linear.toml when /root/.config/linear removal fails', () => {
-    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const { deps } = fakeDeps();
-    const env: Record<string, string | undefined> = {};
-
-    // Make the first rm call throw, second should still succeed
-    const origExec = deps.execFileSync;
-    deps.execFileSync = vi.fn(
-      (cmd: string, args: string[], opts?: Parameters<BootstrapDeps['execFileSync']>[2]) => {
-        if (cmd === 'rm' && args.includes('/root/.config/linear')) {
-          throw new Error('permission denied');
-        }
-        return origExec(cmd, args, opts);
-      }
-    ) as typeof deps.execFileSync;
-
-    configureLinear(env, deps);
-
-    expect(warnSpy).toHaveBeenCalledWith(
-      'WARNING: failed to remove /root/.config/linear: permission denied'
-    );
-    // Second rm should still have been attempted
-    expect(deps.execFileSync).toHaveBeenCalledWith('rm', ['-f', '/root/.linear.toml'], {
-      stdio: 'pipe',
-    });
-    logSpy.mockRestore();
-    warnSpy.mockRestore();
-  });
-
-  it('warns when /root/.config/linear removal fails', () => {
-    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const { deps } = fakeDeps();
-    const env: Record<string, string | undefined> = {};
-
-    const origExec = deps.execFileSync;
-    deps.execFileSync = vi.fn(
-      (cmd: string, args: string[], opts?: Parameters<BootstrapDeps['execFileSync']>[2]) => {
-        if (cmd === 'rm' && args.includes('/root/.config/linear')) {
-          throw new Error('permission denied');
-        }
-        return origExec(cmd, args, opts);
-      }
-    ) as typeof deps.execFileSync;
-
-    configureLinear(env, deps);
-
-    expect(warnSpy).toHaveBeenCalledWith(
-      'WARNING: failed to remove /root/.config/linear: permission denied'
-    );
-    expect(logSpy).toHaveBeenCalledWith('Linear: not configured (credentials cleared)');
-    logSpy.mockRestore();
-    warnSpy.mockRestore();
-  });
-
-  it('warns when ~/.linear.toml removal fails', () => {
-    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const { deps } = fakeDeps();
-    const env: Record<string, string | undefined> = {};
-
-    const origExec = deps.execFileSync;
-    deps.execFileSync = vi.fn(
-      (cmd: string, args: string[], opts?: Parameters<BootstrapDeps['execFileSync']>[2]) => {
-        if (cmd === 'rm' && args.includes('/root/.linear.toml')) {
-          throw new Error('read-only filesystem');
-        }
-        return origExec(cmd, args, opts);
-      }
-    ) as typeof deps.execFileSync;
-
-    configureLinear(env, deps);
-
-    expect(warnSpy).toHaveBeenCalledWith(
-      'WARNING: failed to remove /root/.linear.toml: read-only filesystem'
-    );
-    expect(logSpy).toHaveBeenCalledWith('Linear: not configured (credentials cleared)');
-    logSpy.mockRestore();
-    warnSpy.mockRestore();
-  });
-
-  it('warns for both when both rm calls fail', () => {
-    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const { deps } = fakeDeps();
-    const env: Record<string, string | undefined> = {};
-
-    deps.execFileSync = vi.fn((cmd: string) => {
-      if (cmd === 'rm') throw new Error('disk full');
-      return '';
-    }) as typeof deps.execFileSync;
-
-    configureLinear(env, deps);
-
-    expect(warnSpy).toHaveBeenCalledWith(
-      'WARNING: failed to remove /root/.config/linear: disk full'
-    );
-    expect(warnSpy).toHaveBeenCalledWith('WARNING: failed to remove /root/.linear.toml: disk full');
-    expect(logSpy).toHaveBeenCalledWith('Linear: not configured (credentials cleared)');
+    expect(logSpy).toHaveBeenCalledWith('Linear: not configured');
     logSpy.mockRestore();
-    warnSpy.mockRestore();
   });
 
-  it('formats non-Error thrown values in warning', () => {
+  it('logs not configured when LINEAR_API_KEY is absent', () => {
     const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const { deps } = fakeDeps();
     const env: Record<string, string | undefined> = {};
 
-    deps.execFileSync = vi.fn((cmd: string) => {
-      if (cmd === 'rm') throw 'unexpected string error';
-      return '';
-    }) as typeof deps.execFileSync;
-
-    configureLinear(env, deps);
-
-    expect(warnSpy).toHaveBeenCalledWith(
-      'WARNING: failed to remove /root/.config/linear: unexpected string error'
-    );
-    logSpy.mockRestore();
-    warnSpy.mockRestore();
-  });
-
-  it('cleans up empty LINEAR_API_KEY', () => {
-    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-    const { deps } = fakeDeps();
-    const env: Record<string, string | undefined> = {
-      LINEAR_API_KEY: '',
-    };
-
-    configureLinear(env, deps);
+    configureLinear(env);
 
     expect(env.LINEAR_API_KEY).toBeUndefined();
+    expect(logSpy).toHaveBeenCalledWith('Linear: not configured');
     logSpy.mockRestore();
   });
 });
@@ -878,7 +742,7 @@ describe('updateToolsMdLinearSection', () => {
 
     expect(harness.writeCalls).toHaveLength(1);
     expect(harness.writeCalls[0]!.data).toContain('<!-- BEGIN:linear -->');
-    expect(harness.writeCalls[0]!.data).toContain('linear issue list');
+    expect(harness.writeCalls[0]!.data).toContain('Linear MCP');
     expect(harness.writeCalls[0]!.data).toContain('<!-- END:linear -->');
   });
 

kiloclaw/controller/src/bootstrap.ts

@@ -327,44 +327,17 @@ export function configureGitHub(env: EnvLike, deps: BootstrapDeps = defaultDeps)
 // ---- Step 6: Linear config ----
 
 /**
- * Configure or clean up Linear CLI access.
- * When LINEAR_API_KEY is present the CLI reads it natively.
- * When absent, clean up any on-disk credentials left by a previous
- * `linear auth login --plaintext` on the persistent volume.
- * Best-effort: logs warnings on failure, does not throw.
- *
- * The CLI stores two files under ~/.config/linear/:
- *   - credentials.toml  — workspace list + inline API keys (plaintext mode)
- *   - linear.toml        — global config that can also carry an api_key field
- * It may also create ~/.linear.toml (a project-level or legacy config file).
- * The system keyring is not available in this container (no libsecret-tools),
- * so these files are the only persistence locations.
+ * Configure or clean up Linear MCP access.
+ * Linear access is provided via the Linear MCP server configured in mcporter.
+ * When LINEAR_API_KEY is present, mcporter uses it to authenticate.
+ * When absent, we just clean up the env var. No on-disk artifacts to clean.
  */
-export function configureLinear(env: EnvLike, deps: BootstrapDeps = defaultDeps): void {
+export function configureLinear(env: EnvLike): void {
   if (env.LINEAR_API_KEY) {
-    console.log('Linear CLI configured via LINEAR_API_KEY');
+    console.log('Linear MCP configured via LINEAR_API_KEY');
   } else {
-    // Clean up env var if explicitly set to empty
     delete env.LINEAR_API_KEY;
-    // Remove any previously stored credentials from the persistent volume.
-    // The CLI recreates ~/.config/linear/ via ensureDir on next auth login.
-    // rm -rf/-f exit 0 when the target is absent, so errors here are
-    // genuine failures (permissions, I/O) worth surfacing.
-    try {
-      deps.execFileSync('rm', ['-rf', '/root/.config/linear'], { stdio: 'pipe' });
-    } catch (err) {
-      console.warn(
-        `WARNING: failed to remove /root/.config/linear: ${err instanceof Error ? err.message : err}`
-      );
-    }
-    try {
-      deps.execFileSync('rm', ['-f', '/root/.linear.toml'], { stdio: 'pipe' });
-    } catch (err) {
-      console.warn(
-        `WARNING: failed to remove /root/.linear.toml: ${err instanceof Error ? err.message : err}`
-      );
-    }
-    console.log('Linear: not configured (credentials cleared)');
+    console.log('Linear: not configured');
   }
 }
 
@@ -590,50 +563,18 @@ const LINEAR_MARKER_END = '<!-- END:linear -->';
 
 const LINEAR_TOOLS_SECTION = `
 ${LINEAR_MARKER_BEGIN}
-  ## Linear
-
-  The \`linear\` CLI is configured with your Linear API key. Use it to read and manage issues.
-
-  - Run \`linear --help\` for full command reference; \`--help\` after any subcommand for details.
-  - If you don't know the team key, run \`linear team list\`.
-
-  ### Listing issues
-
-  Example — list all issues by priority:
-  \`\`\`
-  linear issue list --team <key> --sort priority --all-states --all-assignees
-  \`\`\`
-
-  **Flags that silently filter results when omitted:**
-  - \`--state\` defaults to \`backlog\`. Use \`--all-states\` for all, or \`--state <value>\` to filter to one: triage, backlog, unstarted, started, completed, canceled
-  - \`--assignee\` defaults to \`me\`. Use \`--all-assignees\` for all, or \`--assignee <user>\` to filter to one
-
-  ### Writing issue content
-  Use file flags for markdown with newlines or special characters:
-  - \`--description-file <path>\` for \`issue create/update\`
-  - \`--body-file <path>\` for \`comment add/update\`
-
-  ### Config file
-  Avoid repeated \`--team\` and \`--sort\` flags with \`.linear.toml\` in the project directory:
-  \`\`\`toml
-  team = "TEAM_KEY"
-  sort = "priority"
-  \`\`\`
+## Linear
 
-  ### Gotchas
-  - \`--no-pager\` only works on \`issue list\` — errors on other commands
-  - GraphQL non-null types (\`String!\`) require heredoc: \`linear api --variable key=val <<'GRAPHQL'\`
+Linear is configured as your project management tool. Use it  to track issues, plan projects, and manage product roadmaps.
+You can interact with the \`Linear\` MCP server using your \`mcporter\` skill.
 
-  ### Advanced
-  - Get API token: \`linear auth token\`
-  - Direct GraphQL: \`curl -s -X POST https://api.linear.app/graphql -H "Authorization: $(linear auth token)" -d '{"query":"..."}'\`
   ${LINEAR_MARKER_END}`;
 
 /**
  * Manage the Linear section in TOOLS.md.
  *
  * When LINEAR_API_KEY is present, append a bounded section so the agent
- * knows the linear CLI is available. When absent, remove any stale section.
+ * knows Linear MCP is available. When absent, remove any stale section.
  * Idempotent: skips if the marker is already present.
  */
 export function updateToolsMdLinearSection(env: EnvLike, deps: BootstrapDeps): void {
@@ -718,7 +659,7 @@ export async function bootstrap(
   await yieldToEventLoop();
 
   setPhase('linear');
-  configureLinear(env, deps);
+  configureLinear(env);
   await yieldToEventLoop();
 
   const configExists = deps.existsSync(CONFIG_PATH);