@363045841yyt/klinechart-ai-runtime 0.1.0

package/src/index.ts

@@ -0,0 +1,38 @@
+export type * from './types'
+
+export {
+  ALL_TOOLS,
+  TOOL_GROUPS,
+  CHART_NAVIGATION_TOOLS,
+  INDICATOR_TOOLS,
+  ALERT_TOOLS,
+  REPLAY_TOOLS,
+  findTool,
+} from './toolSchemas'
+
+export {
+  describeVolumeProfileState,
+  describeAnchoredVwap,
+  describeFootprintLatestBar,
+  describeAlerts,
+  type VolumeProfileSnapshot,
+  type AnchoredVwapSeriesSnapshot,
+  type FootprintLatestBarSnapshot,
+  type AlertSnapshot,
+} from './describeControllers'
+
+export {
+  serialize,
+  deserialize,
+  ChartSerializationError,
+  type ChartSnapshotInput,
+} from './serialization'
+
+export { executeTool, type ToolCall, type ToolResult } from './executeTool'
+
+export { SessionRegistry, type SessionHandle } from './sessionRegistry'
+
+export {
+  createChartControllerWithMcp,
+  type CreateChartWithMcpOptions,
+} from './createWithMcp'

package/src/mcpServer.ts

@@ -0,0 +1,268 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js'
+import { WebSocketServer, type WebSocket } from 'ws'
+import type { ToolCall, ToolResult } from './executeTool'
+import { ALL_TOOLS } from './toolSchemas'
+import type { ControllerDescription } from './types'
+import { SessionRegistry, type SessionHandle } from './sessionRegistry'
+
+class WsSessionHandle implements SessionHandle {
+  readonly sessionId: string
+  private ws: WebSocket
+  private pending = new Map<
+    string,
+    { resolve: (r: ToolResult) => void; reject: (e: Error) => void }
+  >()
+  private msgSeq = 0
+
+  constructor(
+    sessionId: string,
+    ws: WebSocket,
+  ) {
+    this.sessionId = sessionId
+    this.ws = ws
+  }
+
+  async executeTool(call: ToolCall): Promise<ToolResult> {
+    const requestId = `${this.sessionId}:${++this.msgSeq}`
+
+    return new Promise((resolve, reject) => {
+      this.pending.set(requestId, { resolve, reject })
+
+      if (this.ws.readyState !== this.ws.OPEN) {
+        this.pending.delete(requestId)
+        reject(new Error('WebSocket is not open'))
+        return
+      }
+
+      this.ws.send(
+        JSON.stringify({ type: 'tool:call', requestId, call }),
+      )
+
+      setTimeout(() => {
+        const p = this.pending.get(requestId)
+        if (p) {
+          this.pending.delete(requestId)
+          reject(new Error(`Tool call timed out: ${call.name}`))
+        }
+      }, 30_000)
+    })
+  }
+
+  handleMessage(msg: Record<string, unknown>): void {
+    if (msg.type === 'tool:result') {
+      const requestId = msg.requestId as string
+      const pending = this.pending.get(requestId)
+      if (pending) {
+        this.pending.delete(requestId)
+        pending.resolve(msg.result as ToolResult)
+      }
+    }
+  }
+
+  isAlive(): boolean {
+    return this.ws.readyState === this.ws.OPEN
+  }
+}
+
+export type { WsSessionHandle }
+
+interface ToolResponseContent {
+  type: 'text'
+  text: string
+}
+
+export interface McpServerOptions {
+  serverInfo?: { name?: string; version?: string }
+  ws?: { port?: number; host?: string }
+  registry?: SessionRegistry
+}
+
+export interface McpServerInstance {
+  server: Server
+  registry: SessionRegistry
+  wss: WebSocketServer
+  start(): Promise<void>
+  stop(): Promise<void>
+}
+
+export function createMcpServer(options: McpServerOptions = {}): McpServerInstance {
+  const registry = options.registry ?? new SessionRegistry()
+  const wsPort = options.ws?.port ?? 8080
+  const wsHost = options.ws?.host ?? '0.0.0.0'
+
+  const serverInfoName = options.serverInfo?.name ?? 'klinechart-ai-mcp'
+  const serverInfoVersion = options.serverInfo?.version ?? '0.0.0'
+
+  const server = new Server(
+    {
+      name: serverInfoName,
+      version: serverInfoVersion,
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    },
+  )
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: ALL_TOOLS.map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema,
+    })),
+  }))
+
+  server.setRequestHandler(
+    CallToolRequestSchema,
+    async (request: {
+      params: { name: string; arguments?: Record<string, unknown> }
+    }) => {
+      const { name, arguments: args } = request.params
+      const schema = ALL_TOOLS.find((t) => t.name === name)
+
+      if (!schema) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({
+                success: false,
+                error: `Unknown tool: ${name}`,
+              }),
+            },
+          ],
+          isError: true,
+        }
+      }
+
+      const sessions = registry.getActiveSessionIds()
+      if (sessions.length === 0) {
+        console.warn(`[MCP] CallTool "${name}" but no sessions registered`)
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({
+                success: false,
+                error: 'No browser chart session connected.',
+              }),
+            },
+          ],
+          isError: true,
+        }
+      }
+
+      const sessionId = sessions[0]!
+      const handle = registry.get(sessionId)
+      if (!handle) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({
+                success: false,
+                error: `Session ${sessionId} not found.`,
+              }),
+            },
+          ],
+          isError: true,
+        }
+      }
+
+      const result = await handle.executeTool({
+        name,
+        input: args ?? {},
+      })
+
+      const summary = registry.getSummary(sessionId)
+      const texts: string[] = [JSON.stringify(result)]
+      if (summary) texts.push(`Chart state: ${summary}`)
+
+      return {
+        content: texts.map(
+          (text): ToolResponseContent => ({ type: 'text' as const, text }),
+        ),
+      }
+    },
+  )
+
+  const wss = new WebSocketServer({ port: wsPort, host: wsHost })
+  wss.on('error', (err: NodeJS.ErrnoException) => {
+    console.error(`[MCP] WebSocket server error: ${err.message}`)
+    if (err.code === 'EADDRINUSE') {
+      console.error(
+        `[MCP] Port ${wsPort} is already in use. Use a different port via WS_PORT env or ws.port option.`,
+      )
+    }
+  })
+
+  wss.on('connection', (ws: WebSocket) => {
+    console.error(`[MCP] WS client connected`)
+    let handle: WsSessionHandle | null = null
+
+    ws.on('message', (raw: Buffer) => {
+      let msg: Record<string, unknown>
+      try {
+        msg = JSON.parse(raw.toString())
+      } catch {
+        return
+      }
+
+      if (msg.type === 'register') {
+        const sessionId = (msg.sessionId as string) ?? crypto.randomUUID()
+        handle = new WsSessionHandle(sessionId, ws)
+        registry.register(sessionId, handle)
+        console.error(
+          `[MCP] Session registered: ${sessionId} (total=${registry.getActiveSessionIds().length})`,
+        )
+        ws.send(JSON.stringify({ type: 'registered', sessionId }))
+        return
+      }
+
+      if (handle) {
+        handle.handleMessage(msg)
+      }
+
+      if (msg.type === 'state:update' && handle) {
+        registry.updateState(
+          handle.sessionId,
+          msg.descriptions as Record<string, ControllerDescription>,
+        )
+      }
+    })
+
+    ws.on('close', () => {
+      if (handle) {
+        console.error(`[MCP] Session disconnected: ${handle.sessionId}`)
+        registry.unregister(handle.sessionId)
+      }
+    })
+
+    ws.on('error', () => {
+      if (handle) {
+        registry.unregister(handle.sessionId)
+      }
+    })
+  })
+
+  async function start(): Promise<void> {
+    const transport = new StdioServerTransport()
+    await server.connect(transport)
+  }
+
+  async function stop(): Promise<void> {
+    await server.close()
+    for (const ws of wss.clients) {
+      ws.terminate()
+    }
+    wss.close()
+  }
+
+  return { server, registry, wss, start, stop }
+}

