@foundation0/api 1.1.11 → 1.1.13

package/mcp/client.ts

@@ -1,565 +1,565 @@
-import { Client } from '@modelcontextprotocol/sdk/client/index.js'
-import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
-import { CallToolResultSchema, ListToolsResultSchema } from '@modelcontextprotocol/sdk/types.js'
-import crypto from 'node:crypto'
-import fs from 'node:fs/promises'
-import os from 'node:os'
-import path from 'node:path'
-
-type ToolResultText = {
-  type: 'text'
-  text: string
-}
-
-type ToolResult = {
-  isError?: boolean
-  content?: ToolResultText[]
-}
-
-const DEFAULT_REQUEST_TIMEOUT_MS = 5 * 60 * 1000
-const DEFAULT_MAX_INLINE_FILE_LINES = 300
-const DEFAULT_FILE_CACHE_DIR = path.join(os.tmpdir(), 'f0-mcp-file-cache')
-const CLIENT_FILE_OPTION_KEYS = new Set(['allowLargeSize', 'allowLargeFile', 'authorizeLargeSize', 'line', 'lineStart', 'lineEnd'])
-
-type LineSelection =
-  | { kind: 'none' }
-  | { kind: 'single'; line: number }
-  | { kind: 'range'; start: number; end: number }
-  | { kind: 'invalid'; message: string }
-
-type ClientFileControls = {
-  allowLargeSize: boolean
-  lineSelection: LineSelection
-}
-
-type GitFileReadStats = {
-  lines: number
-  chars: number
-  bytes: number
-  declaredBytes: number | null
-}
-
-type CachedGitFile = {
-  content: string
-  stats: GitFileReadStats
-  cacheKey: string
-  cachePath: string
-}
-
-type ParsedCallPayload = {
-  payload: ExampleMcpCallArgs
-  controls: ClientFileControls
-}
-
-type GitFileIdentity = {
-  owner: string | null
-  repo: string | null
-  filePath: string | null
-  ref: string | null
-}
-
-type ExtractedGitFileContent = {
-  content: string
-  stats: GitFileReadStats
-}
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value)
-
-const parseBoolean = (value: unknown): boolean =>
-  value === true || value === 'true' || value === 1 || value === '1'
-
-const parsePositiveInteger = (value: unknown): number | null => {
-  const numeric = typeof value === 'string' && value.trim() !== ''
-    ? Number(value)
-    : (typeof value === 'number' ? value : NaN)
-
-  if (!Number.isInteger(numeric) || numeric <= 0) {
-    return null
-  }
-
-  return numeric
-}
-
-const splitLines = (value: string): string[] => {
-  const normalized = value.replace(/\r/g, '')
-  const lines = normalized.split('\n')
-  if (lines.length > 0 && lines[lines.length - 1] === '') {
-    lines.pop()
-  }
-  return lines
-}
-
-const computeLineSelection = (
-  lineRaw: unknown,
-  lineStartRaw: unknown,
-  lineEndRaw: unknown,
-): LineSelection => {
-  const lineProvided = lineRaw !== undefined
-  const lineStartProvided = lineStartRaw !== undefined
-  const lineEndProvided = lineEndRaw !== undefined
-
-  if (!lineProvided && !lineStartProvided && !lineEndProvided) {
-    return { kind: 'none' }
-  }
-
-  if (lineProvided && (lineStartProvided || lineEndProvided)) {
-    return { kind: 'invalid', message: 'Use either "line" or "lineStart/lineEnd", not both.' }
-  }
-
-  if (lineProvided) {
-    const line = parsePositiveInteger(lineRaw)
-    if (!line) {
-      return { kind: 'invalid', message: '"line" must be a positive integer.' }
-    }
-    return { kind: 'single', line }
-  }
-
-  const parsedStart = lineStartProvided ? parsePositiveInteger(lineStartRaw) : null
-  const parsedEnd = lineEndProvided ? parsePositiveInteger(lineEndRaw) : null
-
-  if (lineStartProvided && !parsedStart) {
-    return { kind: 'invalid', message: '"lineStart" must be a positive integer.' }
-  }
-  if (lineEndProvided && !parsedEnd) {
-    return { kind: 'invalid', message: '"lineEnd" must be a positive integer.' }
-  }
-
-  const start = parsedStart ?? parsedEnd
-  const end = parsedEnd ?? parsedStart
-  if (!start || !end) {
-    return { kind: 'invalid', message: 'Line range could not be parsed.' }
-  }
-  if (start > end) {
-    return { kind: 'invalid', message: '"lineStart" cannot be greater than "lineEnd".' }
-  }
-  return { kind: 'range', start, end }
-}
-
-const isGitFileViewTool = (toolName: string): boolean => /(^|\.)repo\.contents\.view$/.test(toolName)
-
-const buildCacheKey = (toolName: string, identity: GitFileIdentity): string => {
-  const keyBody = JSON.stringify({ toolName, ...identity })
-  return crypto.createHash('sha256').update(keyBody).digest('hex')
-}
-
-const decodeFileContent = (content: string, encoding: string): string => {
-  if (encoding === 'base64') {
-    return Buffer.from(content.replace(/\s+/g, ''), 'base64').toString('utf8')
-  }
-  return content
-}
-
-const extractGitFileContent = (data: unknown): ExtractedGitFileContent | null => {
-  const unwrapped = (() => {
-    if (!isRecord(data)) return data
-    if (typeof data.ok === 'boolean' && 'result' in data) {
-      return (data as any).result
-    }
-    return data
-  })()
-
-  if (!isRecord(unwrapped) || !isRecord(unwrapped.body)) {
-    return null
-  }
-
-  const body = unwrapped.body
-  if (typeof body.content !== 'string') {
-    return null
-  }
-
-  const encoding = typeof body.encoding === 'string' ? body.encoding.toLowerCase() : ''
-  let content = ''
-  try {
-    content = decodeFileContent(body.content, encoding)
-  } catch {
-    return null
-  }
-  const lines = splitLines(content).length
-  const chars = content.length
-  const bytes = Buffer.byteLength(content, 'utf8')
-  const declaredBytes = typeof body.size === 'number'
-    ? body.size
-    : (typeof body.size === 'string' && body.size.trim() !== '' ? Number(body.size) : null)
-
-  return {
-    content,
-    stats: {
-      lines,
-      chars,
-      bytes,
-      declaredBytes: Number.isFinite(declaredBytes) ? Number(declaredBytes) : null,
-    },
-  }
-}
-
-const toResponseText = (value: unknown): string => {
-  if (typeof value === 'string') {
-    return value
-  }
-  return JSON.stringify(value, null, 2)
-}
-
-const buildResponse = (isError: boolean, data: unknown): ExampleMcpCallResponse => ({
-  isError,
-  text: toResponseText(data),
-  data,
-})
-
-const toText = (result: ToolResult | null): string => {
-  if (!result || !result.content || result.content.length === 0) {
-    return ''
-  }
-
-  return result.content
-    .map((entry) => (entry.type === 'text' ? entry.text : ''))
-    .filter((entry) => entry.length > 0)
-    .join('\n')
-}
-
-const tryParseResult = (text: string): { parsed?: unknown; text: string } => {
-  if (!text) {
-    return { text }
-  }
-
-  try {
-    return {
-      text,
-      parsed: JSON.parse(text),
-    }
-  } catch {
-    return { text }
-  }
-}
-
-export interface ExampleMcpClientOptions {
-  name?: string
-  version?: string
-  requestTimeoutMs?: number
-  maxInlineFileLines?: number
-  fileCacheDir?: string
-}
-
-export interface ExampleMcpCallArgs {
-  args?: unknown[]
-  options?: Record<string, unknown>
-  [key: string]: unknown
-}
-
-export type ExampleMcpCallResponse = {
-  isError: boolean
-  text: string
-  data: unknown
-}
-
-export class ExampleMcpClient {
-  private readonly client: Client
-  private readonly requestTimeoutMs: number
-  private readonly maxInlineFileLines: number
-  private readonly fileCacheDir: string
-  private transport: StdioClientTransport | null = null
-
-  public constructor(options: ExampleMcpClientOptions = {}) {
-    this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
-    this.maxInlineFileLines = options.maxInlineFileLines ?? DEFAULT_MAX_INLINE_FILE_LINES
-    this.fileCacheDir = options.fileCacheDir ?? DEFAULT_FILE_CACHE_DIR
-    this.client = new Client(
-      {
-        name: options.name ?? 'f0-mcp-client',
-        version: options.version ?? '1.0.0',
-      },
-      {
-        capabilities: {},
-      },
-    )
-  }
-
-  public async connect(command: string, args: string[] = []): Promise<void> {
-    if (this.transport) {
-      throw new Error('Client transport is already connected')
-    }
-
-    this.transport = new StdioClientTransport({
-      command,
-      args,
-    })
-
-    await this.client.connect(this.transport)
-  }
-
-  public async close(): Promise<void> {
-    if (this.transport) {
-      await this.client.close()
-      this.transport = null
-    }
-  }
-
-  public async listTools(): Promise<string[]> {
-    const response = await this.client.request(
-      {
-        method: 'tools/list',
-      },
-      ListToolsResultSchema,
-      {
-        timeout: this.requestTimeoutMs,
-      },
-    )
-
-    return response.tools.map((tool) => tool.name)
-  }
-
-  private parseCallPayload(args: ExampleMcpCallArgs): ParsedCallPayload {
-    const input = isRecord(args) ? args : {}
-    const options = isRecord(input.options) ? { ...input.options } : {}
-    const allowLargeSize = parseBoolean(input.allowLargeSize)
-      || parseBoolean(input.allowLargeFile)
-      || parseBoolean(input.authorizeLargeSize)
-      || parseBoolean(options.allowLargeSize)
-      || parseBoolean(options.allowLargeFile)
-      || parseBoolean(options.authorizeLargeSize)
-
-    const lineSelection = computeLineSelection(
-      input.line ?? options.line,
-      input.lineStart ?? options.lineStart,
-      input.lineEnd ?? options.lineEnd,
-    )
-
-    for (const key of CLIENT_FILE_OPTION_KEYS) {
-      delete options[key]
-    }
-
-    const payload: ExampleMcpCallArgs = {}
-    if (Array.isArray(input.args)) {
-      payload.args = [...input.args]
-    }
-    if (Object.keys(options).length > 0) {
-      payload.options = options
-    }
-
-    for (const [key, value] of Object.entries(input)) {
-      if (key === 'args' || key === 'options' || CLIENT_FILE_OPTION_KEYS.has(key)) {
-        continue
-      }
-      if (value !== undefined) {
-        payload[key] = value
-      }
-    }
-
-    return {
-      payload,
-      controls: {
-        allowLargeSize,
-        lineSelection,
-      },
-    }
-  }
-
-  private async requestTool(toolName: string, args: ExampleMcpCallArgs): Promise<ExampleMcpCallResponse> {
-    const response = await this.client.request(
-      {
-        method: 'tools/call',
-        params: {
-          name: toolName,
-          arguments: args,
-        },
-      },
-      CallToolResultSchema,
-      {
-        timeout: this.requestTimeoutMs,
-      },
-    )
-
-    const text = toText(response as ToolResult)
-    const parsed = tryParseResult(text)
-    return {
-      isError: Boolean(response.isError),
-      text: parsed.text,
-      data: parsed.parsed ?? parsed.text,
-    }
-  }
-
-  private extractGitFileIdentity(payload: ExampleMcpCallArgs): GitFileIdentity {
-    const args = Array.isArray(payload.args) ? payload.args : []
-    const options = isRecord(payload.options) ? payload.options : {}
-    const query = isRecord(options.query) ? options.query : {}
-
-    const owner = args.length > 0 ? String(args[0]) : null
-    const repo = args.length > 1 ? String(args[1]) : null
-    const filePath = args.length > 2 ? String(args[2]) : null
-    const refSource = options.ref ?? options.branch ?? options.sha ?? query.ref ?? query.branch ?? query.sha
-    const ref = refSource === undefined ? null : String(refSource)
-
-    return { owner, repo, filePath, ref }
-  }
-
-  private getCachePaths(cacheKey: string): { contentPath: string; metaPath: string } {
-    return {
-      contentPath: path.join(this.fileCacheDir, `${cacheKey}.txt`),
-      metaPath: path.join(this.fileCacheDir, `${cacheKey}.json`),
-    }
-  }
-
-  private async readCachedGitFile(cacheKey: string): Promise<CachedGitFile | null> {
-    const { contentPath, metaPath } = this.getCachePaths(cacheKey)
-    try {
-      const [content, metaRaw] = await Promise.all([
-        fs.readFile(contentPath, 'utf8'),
-        fs.readFile(metaPath, 'utf8'),
-      ])
-
-      const metaParsed = JSON.parse(metaRaw)
-      if (!isRecord(metaParsed)) {
-        return null
-      }
-
-      const statsRaw = isRecord(metaParsed.stats) ? metaParsed.stats : {}
-      const lines = parsePositiveInteger(statsRaw.lines) ?? splitLines(content).length
-      const chars = parsePositiveInteger(statsRaw.chars) ?? content.length
-      const bytes = parsePositiveInteger(statsRaw.bytes) ?? Buffer.byteLength(content, 'utf8')
-      const declaredBytesRaw = statsRaw.declaredBytes
-      const declaredBytes = typeof declaredBytesRaw === 'number'
-        ? declaredBytesRaw
-        : (typeof declaredBytesRaw === 'string' && declaredBytesRaw.trim() !== '' ? Number(declaredBytesRaw) : null)
-
-      return {
-        content,
-        stats: {
-          lines,
-          chars,
-          bytes,
-          declaredBytes: Number.isFinite(declaredBytes) ? Number(declaredBytes) : null,
-        },
-        cacheKey,
-        cachePath: contentPath,
-      }
-    } catch {
-      return null
-    }
-  }
-
-  private async writeCachedGitFile(cacheKey: string, content: string, stats: GitFileReadStats): Promise<CachedGitFile> {
-    await fs.mkdir(this.fileCacheDir, { recursive: true })
-    const { contentPath, metaPath } = this.getCachePaths(cacheKey)
-    await Promise.all([
-      fs.writeFile(contentPath, content, 'utf8'),
-      fs.writeFile(metaPath, JSON.stringify({ stats }, null, 2), 'utf8'),
-    ])
-
-    return {
-      content,
-      stats,
-      cacheKey,
-      cachePath: contentPath,
-    }
-  }
-
-  private buildLineReadResponse(cache: CachedGitFile, selection: Exclude<LineSelection, { kind: 'none' | 'invalid' }>): ExampleMcpCallResponse {
-    const allLines = splitLines(cache.content)
-    const start = selection.kind === 'single' ? selection.line : selection.start
-    const end = selection.kind === 'single' ? selection.line : selection.end
-
-    if (start > allLines.length) {
-      return buildResponse(true, {
-        error: 'Requested line is out of range.',
-        requested: { start, end },
-        totalLines: allLines.length,
-        cachePath: cache.cachePath,
-      })
-    }
-
-    const clampedEnd = Math.min(end, allLines.length)
-    const lines = []
-    for (let lineNo = start; lineNo <= clampedEnd; lineNo += 1) {
-      lines.push({
-        line: lineNo,
-        text: allLines[lineNo - 1] ?? '',
-      })
-    }
-
-    return buildResponse(false, {
-      mode: 'line',
-      requested: { start, end: clampedEnd },
-      totalLines: allLines.length,
-      cachePath: cache.cachePath,
-      stats: cache.stats,
-      lines,
-    })
-  }
-
-  public async call(toolName: string, args: ExampleMcpCallArgs = {}): Promise<ExampleMcpCallResponse> {
-    const { payload, controls } = this.parseCallPayload(args)
-
-    if (!isGitFileViewTool(toolName)) {
-      return this.requestTool(toolName, payload)
-    }
-
-    if (controls.lineSelection.kind === 'invalid') {
-      return buildResponse(true, {
-        error: controls.lineSelection.message,
-        hint: 'Use options.line=<positive-int> or options.lineStart/options.lineEnd for ranged reads.',
-      })
-    }
-
-    const identity = this.extractGitFileIdentity(payload)
-    const cacheKey = buildCacheKey(toolName, identity)
-    const requiresLineRead = controls.lineSelection.kind === 'single' || controls.lineSelection.kind === 'range'
-
-    if (requiresLineRead) {
-      const cached = await this.readCachedGitFile(cacheKey)
-      if (cached) {
-        return this.buildLineReadResponse(cached, controls.lineSelection)
-      }
-    }
-
-    const response = await this.requestTool(toolName, payload)
-    if (response.isError) {
-      return response
-    }
-
-    const extracted = extractGitFileContent(response.data)
-    if (!extracted) {
-      if (requiresLineRead) {
-        return buildResponse(true, {
-          error: 'Line-by-line mode requires a file response with textual content.',
-          hint: 'Use repo.contents.view for files. Directory listings are not line-readable.',
-        })
-      }
-      return response
-    }
-
-    if (!requiresLineRead) {
-      if (extracted.stats.lines > this.maxInlineFileLines && !controls.allowLargeSize) {
-        return buildResponse(true, {
-          error: 'Large file response blocked by client-side safety guard.',
-          hint: `File has ${extracted.stats.lines} lines; default limit is ${this.maxInlineFileLines}. Set options.allowLargeSize=true to allow full-file responses.`,
-          lineByLineHint: 'For safer reads, request options.line=<n> or options.lineStart=<a>, options.lineEnd=<b>.',
-          stats: extracted.stats,
-          file: identity,
-          optionExample: {
-            options: {
-              allowLargeSize: true,
-            },
-          },
-        })
-      }
-
-      return response
-    }
-
-    const cached = await this.writeCachedGitFile(cacheKey, extracted.content, extracted.stats)
-    return this.buildLineReadResponse(cached, controls.lineSelection)
-  }
-
-  public async callByPath(
-    path: string,
-    methodArgs: unknown[] = [],
-    methodOptions: Record<string, unknown> = {},
-  ): Promise<ExampleMcpCallResponse> {
-    const args = { args: methodArgs, options: methodOptions }
-    return this.call(path, args)
-  }
-}
-
-export const createExampleMcpClient = (options: ExampleMcpClientOptions = {}): ExampleMcpClient => {
-  return new ExampleMcpClient(options)
-}
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { CallToolResultSchema, ListToolsResultSchema } from '@modelcontextprotocol/sdk/types.js'
+import crypto from 'node:crypto'
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+type ToolResultText = {
+  type: 'text'
+  text: string
+}
+
+type ToolResult = {
+  isError?: boolean
+  content?: ToolResultText[]
+}
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 5 * 60 * 1000
+const DEFAULT_MAX_INLINE_FILE_LINES = 300
+const DEFAULT_FILE_CACHE_DIR = path.join(os.tmpdir(), 'f0-mcp-file-cache')
+const CLIENT_FILE_OPTION_KEYS = new Set(['allowLargeSize', 'allowLargeFile', 'authorizeLargeSize', 'line', 'lineStart', 'lineEnd'])
+
+type LineSelection =
+  | { kind: 'none' }
+  | { kind: 'single'; line: number }
+  | { kind: 'range'; start: number; end: number }
+  | { kind: 'invalid'; message: string }
+
+type ClientFileControls = {
+  allowLargeSize: boolean
+  lineSelection: LineSelection
+}
+
+type GitFileReadStats = {
+  lines: number
+  chars: number
+  bytes: number
+  declaredBytes: number | null
+}
+
+type CachedGitFile = {
+  content: string
+  stats: GitFileReadStats
+  cacheKey: string
+  cachePath: string
+}
+
+type ParsedCallPayload = {
+  payload: ExampleMcpCallArgs
+  controls: ClientFileControls
+}
+
+type GitFileIdentity = {
+  owner: string | null
+  repo: string | null
+  filePath: string | null
+  ref: string | null
+}
+
+type ExtractedGitFileContent = {
+  content: string
+  stats: GitFileReadStats
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const parseBoolean = (value: unknown): boolean =>
+  value === true || value === 'true' || value === 1 || value === '1'
+
+const parsePositiveInteger = (value: unknown): number | null => {
+  const numeric = typeof value === 'string' && value.trim() !== ''
+    ? Number(value)
+    : (typeof value === 'number' ? value : NaN)
+
+  if (!Number.isInteger(numeric) || numeric <= 0) {
+    return null
+  }
+
+  return numeric
+}
+
+const splitLines = (value: string): string[] => {
+  const normalized = value.replace(/\r/g, '')
+  const lines = normalized.split('\n')
+  if (lines.length > 0 && lines[lines.length - 1] === '') {
+    lines.pop()
+  }
+  return lines
+}
+
+const computeLineSelection = (
+  lineRaw: unknown,
+  lineStartRaw: unknown,
+  lineEndRaw: unknown,
+): LineSelection => {
+  const lineProvided = lineRaw !== undefined
+  const lineStartProvided = lineStartRaw !== undefined
+  const lineEndProvided = lineEndRaw !== undefined
+
+  if (!lineProvided && !lineStartProvided && !lineEndProvided) {
+    return { kind: 'none' }
+  }
+
+  if (lineProvided && (lineStartProvided || lineEndProvided)) {
+    return { kind: 'invalid', message: 'Use either "line" or "lineStart/lineEnd", not both.' }
+  }
+
+  if (lineProvided) {
+    const line = parsePositiveInteger(lineRaw)
+    if (!line) {
+      return { kind: 'invalid', message: '"line" must be a positive integer.' }
+    }
+    return { kind: 'single', line }
+  }
+
+  const parsedStart = lineStartProvided ? parsePositiveInteger(lineStartRaw) : null
+  const parsedEnd = lineEndProvided ? parsePositiveInteger(lineEndRaw) : null
+
+  if (lineStartProvided && !parsedStart) {
+    return { kind: 'invalid', message: '"lineStart" must be a positive integer.' }
+  }
+  if (lineEndProvided && !parsedEnd) {
+    return { kind: 'invalid', message: '"lineEnd" must be a positive integer.' }
+  }
+
+  const start = parsedStart ?? parsedEnd
+  const end = parsedEnd ?? parsedStart
+  if (!start || !end) {
+    return { kind: 'invalid', message: 'Line range could not be parsed.' }
+  }
+  if (start > end) {
+    return { kind: 'invalid', message: '"lineStart" cannot be greater than "lineEnd".' }
+  }
+  return { kind: 'range', start, end }
+}
+
+const isGitFileViewTool = (toolName: string): boolean => /(^|\.)repo\.contents\.view$/.test(toolName)
+
+const buildCacheKey = (toolName: string, identity: GitFileIdentity): string => {
+  const keyBody = JSON.stringify({ toolName, ...identity })
+  return crypto.createHash('sha256').update(keyBody).digest('hex')
+}
+
+const decodeFileContent = (content: string, encoding: string): string => {
+  if (encoding === 'base64') {
+    return Buffer.from(content.replace(/\s+/g, ''), 'base64').toString('utf8')
+  }
+  return content
+}
+
+const extractGitFileContent = (data: unknown): ExtractedGitFileContent | null => {
+  const unwrapped = (() => {
+    if (!isRecord(data)) return data
+    if (typeof data.ok === 'boolean' && 'result' in data) {
+      return (data as any).result
+    }
+    return data
+  })()
+
+  if (!isRecord(unwrapped) || !isRecord(unwrapped.body)) {
+    return null
+  }
+
+  const body = unwrapped.body
+  if (typeof body.content !== 'string') {
+    return null
+  }
+
+  const encoding = typeof body.encoding === 'string' ? body.encoding.toLowerCase() : ''
+  let content = ''
+  try {
+    content = decodeFileContent(body.content, encoding)
+  } catch {
+    return null
+  }
+  const lines = splitLines(content).length
+  const chars = content.length
+  const bytes = Buffer.byteLength(content, 'utf8')
+  const declaredBytes = typeof body.size === 'number'
+    ? body.size
+    : (typeof body.size === 'string' && body.size.trim() !== '' ? Number(body.size) : null)
+
+  return {
+    content,
+    stats: {
+      lines,
+      chars,
+      bytes,
+      declaredBytes: Number.isFinite(declaredBytes) ? Number(declaredBytes) : null,
+    },
+  }
+}
+
+const toResponseText = (value: unknown): string => {
+  if (typeof value === 'string') {
+    return value
+  }
+  return JSON.stringify(value, null, 2)
+}
+
+const buildResponse = (isError: boolean, data: unknown): ExampleMcpCallResponse => ({
+  isError,
+  text: toResponseText(data),
+  data,
+})
+
+const toText = (result: ToolResult | null): string => {
+  if (!result || !result.content || result.content.length === 0) {
+    return ''
+  }
+
+  return result.content
+    .map((entry) => (entry.type === 'text' ? entry.text : ''))
+    .filter((entry) => entry.length > 0)
+    .join('\n')
+}
+
+const tryParseResult = (text: string): { parsed?: unknown; text: string } => {
+  if (!text) {
+    return { text }
+  }
+
+  try {
+    return {
+      text,
+      parsed: JSON.parse(text),
+    }
+  } catch {
+    return { text }
+  }
+}
+
+export interface ExampleMcpClientOptions {
+  name?: string
+  version?: string
+  requestTimeoutMs?: number
+  maxInlineFileLines?: number
+  fileCacheDir?: string
+}
+
+export interface ExampleMcpCallArgs {
+  args?: unknown[]
+  options?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+export type ExampleMcpCallResponse = {
+  isError: boolean
+  text: string
+  data: unknown
+}
+
+export class ExampleMcpClient {
+  private readonly client: Client
+  private readonly requestTimeoutMs: number
+  private readonly maxInlineFileLines: number
+  private readonly fileCacheDir: string
+  private transport: StdioClientTransport | null = null
+
+  public constructor(options: ExampleMcpClientOptions = {}) {
+    this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
+    this.maxInlineFileLines = options.maxInlineFileLines ?? DEFAULT_MAX_INLINE_FILE_LINES
+    this.fileCacheDir = options.fileCacheDir ?? DEFAULT_FILE_CACHE_DIR
+    this.client = new Client(
+      {
+        name: options.name ?? 'f0-mcp-client',
+        version: options.version ?? '1.0.0',
+      },
+      {
+        capabilities: {},
+      },
+    )
+  }
+
+  public async connect(command: string, args: string[] = []): Promise<void> {
+    if (this.transport) {
+      throw new Error('Client transport is already connected')
+    }
+
+    this.transport = new StdioClientTransport({
+      command,
+      args,
+    })
+
+    await this.client.connect(this.transport)
+  }
+
+  public async close(): Promise<void> {
+    if (this.transport) {
+      await this.client.close()
+      this.transport = null
+    }
+  }
+
+  public async listTools(): Promise<string[]> {
+    const response = await this.client.request(
+      {
+        method: 'tools/list',
+      },
+      ListToolsResultSchema,
+      {
+        timeout: this.requestTimeoutMs,
+      },
+    )
+
+    return response.tools.map((tool) => tool.name)
+  }
+
+  private parseCallPayload(args: ExampleMcpCallArgs): ParsedCallPayload {
+    const input = isRecord(args) ? args : {}
+    const options = isRecord(input.options) ? { ...input.options } : {}
+    const allowLargeSize = parseBoolean(input.allowLargeSize)
+      || parseBoolean(input.allowLargeFile)
+      || parseBoolean(input.authorizeLargeSize)
+      || parseBoolean(options.allowLargeSize)
+      || parseBoolean(options.allowLargeFile)
+      || parseBoolean(options.authorizeLargeSize)
+
+    const lineSelection = computeLineSelection(
+      input.line ?? options.line,
+      input.lineStart ?? options.lineStart,
+      input.lineEnd ?? options.lineEnd,
+    )
+
+    for (const key of CLIENT_FILE_OPTION_KEYS) {
+      delete options[key]
+    }
+
+    const payload: ExampleMcpCallArgs = {}
+    if (Array.isArray(input.args)) {
+      payload.args = [...input.args]
+    }
+    if (Object.keys(options).length > 0) {
+      payload.options = options
+    }
+
+    for (const [key, value] of Object.entries(input)) {
+      if (key === 'args' || key === 'options' || CLIENT_FILE_OPTION_KEYS.has(key)) {
+        continue
+      }
+      if (value !== undefined) {
+        payload[key] = value
+      }
+    }
+
+    return {
+      payload,
+      controls: {
+        allowLargeSize,
+        lineSelection,
+      },
+    }
+  }
+
+  private async requestTool(toolName: string, args: ExampleMcpCallArgs): Promise<ExampleMcpCallResponse> {
+    const response = await this.client.request(
+      {
+        method: 'tools/call',
+        params: {
+          name: toolName,
+          arguments: args,
+        },
+      },
+      CallToolResultSchema,
+      {
+        timeout: this.requestTimeoutMs,
+      },
+    )
+
+    const text = toText(response as ToolResult)
+    const parsed = tryParseResult(text)
+    return {
+      isError: Boolean(response.isError),
+      text: parsed.text,
+      data: parsed.parsed ?? parsed.text,
+    }
+  }
+
+  private extractGitFileIdentity(payload: ExampleMcpCallArgs): GitFileIdentity {
+    const args = Array.isArray(payload.args) ? payload.args : []
+    const options = isRecord(payload.options) ? payload.options : {}
+    const query = isRecord(options.query) ? options.query : {}
+
+    const owner = args.length > 0 ? String(args[0]) : null
+    const repo = args.length > 1 ? String(args[1]) : null
+    const filePath = args.length > 2 ? String(args[2]) : null
+    const refSource = options.ref ?? options.branch ?? options.sha ?? query.ref ?? query.branch ?? query.sha
+    const ref = refSource === undefined ? null : String(refSource)
+
+    return { owner, repo, filePath, ref }
+  }
+
+  private getCachePaths(cacheKey: string): { contentPath: string; metaPath: string } {
+    return {
+      contentPath: path.join(this.fileCacheDir, `${cacheKey}.txt`),
+      metaPath: path.join(this.fileCacheDir, `${cacheKey}.json`),
+    }
+  }
+
+  private async readCachedGitFile(cacheKey: string): Promise<CachedGitFile | null> {
+    const { contentPath, metaPath } = this.getCachePaths(cacheKey)
+    try {
+      const [content, metaRaw] = await Promise.all([
+        fs.readFile(contentPath, 'utf8'),
+        fs.readFile(metaPath, 'utf8'),
+      ])
+
+      const metaParsed = JSON.parse(metaRaw)
+      if (!isRecord(metaParsed)) {
+        return null
+      }
+
+      const statsRaw = isRecord(metaParsed.stats) ? metaParsed.stats : {}
+      const lines = parsePositiveInteger(statsRaw.lines) ?? splitLines(content).length
+      const chars = parsePositiveInteger(statsRaw.chars) ?? content.length
+      const bytes = parsePositiveInteger(statsRaw.bytes) ?? Buffer.byteLength(content, 'utf8')
+      const declaredBytesRaw = statsRaw.declaredBytes
+      const declaredBytes = typeof declaredBytesRaw === 'number'
+        ? declaredBytesRaw
+        : (typeof declaredBytesRaw === 'string' && declaredBytesRaw.trim() !== '' ? Number(declaredBytesRaw) : null)
+
+      return {
+        content,
+        stats: {
+          lines,
+          chars,
+          bytes,
+          declaredBytes: Number.isFinite(declaredBytes) ? Number(declaredBytes) : null,
+        },
+        cacheKey,
+        cachePath: contentPath,
+      }
+    } catch {
+      return null
+    }
+  }
+
+  private async writeCachedGitFile(cacheKey: string, content: string, stats: GitFileReadStats): Promise<CachedGitFile> {
+    await fs.mkdir(this.fileCacheDir, { recursive: true })
+    const { contentPath, metaPath } = this.getCachePaths(cacheKey)
+    await Promise.all([
+      fs.writeFile(contentPath, content, 'utf8'),
+      fs.writeFile(metaPath, JSON.stringify({ stats }, null, 2), 'utf8'),
+    ])
+
+    return {
+      content,
+      stats,
+      cacheKey,
+      cachePath: contentPath,
+    }
+  }
+
+  private buildLineReadResponse(cache: CachedGitFile, selection: Exclude<LineSelection, { kind: 'none' | 'invalid' }>): ExampleMcpCallResponse {
+    const allLines = splitLines(cache.content)
+    const start = selection.kind === 'single' ? selection.line : selection.start
+    const end = selection.kind === 'single' ? selection.line : selection.end
+
+    if (start > allLines.length) {
+      return buildResponse(true, {
+        error: 'Requested line is out of range.',
+        requested: { start, end },
+        totalLines: allLines.length,
+        cachePath: cache.cachePath,
+      })
+    }
+
+    const clampedEnd = Math.min(end, allLines.length)
+    const lines = []
+    for (let lineNo = start; lineNo <= clampedEnd; lineNo += 1) {
+      lines.push({
+        line: lineNo,
+        text: allLines[lineNo - 1] ?? '',
+      })
+    }
+
+    return buildResponse(false, {
+      mode: 'line',
+      requested: { start, end: clampedEnd },
+      totalLines: allLines.length,
+      cachePath: cache.cachePath,
+      stats: cache.stats,
+      lines,
+    })
+  }
+
+  public async call(toolName: string, args: ExampleMcpCallArgs = {}): Promise<ExampleMcpCallResponse> {
+    const { payload, controls } = this.parseCallPayload(args)
+
+    if (!isGitFileViewTool(toolName)) {
+      return this.requestTool(toolName, payload)
+    }
+
+    if (controls.lineSelection.kind === 'invalid') {
+      return buildResponse(true, {
+        error: controls.lineSelection.message,
+        hint: 'Use options.line=<positive-int> or options.lineStart/options.lineEnd for ranged reads.',
+      })
+    }
+
+    const identity = this.extractGitFileIdentity(payload)
+    const cacheKey = buildCacheKey(toolName, identity)
+    const requiresLineRead = controls.lineSelection.kind === 'single' || controls.lineSelection.kind === 'range'
+
+    if (requiresLineRead) {
+      const cached = await this.readCachedGitFile(cacheKey)
+      if (cached) {
+        return this.buildLineReadResponse(cached, controls.lineSelection)
+      }
+    }
+
+    const response = await this.requestTool(toolName, payload)
+    if (response.isError) {
+      return response
+    }
+
+    const extracted = extractGitFileContent(response.data)
+    if (!extracted) {
+      if (requiresLineRead) {
+        return buildResponse(true, {
+          error: 'Line-by-line mode requires a file response with textual content.',
+          hint: 'Use repo.contents.view for files. Directory listings are not line-readable.',
+        })
+      }
+      return response
+    }
+
+    if (!requiresLineRead) {
+      if (extracted.stats.lines > this.maxInlineFileLines && !controls.allowLargeSize) {
+        return buildResponse(true, {
+          error: 'Large file response blocked by client-side safety guard.',
+          hint: `File has ${extracted.stats.lines} lines; default limit is ${this.maxInlineFileLines}. Set options.allowLargeSize=true to allow full-file responses.`,
+          lineByLineHint: 'For safer reads, request options.line=<n> or options.lineStart=<a>, options.lineEnd=<b>.',
+          stats: extracted.stats,
+          file: identity,
+          optionExample: {
+            options: {
+              allowLargeSize: true,
+            },
+          },
+        })
+      }
+
+      return response
+    }
+
+    const cached = await this.writeCachedGitFile(cacheKey, extracted.content, extracted.stats)
+    return this.buildLineReadResponse(cached, controls.lineSelection)
+  }
+
+  public async callByPath(
+    path: string,
+    methodArgs: unknown[] = [],
+    methodOptions: Record<string, unknown> = {},
+  ): Promise<ExampleMcpCallResponse> {
+    const args = { args: methodArgs, options: methodOptions }
+    return this.call(path, args)
+  }
+}
+
+export const createExampleMcpClient = (options: ExampleMcpClientOptions = {}): ExampleMcpClient => {
+  return new ExampleMcpClient(options)
+}