@andypai/agent-kanban 0.2.0 → 0.3.0

package/src/mcp/core.ts

@@ -0,0 +1,193 @@
+import type { KanbanProvider } from '../providers/types.ts'
+import type { Task, TaskComment } from '../types.ts'
+import { TrackerMcpError, toTrackerMcpError } from './errors.ts'
+import type { TrackerMcpHooks, TrackerMcpPolicy } from './types.ts'
+
+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.ts'
+
+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.ts'
+export { createTrackerMcpServer } from './server.ts'
+export { TrackerMcpError, type TrackerMcpErrorCode } from './errors.ts'
+export type { TrackerCore } from './core.ts'
+export type {
+  TrackerMcpAuthResolver,
+  TrackerMcpHooks,
+  TrackerMcpPolicy,
+  TrackerMcpServer,
+  TrackerMcpTool,
+  TrackerMcpToolHandlerContext,
+} from './types.ts'
+export { defaultTools } from './server.ts'