package/src/serialization.ts

@@ -0,0 +1,88 @@
+import type { SerializedChartState } from './types'
+
+const SCHEMA_VERSION = 1 as const
+
+export class ChartSerializationError extends Error {
+  readonly code: string
+  constructor(code: string, message: string) {
+    super(message)
+    this.name = 'ChartSerializationError'
+    this.code = code
+  }
+}
+
+export interface ChartSnapshotInput {
+  label?: string
+  viewport?: { zoomLevel: number; visibleFrom: number; visibleTo: number }
+  theme?: 'light' | 'dark'
+  indicators?: ReadonlyArray<{
+    definitionId: string
+    params: Readonly<Record<string, number | string | boolean>>
+  }>
+  alerts?: ReadonlyArray<{
+    id: string
+    name: string
+    predicate: unknown
+    oneShot: boolean
+    cooldownMs?: number
+  }>
+}
+
+export function serialize(
+  snapshot: ChartSnapshotInput,
+): SerializedChartState {
+  const controllers: SerializedChartState['controllers'] = {}
+  if (snapshot.viewport !== undefined) controllers.viewport = snapshot.viewport
+  if (snapshot.theme !== undefined) controllers.theme = snapshot.theme
+  if (snapshot.indicators !== undefined)
+    controllers.indicators = snapshot.indicators
+  if (snapshot.alerts !== undefined) controllers.alerts = snapshot.alerts
+  const out: SerializedChartState = {
+    schemaVersion: SCHEMA_VERSION,
+    snapshotTakenAt: new Date().toISOString(),
+    controllers,
+  }
+  if (snapshot.label !== undefined) out.label = snapshot.label
+  return out
+}
+
+export function deserialize(json: string): SerializedChartState {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(json)
+  } catch (err) {
+    throw new ChartSerializationError(
+      'INVALID_JSON',
+      `Could not parse SerializedChartState as JSON: ${(err as Error).message}`,
+    )
+  }
+  if (typeof parsed !== 'object' || parsed === null) {
+    throw new ChartSerializationError(
+      'NOT_OBJECT',
+      'SerializedChartState root must be an object.',
+    )
+  }
+  const root = parsed as Partial<SerializedChartState>
+  if (root.schemaVersion !== SCHEMA_VERSION) {
+    throw new ChartSerializationError(
+      'SCHEMA_VERSION_MISMATCH',
+      `Expected schemaVersion ${SCHEMA_VERSION}, got ${String(root.schemaVersion)}.`,
+    )
+  }
+  if (
+    typeof root.snapshotTakenAt !== 'string' ||
+    Number.isNaN(Date.parse(root.snapshotTakenAt))
+  ) {
+    throw new ChartSerializationError(
+      'INVALID_TIMESTAMP',
+      'snapshotTakenAt must be an ISO 8601 string.',
+    )
+  }
+  if (typeof root.controllers !== 'object' || root.controllers === null) {
+    throw new ChartSerializationError(
+      'MISSING_CONTROLLERS',
+      'controllers object is required.',
+    )
+  }
+  return root as SerializedChartState
+}

