instances

Instructions

Implementation Reference

• src/tools/simplified.ts:133-169 (handler)

  The tool handler for 'instances'. Registers the MCP tool with server.tool(), calls registry.refresh() to get instances, enriches them with busy/idle status and recent session info, then formats and returns the result.

  server.tool(
    'instances',
    'List all connected opencode instances with their current status (busy/idle). Call this to see what machines are available.',
    {},
    async () => {
      try {
        const instances = await registry.refresh()
  
        const enriched = await Promise.all(
          instances
            .filter((inst) => inst.online)
            .map(async (inst) => {
              const { busySessionId } = await getInstanceStatus(inst.url)
              const session = await findMostRecentSession(inst.url)
              const status = busySessionId ? 'busy' : 'idle'
              return {
                instance: inst,
                status,
                recentSession: session?.title,
              }
            }),
        )
  
        return {
          content: [
            { type: 'text', text: formatInstanceList(enriched) },
          ],
        }
      } catch (err) {
        return {
          content: [
            { type: 'text', text: `Error: ${(err as Error).message}` },
          ],
          isError: true,
        }
      }
    },

• src/index.ts:38-38 (registration)

  Registration call that wires 'instances' tool into the MCP server. registerSimplifiedTools(server, registry) is called from the main entry point.

  registerSimplifiedTools(server, registry)

• src/tools/simplified.ts:105-127 (helper)

  Helper function formatInstanceList that formats the instances list into a user-readable string output.

  function formatInstanceList(
    instances: Array<{
      instance: OpenCodeInstance
      status: string
      recentSession?: string
    }>,
  ): string {
    if (instances.length === 0) {
      return 'No opencode instances are currently connected.\n\nRun `opencode-connected` on a machine to register one.'
    }
  
    const lines: string[] = []
    for (const { instance, status, recentSession } of instances) {
      const session = recentSession ? ` — "${recentSession}"` : ''
      lines.push(
        `**${instance.name}** (${instance.hostname}:${instance.cwd})`,
      )
      lines.push(
        `  ${instance.online ? 'online' : 'offline'} | ${status}${session} | v${instance.version ?? 'unknown'}`,
      )
    }
    return lines.join('\n')
  }

• src/tools/simplified.ts:56-68 (helper)

  Helper function getInstanceStatus that checks the busy/idle status of sessions on an instance via the /session/status endpoint.

  async function getInstanceStatus(
    baseUrl: string,
  ): Promise<{ statuses: Record<string, string>; busySessionId?: string }> {
    try {
      const res = await fetch(`${baseUrl}/session/status`)
      if (!res.ok) return { statuses: {} }
      const data = (await res.json()) as Record<
        string,
        { type: string }
      >
      const statuses: Record<string, string> = {}
      let busySessionId: string | undefined
      for (const [id, info] of Object.entries(data)) {

• src/tools/simplified.ts:90-102 (helper)

  Helper function findMostRecentSession that finds the most recently updated session on an instance via the /session endpoint.

  async function findMostRecentSession(
    baseUrl: string,
  ): Promise<SessionInfo | undefined> {
    try {
      const res = await fetch(`${baseUrl}/session`)
      if (!res.ok) return undefined
      const sessions = (await res.json()) as SessionInfo[]
      if (sessions.length === 0) return undefined
      sessions.sort((a, b) => b.time.updated - a.time.updated)
      return sessions[0]
    } catch {
      return undefined
    }