@foundation0/api 1.0.1 → 1.1.1

package/mcp/client.ts

@@ -1,6 +1,10 @@
 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'
@@ -13,6 +17,186 @@ type ToolResult = {
 }
 
 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 => {
+  if (!isRecord(data) || !isRecord(data.body)) {
+    return null
+  }
+
+  const body = data.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) {
@@ -40,31 +224,37 @@ const tryParseResult = (text: string): { parsed?: unknown; text: string } => {
   }
 }
 
-export interface F0McpClientOptions {
+export interface ExampleMcpClientOptions {
   name?: string
   version?: string
   requestTimeoutMs?: number
+  maxInlineFileLines?: number
+  fileCacheDir?: string
 }
 
-export interface F0McpCallArgs {
+export interface ExampleMcpCallArgs {
   args?: unknown[]
   options?: Record<string, unknown>
   [key: string]: unknown
 }
 
-export type F0McpCallResponse = {
+export type ExampleMcpCallResponse = {
   isError: boolean
   text: string
   data: unknown
 }
 
-export class F0McpClient {
+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: F0McpClientOptions = {}) {
+  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',
@@ -110,7 +300,53 @@ export class F0McpClient {
     return response.tools.map((tool) => tool.name)
   }
 
-  public async call(toolName: string, args: F0McpCallArgs = {}): Promise<F0McpCallResponse> {
+  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',
@@ -134,16 +370,188 @@ export class F0McpClient {
     }
   }
 
+  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<F0McpCallResponse> {
+  ): Promise<ExampleMcpCallResponse> {
     const args = { args: methodArgs.map((value) => String(value)), options: methodOptions }
     return this.call(path, args)
   }
 }
 
-export const createF0McpClient = (options: F0McpClientOptions = {}): F0McpClient => {
-  return new F0McpClient(options)
+export const createExampleMcpClient = (options: ExampleMcpClientOptions = {}): ExampleMcpClient => {
+  return new ExampleMcpClient(options)
 }

package/mcp/index.ts

@@ -1,15 +1,15 @@
 export {
-  createF0McpServer,
-  runF0McpServer,
+  createExampleMcpServer,
+  runExampleMcpServer,
   normalizeToolCallNameForServer,
-  type F0McpServerOptions,
-  type F0McpServerInstance,
+  type ExampleMcpServerOptions,
+  type ExampleMcpServerInstance,
 } from './server'
 
 export {
-  F0McpClient,
-  createF0McpClient,
-  type F0McpCallArgs,
-  type F0McpCallResponse,
-  type F0McpClientOptions,
+  ExampleMcpClient,
+  createExampleMcpClient,
+  type ExampleMcpCallArgs,
+  type ExampleMcpCallResponse,
+  type ExampleMcpClientOptions,
 } from './client'

package/mcp/server.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'bun:test'
+import { createExampleMcpServer } from './server'
+
+describe('createExampleMcpServer endpoint whitelist', () => {
+  it('exposes all root endpoints by default', () => {
+    const instance = createExampleMcpServer()
+    const names = instance.tools.map((tool) => tool.name)
+
+    expect(names.some((name) => name.startsWith('agents.'))).toBe(true)
+    expect(names.some((name) => name.startsWith('projects.'))).toBe(true)
+    expect(names).not.toContain('projects.syncTasks')
+    expect(names).not.toContain('projects.clearIssues')
+  })
+
+  it('filters tools to selected root endpoints', () => {
+    const instance = createExampleMcpServer({
+      allowedRootEndpoints: ['projects'],
+    })
+    const names = instance.tools.map((tool) => tool.name)
+
+    expect(names.length).toBeGreaterThan(0)
+    expect(names.every((name) => name.startsWith('projects.'))).toBe(true)
+    expect(names.some((name) => name.startsWith('agents.'))).toBe(false)
+  })
+
+  it('throws on unknown root endpoints', () => {
+    expect(() => createExampleMcpServer({
+      allowedRootEndpoints: ['unknown-root'],
+    })).toThrow('Unknown root endpoints')
+  })
+
+  it('disables write-capable tools when disableWrite=true', () => {
+    const instance = createExampleMcpServer({
+      disableWrite: true,
+    })
+    const names = instance.tools.map((tool) => tool.name)
+
+    expect(names).toContain('projects.readGitTask')
+    expect(names).toContain('projects.listProjects')
+    expect(names).toContain('agents.listAgents')
+    expect(names).not.toContain('projects.writeGitTask')
+    expect(names).not.toContain('projects.syncTasks')
+    expect(names).not.toContain('projects.clearIssues')
+    expect(names).not.toContain('projects.generateSpec')
+    expect(names).not.toContain('projects.setActive')
+    expect(names).not.toContain('projects.main')
+    expect(names).not.toContain('agents.createAgent')
+    expect(names).not.toContain('agents.setActive')
+    expect(names).not.toContain('agents.setActiveLink')
+    expect(names).not.toContain('agents.runAgent')
+    expect(names).not.toContain('agents.main')
+  })
+
+  it('applies disableWrite with root endpoint whitelist', () => {
+    const instance = createExampleMcpServer({
+      allowedRootEndpoints: ['projects'],
+      disableWrite: true,
+    })
+    const names = instance.tools.map((tool) => tool.name)
+
+    expect(names.length).toBeGreaterThan(0)
+    expect(names.every((name) => name.startsWith('projects.'))).toBe(true)
+    expect(names).toContain('projects.readGitTask')
+    expect(names).toContain('projects.fetchGitTasks')
+    expect(names).not.toContain('projects.writeGitTask')
+    expect(names).not.toContain('projects.syncTasks')
+  })
+
+  it('re-enables issue write endpoints when enableIssues=true with disableWrite', () => {
+    const instance = createExampleMcpServer({
+      disableWrite: true,
+      enableIssues: true,
+    })
+    const names = instance.tools.map((tool) => tool.name)
+
+    expect(names).toContain('projects.fetchGitTasks')
+    expect(names).toContain('projects.readGitTask')
+    expect(names).toContain('projects.writeGitTask')
+    expect(names).not.toContain('projects.syncTasks')
+    expect(names).not.toContain('projects.clearIssues')
+    expect(names).not.toContain('projects.generateSpec')
+    expect(names).not.toContain('projects.setActive')
+    expect(names).not.toContain('agents.createAgent')
+    expect(names).not.toContain('agents.runAgent')
+  })
+
+  it('exposes syncTasks and clearIssues only when admin=true', () => {
+    const defaultInstance = createExampleMcpServer()
+    const defaultNames = defaultInstance.tools.map((tool) => tool.name)
+    expect(defaultNames).not.toContain('projects.syncTasks')
+    expect(defaultNames).not.toContain('projects.clearIssues')
+
+    const adminInstance = createExampleMcpServer({ admin: true })
+    const adminNames = adminInstance.tools.map((tool) => tool.name)
+    expect(adminNames).toContain('projects.syncTasks')
+    expect(adminNames).toContain('projects.clearIssues')
+  })
+
+  it('requires admin along with enableIssues for destructive issue endpoints under disableWrite', () => {
+    const nonAdmin = createExampleMcpServer({
+      disableWrite: true,
+      enableIssues: true,
+    })
+    const nonAdminNames = nonAdmin.tools.map((tool) => tool.name)
+    expect(nonAdminNames).not.toContain('projects.syncTasks')
+    expect(nonAdminNames).not.toContain('projects.clearIssues')
+
+    const admin = createExampleMcpServer({
+      disableWrite: true,
+      enableIssues: true,
+      admin: true,
+    })
+    const adminNames = admin.tools.map((tool) => tool.name)
+    expect(adminNames).toContain('projects.syncTasks')
+    expect(adminNames).toContain('projects.clearIssues')
+  })
+})