package/src/sessionRegistry.ts

@@ -0,0 +1,61 @@
+import type { ToolCall, ToolResult } from './executeTool'
+import type { ControllerDescription } from './types'
+
+export interface SessionHandle {
+  readonly sessionId: string
+  executeTool(call: ToolCall): Promise<ToolResult>
+}
+
+export class SessionRegistry {
+  private sessions = new Map<string, SessionHandle>()
+  private states = new Map<string, Record<string, ControllerDescription>>()
+
+  register(sessionId: string, handle: SessionHandle): void {
+    this.sessions.set(sessionId, handle)
+    this.states.set(sessionId, {})
+  }
+
+  unregister(sessionId: string): void {
+    this.sessions.delete(sessionId)
+    this.states.delete(sessionId)
+  }
+
+  get(sessionId: string): SessionHandle | undefined {
+    return this.sessions.get(sessionId)
+  }
+
+  has(sessionId: string): boolean {
+    return this.sessions.has(sessionId)
+  }
+
+  getActiveSessionIds(): string[] {
+    return Array.from(this.sessions.keys())
+  }
+
+  updateState(
+    sessionId: string,
+    descriptions: Record<string, ControllerDescription>,
+  ): void {
+    const existing = this.states.get(sessionId)
+    if (existing) {
+      Object.assign(existing, descriptions)
+    }
+  }
+
+  getState(
+    sessionId: string,
+  ): Record<string, ControllerDescription> | undefined {
+    return this.states.get(sessionId)
+  }
+
+  getSummary(sessionId: string): string {
+    const descriptions = this.states.get(sessionId)
+    if (!descriptions) return 'No state available.'
+
+    const parts: string[] = []
+    for (const desc of Object.values(descriptions)) {
+      parts.push(`[${desc.controllerId}] ${desc.summary}`)
+    }
+    return parts.length > 0 ? parts.join(' | ') : 'No controllers described.'
+  }
+}

