@andypai/agent-kanban 0.2.0 → 0.3.1

package/src/index.ts

@@ -2,22 +2,16 @@
 
 import { parseArgs } from 'node:util'
 import { Database } from 'bun:sqlite'
-import { KanbanError, ErrorCode } from './errors.ts'
-import { formatOutput, error, success } from './output.ts'
-import { openDb, getDbPath, initSchema, migrateSchema, seedDefaultColumns } from './db.ts'
-import { boardInit, boardReset } from './commands/board.ts'
-import {
-  columnAdd,
-  columnDelete,
-  columnList,
-  columnRename,
-  columnReorder,
-} from './commands/column.ts'
-import { bulkClearDoneCmd, bulkMoveAllCmd } from './commands/bulk.ts'
-import { getConfigPath, loadConfig, saveConfig } from './config.ts'
-import type { CliOutput, Priority } from './types.ts'
-import { createProvider } from './providers/index.ts'
-import { unsupportedOperation } from './providers/errors.ts'
+import { KanbanError, ErrorCode } from './errors'
+import { formatOutput, error, success } from './output'
+import { openDb, getDbPath, initSchema, migrateSchema, seedDefaultColumns } from './db'
+import { boardInit, boardReset } from './commands/board'
+import { columnAdd, columnDelete, columnList, columnRename, columnReorder } from './commands/column'
+import { bulkClearDoneCmd, bulkMoveAllCmd } from './commands/bulk'
+import { getConfigPath, loadConfig, saveConfig } from './config'
+import type { CliOutput, Priority } from './types'
+import { createProvider } from './providers/index'
+import { unsupportedOperation } from './providers/errors'
 
 interface ParsedArgs {
   values: Record<string, unknown>
@@ -50,7 +44,7 @@ function parseCliArgs(argv: string[]): ParsedArgs {
 }
 
 function requireLocalProvider(providerType: string, feature: string): void {
-  if (providerType === 'linear') unsupportedOperation(`${feature} is only available in local mode`)
+  if (providerType !== 'local') unsupportedOperation(`${feature} is only available in local mode`)
 }
 
 async function routeTask(
@@ -197,7 +191,7 @@ async function routeConfig(
   positionals: string[],
   values: Record<string, unknown>,
 ): Promise<CliOutput> {
-  if (provider.type === 'linear') {
+  if (provider.type !== 'local') {
     if (action === 'show' || action === undefined) {
       return success(await provider.getConfig())
     }
@@ -357,6 +351,7 @@ Commands:
   config remove-project <name> Remove project
 
   serve                       Start web dashboard [--port 3000]
+  mcp                         Run as an MCP server over stdio (for Claude Desktop, etc.)
 
 Options:
   --pretty      Human-readable output (default: JSON)
@@ -364,29 +359,82 @@ Options:
   --project <n> Filter/set project
   -h, --help    Show this help`
 
+export interface ServeOptions {
+  db?: string
+  port: number
+  tunnel: boolean
+}
+
+export function parseServeArgs(argv: string[]): ServeOptions {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      db: { type: 'string' },
+      port: { type: 'string' },
+      tunnel: { type: 'boolean', default: false },
+    },
+    strict: false,
+    allowPositionals: true,
+  })
+  const port = values.port
+    ? parseInt(values.port as string, 10)
+    : parseInt(process.env['PORT'] || '3000', 10)
+  return {
+    db: values.db as string | undefined,
+    port,
+    tunnel: Boolean(values.tunnel),
+  }
+}
+
+export interface McpOptions {
+  db?: string
+}
+
+export function parseMcpArgs(argv: string[]): McpOptions {
+  const { values } = parseArgs({
+    args: argv,
+    options: { db: { type: 'string' } },
+    strict: false,
+    allowPositionals: true,
+  })
+  return { db: values.db as string | undefined }
+}
+
 if (import.meta.main) {
   const argv = process.argv.slice(2)
 
-  if (argv[0] === 'serve') {
-    const portIdx = argv.indexOf('--port')
-    const port =
-      portIdx !== -1
-        ? parseInt(argv[portIdx + 1]!, 10)
-        : parseInt(process.env['PORT'] || '3000', 10)
-
-    const { values } = parseArgs({
-      args: argv,
-      options: { db: { type: 'string' }, port: { type: 'string' } },
-      strict: false,
-      allowPositionals: true,
-    })
-
-    const dbPath = (values.db as string | undefined) ?? getDbPath()
+  if (argv[0] === 'mcp') {
+    const opts = parseMcpArgs(argv)
+    const dbPath = opts.db ?? getDbPath()
     const db = openDb(dbPath)
     migrateSchema(db)
     const provider = createProvider(db, dbPath)
-    const { startServer } = await import('./server.ts')
-    startServer(provider, port)
+    const { startStdioMcpServer } = await import('./commands/mcp')
+    await startStdioMcpServer(provider)
+  } else if (argv[0] === 'serve') {
+    const opts = parseServeArgs(argv)
+
+    const dbPath = opts.db ?? getDbPath()
+    const db = openDb(dbPath)
+    migrateSchema(db)
+    const provider = createProvider(db, dbPath)
+    const { startServer } = await import('./server')
+    startServer(provider, opts.port)
+
+    if (opts.tunnel) {
+      const { startCloudflareTunnel } = await import('./tunnel')
+      try {
+        const handle = startCloudflareTunnel(opts.port)
+        const shutdown = (): void => {
+          handle.stop()
+          process.exit(0)
+        }
+        process.on('SIGINT', shutdown)
+        process.on('SIGTERM', shutdown)
+      } catch {
+        // startCloudflareTunnel already logged a friendly message
+      }
+    }
   } else {
     let exitCode = 0
     const pretty = argv.includes('--pretty')

package/src/mcp/core.ts

@@ -0,0 +1,193 @@
+import type { KanbanProvider } from '../providers/types'
+import type { Task, TaskComment } from '../types'
+import { TrackerMcpError, toTrackerMcpError } from './errors'
+import type { TrackerMcpHooks, TrackerMcpPolicy } from './types'
+
+export interface TrackerCore<TScope> {
+  notifyAuthFailure(input: {
+    request: Request
+    durationMs: number
+    error: TrackerMcpError
+  }): Promise<void>
+  notifyToolError(input: {
+    scope: TScope | null
+    tool: string
+    ticketId?: string
+    durationMs: number
+    error: TrackerMcpError
+  }): Promise<void>
+  handlers: {
+    getTicket(input: { scope: TScope; ticketId: string }): Promise<Task>
+    listComments(input: { scope: TScope; ticketId: string }): Promise<TaskComment[]>
+    getBoard(input: { scope: TScope }): Promise<Awaited<ReturnType<KanbanProvider['getBoard']>>>
+    postComment(input: { scope: TScope; ticketId: string; body: string }): Promise<TaskComment>
+    updateComment(input: {
+      scope: TScope
+      ticketId: string
+      commentId: string
+      body: string
+    }): Promise<TaskComment>
+    moveTicket(input: { scope: TScope; ticketId: string; column: string }): Promise<void>
+  }
+}
+
+interface RunToolInput<TScope, TResult> {
+  scope: TScope
+  tool: string
+  ticketId?: string
+  execute(): Promise<TResult>
+  resultMeta?: Record<string, unknown> | ((result: TResult) => Record<string, unknown> | undefined)
+}
+
+async function filterComments<TScope>(
+  scope: TScope,
+  comments: TaskComment[],
+  policy: TrackerMcpPolicy<TScope>,
+): Promise<TaskComment[]> {
+  if (!policy.filterComment) return comments
+  const allowed = await Promise.all(
+    comments.map((comment) => policy.filterComment!(scope, comment)),
+  )
+  return comments.filter((_, index) => allowed[index])
+}
+
+export function createTrackerCore<TScope>(input: {
+  provider: KanbanProvider
+  policy: TrackerMcpPolicy<TScope>
+  hooks?: TrackerMcpHooks<TScope>
+}): TrackerCore<TScope> {
+  const { provider, policy } = input
+  const hooks = input.hooks ?? {}
+
+  async function runTool<TResult>({
+    scope,
+    tool,
+    ticketId,
+    execute,
+    resultMeta,
+  }: RunToolInput<TScope, TResult>): Promise<TResult> {
+    const startedAt = Date.now()
+    await hooks.onToolStart?.({ scope, tool, ticketId })
+    try {
+      const result = await execute()
+      const hookResult = typeof resultMeta === 'function' ? resultMeta(result) : resultMeta
+      await hooks.onToolResult?.({
+        scope,
+        tool,
+        ticketId,
+        durationMs: Date.now() - startedAt,
+        result: hookResult,
+      })
+      return result
+    } catch (error) {
+      const trackerError = toTrackerMcpError(error)
+      await hooks.onToolError?.({
+        scope,
+        tool,
+        ticketId,
+        durationMs: Date.now() - startedAt,
+        errorCode: trackerError.code,
+        error: trackerError,
+      })
+      throw trackerError
+    }
+  }
+
+  return {
+    async notifyAuthFailure({ request, durationMs, error }) {
+      await hooks.onAuthFailure?.({
+        request,
+        durationMs,
+        errorCode: 'auth_failed',
+        error,
+      })
+    },
+
+    async notifyToolError({ scope, tool, ticketId, durationMs, error }) {
+      await hooks.onToolError?.({
+        scope,
+        tool,
+        ticketId,
+        durationMs,
+        errorCode: error.code,
+        error,
+      })
+    },
+
+    handlers: {
+      getTicket({ scope, ticketId }) {
+        return runTool({
+          scope,
+          tool: 'getTicket',
+          ticketId,
+          execute: async () => {
+            await policy.canReadTicket(scope, ticketId)
+            return provider.getTask(ticketId)
+          },
+        })
+      },
+
+      listComments({ scope, ticketId }) {
+        return runTool({
+          scope,
+          tool: 'listComments',
+          ticketId,
+          execute: async () => {
+            await policy.canReadTicket(scope, ticketId)
+            const comments = await provider.listComments(ticketId)
+            return filterComments(scope, comments, policy)
+          },
+          resultMeta: (comments) => ({ commentCount: comments.length }),
+        })
+      },
+
+      getBoard({ scope }) {
+        return runTool({
+          scope,
+          tool: 'getBoard',
+          execute: async () => provider.getBoard(),
+        })
+      },
+
+      postComment({ scope, ticketId, body }) {
+        return runTool({
+          scope,
+          tool: 'postComment',
+          ticketId,
+          execute: async () => {
+            await policy.canPostComment(scope, ticketId, body)
+            return provider.comment(ticketId, body)
+          },
+          resultMeta: (comment) => ({ commentId: comment.id }),
+        })
+      },
+
+      updateComment({ scope, ticketId, commentId, body }) {
+        return runTool({
+          scope,
+          tool: 'updateComment',
+          ticketId,
+          execute: async () => {
+            const existing = await provider.getComment(ticketId, commentId)
+            await policy.canUpdateComment(scope, ticketId, existing, body)
+            return provider.updateComment(ticketId, commentId, body)
+          },
+          resultMeta: (comment) => ({ commentId: comment.id }),
+        })
+      },
+
+      moveTicket({ scope, ticketId, column }) {
+        return runTool({
+          scope,
+          tool: 'moveTicket',
+          ticketId,
+          execute: async () => {
+            await policy.canMoveTicket(scope, ticketId, column)
+            await provider.moveTask(ticketId, column)
+          },
+          resultMeta: { movedTo: column },
+        })
+      },
+    },
+  }
+}

package/src/mcp/errors.ts

@@ -0,0 +1,109 @@
+import { McpError, ErrorCode as JsonRpcErrorCode } from '@modelcontextprotocol/sdk/types.js'
+import { ErrorCode, type ErrorCodeValue, KanbanError } from '../errors'
+
+export type TrackerMcpErrorCode =
+  | 'auth_failed'
+  | 'policy_denied'
+  | 'ticket_not_found'
+  | 'comment_not_found'
+  | 'validation_failed'
+  | 'provider_unavailable'
+  | 'internal_error'
+
+export class TrackerMcpError extends Error {
+  override readonly name = 'TrackerMcpError'
+  readonly code: TrackerMcpErrorCode
+  override readonly cause?: unknown
+  readonly publicMessage?: string
+
+  constructor(input: {
+    code: TrackerMcpErrorCode
+    message?: string
+    publicMessage?: string
+    cause?: unknown
+  }) {
+    super(input.message ?? input.publicMessage ?? input.code)
+    this.code = input.code
+    this.cause = input.cause
+    this.publicMessage = input.publicMessage
+  }
+}
+
+function providerError(code: ErrorCodeValue): TrackerMcpErrorCode {
+  switch (code) {
+    case ErrorCode.TASK_NOT_FOUND:
+      return 'ticket_not_found'
+    case ErrorCode.COMMENT_NOT_FOUND:
+      return 'comment_not_found'
+    case ErrorCode.COLUMN_NOT_FOUND:
+    case ErrorCode.INVALID_METADATA:
+    case ErrorCode.INVALID_POSITION:
+    case ErrorCode.INVALID_PRIORITY:
+    case ErrorCode.MISSING_ARGUMENT:
+    case ErrorCode.UNSUPPORTED_OPERATION:
+    case ErrorCode.CONFLICT:
+      return 'validation_failed'
+    case ErrorCode.PROVIDER_AUTH_FAILED:
+    case ErrorCode.PROVIDER_RATE_LIMITED:
+    case ErrorCode.PROVIDER_UPSTREAM_ERROR:
+    case ErrorCode.PROVIDER_SYNC_REQUIRED:
+    case ErrorCode.PROVIDER_NOT_CONFIGURED:
+      return 'provider_unavailable'
+    default:
+      return 'internal_error'
+  }
+}
+
+export function toTrackerMcpError(error: unknown): TrackerMcpError {
+  if (error instanceof TrackerMcpError) return error
+  if (error instanceof KanbanError) {
+    return new TrackerMcpError({
+      code: providerError(error.code),
+      message: error.message,
+      publicMessage: error.message,
+      cause: error,
+    })
+  }
+  if (error instanceof Error) {
+    return new TrackerMcpError({
+      code: 'internal_error',
+      message: error.message,
+      publicMessage: error.message,
+      cause: error,
+    })
+  }
+  return new TrackerMcpError({
+    code: 'internal_error',
+    message: String(error),
+    publicMessage: String(error),
+    cause: error,
+  })
+}
+
+export function trackerMcpJsonRpcCode(code: TrackerMcpErrorCode): number {
+  switch (code) {
+    case 'auth_failed':
+      return -32001
+    case 'policy_denied':
+      return -32002
+    case 'ticket_not_found':
+    case 'comment_not_found':
+      return -32003
+    case 'validation_failed':
+      return JsonRpcErrorCode.InvalidParams
+    case 'provider_unavailable':
+      return -32010
+    case 'internal_error':
+    default:
+      return JsonRpcErrorCode.InternalError
+  }
+}
+
+export function toMcpError(error: unknown): McpError {
+  const trackerError = toTrackerMcpError(error)
+  return new McpError(
+    trackerMcpJsonRpcCode(trackerError.code),
+    trackerError.publicMessage ?? trackerError.message,
+    { trackerMcpCode: trackerError.code },
+  )
+}

package/src/mcp/index.ts

@@ -0,0 +1,13 @@
+export { createTrackerCore } from './core'
+export { createTrackerMcpServer } from './server'
+export { TrackerMcpError, type TrackerMcpErrorCode } from './errors'
+export type { TrackerCore } from './core'
+export type {
+  TrackerMcpAuthResolver,
+  TrackerMcpHooks,
+  TrackerMcpPolicy,
+  TrackerMcpServer,
+  TrackerMcpTool,
+  TrackerMcpToolHandlerContext,
+} from './types'
+export { defaultTools } from './server'