package/src/toolSchemas.ts

@@ -0,0 +1,235 @@
+import type { McpToolSchema } from './types'
+
+export const CHART_NAVIGATION_TOOLS: McpToolSchema[] = [
+  {
+    name: 'chart.zoomToLevel',
+    description:
+      'Zoom the chart to a specific discrete level (1 = most zoomed out, ' +
+      'higher numbers = more zoomed in). Use when the user says "zoom in", ' +
+      '"zoom out", "fit the chart", or asks for a specific zoom level.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        level: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 20,
+          description: 'Discrete zoom level. Higher = more zoomed in.',
+        },
+        anchorX: {
+          type: 'number',
+          description: 'Optional X coordinate to keep stationary during zoom.',
+        },
+      },
+      required: ['level'],
+    },
+    safety: 'mutates-state',
+  },
+  {
+    name: 'chart.setTheme',
+    description:
+      'Switch between light and dark theme. Use when the user asks for ' +
+      '"dark mode", "light mode", or expresses a theme preference.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        theme: { type: 'string', enum: ['light', 'dark'] },
+      },
+      required: ['theme'],
+    },
+    safety: 'mutates-state',
+  },
+]
+
+export const INDICATOR_TOOLS: McpToolSchema[] = [
+  {
+    name: 'indicators.add',
+    description:
+      'Add a technical indicator to the chart by its catalog id (e.g. "MA", ' +
+      '"BOLL", "MACD", "RSI"). Use when the user asks to "add a moving ' +
+      'average", "show MACD", "I want to see Bollinger Bands", etc.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        definitionId: {
+          type: 'string',
+          description:
+            'Catalog id of the indicator. Common: MA, EMA, BOLL, EXPMA, ' +
+            'MACD, RSI, KDJ, VOL, ATR, OBV.',
+        },
+      },
+      required: ['definitionId'],
+    },
+    outputSchema: {
+      type: 'object',
+      properties: {
+        instanceId: {
+          type: 'string',
+          description:
+            'New instance id, or null if the indicator was already active.',
+        },
+      },
+    },
+    safety: 'mutates-state',
+  },
+  {
+    name: 'indicators.remove',
+    description: 'Remove an indicator instance by its instance id.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instanceId: { type: 'string' },
+      },
+      required: ['instanceId'],
+    },
+    safety: 'mutates-state',
+  },
+  {
+    name: 'indicators.updateParams',
+    description:
+      'Change the parameters of an active indicator (e.g. MA period from ' +
+      '20 to 50, BOLL multiplier from 2 to 2.5).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instanceId: { type: 'string' },
+        params: {
+          type: 'object',
+          properties: {},
+          additionalProperties: true,
+          description: 'Param key to value map (numbers, strings, booleans).',
+        },
+      },
+      required: ['instanceId', 'params'],
+    },
+    safety: 'mutates-state',
+  },
+]
+
+export const ALERT_TOOLS: McpToolSchema[] = [
+  {
+    name: 'alerts.addPriceCross',
+    description:
+      'Create a price-crossing alert. Use when the user says "alert me when ' +
+      'BTC crosses 100k", "tell me when price drops below X", "wake me up at Y".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Unique alert id.' },
+        name: { type: 'string', description: 'Human-readable label.' },
+        price: { type: 'number' },
+        direction: { type: 'string', enum: ['up', 'down', 'any'] },
+        oneShot: {
+          type: 'boolean',
+          description: 'If true, fires once then auto-disables.',
+        },
+      },
+      required: ['id', 'name', 'price', 'direction', 'oneShot'],
+    },
+    safety: 'mutates-state',
+  },
+  {
+    name: 'alerts.addIndicatorCross',
+    description:
+      'Alert when an indicator value crosses a threshold (e.g. RSI > 70, MACD ' +
+      'histogram goes positive).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' },
+        name: { type: 'string' },
+        indicatorId: { type: 'string' },
+        threshold: { type: 'number' },
+        direction: { type: 'string', enum: ['up', 'down', 'any'] },
+        oneShot: { type: 'boolean' },
+      },
+      required: [
+        'id',
+        'name',
+        'indicatorId',
+        'threshold',
+        'direction',
+        'oneShot',
+      ],
+    },
+    safety: 'mutates-state',
+  },
+  {
+    name: 'alerts.remove',
+    description:
+      'Remove an existing alert rule by its id. Use when the user says ' +
+      '"cancel the BTC alert", "delete that alert", "I no longer need notification X".',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: ['id'],
+    },
+    safety: 'mutates-state',
+  },
+]
+
+export const REPLAY_TOOLS: McpToolSchema[] = [
+  {
+    name: 'replay.seekTo',
+    description:
+      'Move the replay cursor to a specific bar index. Use when the user says ' +
+      '"go to bar X", "rewind to the start", "show me what happened at this point".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        position: { type: 'number', description: 'Bar index (float).' },
+      },
+      required: ['position'],
+    },
+    safety: 'mutates-state',
+  },
+  {
+    name: 'replay.play',
+    description:
+      'Start replay from the current cursor at the configured pacing and speed. ' +
+      'Use when the user says "play", "start replay", "go".',
+    inputSchema: { type: 'object', properties: {} },
+    safety: 'mutates-state',
+  },
+  {
+    name: 'replay.pause',
+    description:
+      'Pause the replay at the current bar. Use when the user says "pause", ' +
+      '"stop", "hold on", or wants to inspect a specific bar.',
+    inputSchema: { type: 'object', properties: {} },
+    safety: 'mutates-state',
+  },
+  {
+    name: 'replay.setSpeed',
+    description:
+      'Set replay speed multiplier (1.0 = real-time, 10.0 = 10x speed). ' +
+      'Use when the user says "faster", "slow down", "real-time".',
+    inputSchema: {
+      type: 'object',
+      properties: { speed: { type: 'number', minimum: 0.01 } },
+      required: ['speed'],
+    },
+    safety: 'mutates-state',
+  },
+]
+
+export const ALL_TOOLS: ReadonlyArray<McpToolSchema> = [
+  ...CHART_NAVIGATION_TOOLS,
+  ...INDICATOR_TOOLS,
+  ...ALERT_TOOLS,
+  ...REPLAY_TOOLS,
+]
+
+export const TOOL_GROUPS = {
+  navigation: CHART_NAVIGATION_TOOLS,
+  indicators: INDICATOR_TOOLS,
+  alerts: ALERT_TOOLS,
+  replay: REPLAY_TOOLS,
+} as const
+
+export function findTool(name: string): McpToolSchema | null {
+  for (const tool of ALL_TOOLS) {
+    if (tool.name === name) return tool
+  }
+  return null
+}