@foundation0/api 1.1.0 → 1.1.1

package/README.md

@@ -26,6 +26,10 @@ The server supports:
 - `FALLBACK_GITEA_HOST` (fallback host variable)
 - `GITEA_TOKEN` (for authenticated actions)
 - `MCP_TOOLS_PREFIX` (or `--tools-prefix`) to namespace tools in clients
+- `MCP_ALLOWED_ROOT_ENDPOINTS` (or `--allowed-root-endpoints`) to whitelist API root endpoints
+- `MCP_DISABLE_WRITE` (or `--disable-write`) to expose read-only tools only
+- `MCP_ENABLE_ISSUES` (or `--enable-issues`) to allow issue endpoints when write mode is disabled
+- `MCP_ADMIN` (or `--admin`) to expose admin-only destructive endpoints
 
 Useful defaults:
 
@@ -107,7 +111,18 @@ f0-mcp --help
 # examples
 f0-mcp --tools-prefix=example --server-name=my-example
 f0-mcp --tools-prefix api --server-version 1.2.3
+f0-mcp --allowed-root-endpoints projects
+f0-mcp --allowed-root-endpoints agents,projects
+f0-mcp --disable-write
+f0-mcp --allowed-root-endpoints projects --disable-write
+f0-mcp --disable-write --enable-issues
+f0-mcp --admin
+f0-mcp --admin --disable-write --enable-issues
 ```
 
 - `--tools-prefix` is useful when running multiple MCP servers side-by-side.
 - `--server-name` and `--server-version` are mostly metadata but can help identify logs and client tool sets.
+- `--allowed-root-endpoints` restricts exposed tools to selected root namespaces (`agents`, `projects`).
+- `--disable-write` removes write-capable tools (for example create/update/delete/sync/set/main/run operations).
+- `--enable-issues` is a special-case override for `--disable-write`: issue endpoints remain enabled (`fetchGitTasks`, `readGitTask`, `writeGitTask`).
+- `projects.syncTasks` and `projects.clearIssues` are admin-only and hidden by default; they are exposed only with `--admin` (or `MCP_ADMIN=true`).

package/agents.ts

@@ -864,7 +864,7 @@ export async function main(argv: string[], processRoot: string = process.cwd()):
 
   const agentName = maybeAgentOrFlag
   const target = maybeTarget
-  const setActive = rest.includes('--set-active')
+  const setActiveRequested = rest.includes('--set-active')
   const useLatest = rest.includes('--latest')
 
   if (target === 'load') {
@@ -887,7 +887,7 @@ export async function main(argv: string[], processRoot: string = process.cwd()):
     throw new Error('Missing required arguments: <agent-name> and <file-path>.')
   }
 
-  if (!setActive) {
+  if (!setActiveRequested) {
     throw new Error('`--set-active` is required for this operation.')
   }
 

package/git.ts

@@ -1,14 +1,20 @@
 export type {
+  GitLabelManagementApi,
+  GitLabelManagementDefaults,
+  GitRepositoryLabel,
   GitServiceApi,
   GitServiceApiExecutionResult,
   GitServiceApiMethod,
-} from '@foundation0/git'
+} from '../git/packages/git/src/index.ts'
 
 export {
+  attachGitLabelManagementApi,
   buildGitApiMockResponse,
   callIssueDependenciesApi,
+  createGitLabelManagementApi,
   createGitServiceApi,
+  extractRepositoryLabels,
   extractDependencyIssueNumbers,
   resolveProjectRepoIdentity,
   syncIssueDependencies,
-} from '@foundation0/git'
+} from '../git/packages/git/src/index.ts'

package/mcp/cli.ts

@@ -18,26 +18,89 @@ const getArgValue = (name: string, fallback?: string): string | undefined => {
   return fallback
 }
 
-const hasFlag = (name: string): boolean => process.argv.includes(name)
-
+const hasFlag = (name: string): boolean => process.argv.includes(name)
+const parseBooleanLiteral = (value: string | undefined): boolean | undefined => {
+  if (value === undefined) return undefined
+  const normalized = value.trim().toLowerCase()
+  if (normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on') {
+    return true
+  }
+  if (normalized === '0' || normalized === 'false' || normalized === 'no' || normalized === 'off') {
+    return false
+  }
+  return undefined
+}
+const resolveBooleanFlag = (name: string, envValue: string | undefined): boolean => {
+  const index = process.argv.indexOf(name)
+  if (index >= 0) {
+    const next = process.argv[index + 1]
+    if (!next || next.startsWith('--')) {
+      return true
+    }
+    const parsedNext = parseBooleanLiteral(next)
+    if (parsedNext === undefined) {
+      throw new Error(`Invalid boolean value for ${name}: ${next}`)
+    }
+    return parsedNext
+  }
+
+  const exactArg = process.argv.find((arg) => arg.startsWith(`${name}=`))
+  if (exactArg) {
+    const [, raw] = exactArg.split('=', 2)
+    const parsed = parseBooleanLiteral(raw)
+    if (parsed === undefined) {
+      throw new Error(`Invalid boolean value for ${name}: ${raw}`)
+    }
+    return parsed
+  }
+
+  return parseBooleanLiteral(envValue) ?? false
+}
+const parseListArg = (value: string | undefined): string[] => {
+  if (!value) return []
+  return value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0)
+}
+
 const serverName = getArgValue('--server-name', 'f0-mcp')
-const serverVersion = getArgValue('--server-version', '1.0.0')
-const toolsPrefix = getArgValue('--tools-prefix') ?? process.env.MCP_TOOLS_PREFIX
-
+const serverVersion = getArgValue('--server-version', '1.0.0')
+const toolsPrefix = getArgValue('--tools-prefix') ?? process.env.MCP_TOOLS_PREFIX
+const allowedRootEndpoints = parseListArg(
+  getArgValue('--allowed-root-endpoints') ?? process.env.MCP_ALLOWED_ROOT_ENDPOINTS,
+)
+const disableWrite = resolveBooleanFlag('--disable-write', process.env.MCP_DISABLE_WRITE)
+const enableIssues = resolveBooleanFlag('--enable-issues', process.env.MCP_ENABLE_ISSUES)
+const admin = resolveBooleanFlag('--admin', process.env.MCP_ADMIN)
+
 if (hasFlag('--help') || hasFlag('-h')) {
   console.log('Usage: f0-mcp [--tools-prefix=api]')
-  console.log('Optional flags:')
-  console.log('  --server-name <name>')
-  console.log('  --server-version <version>')
-  console.log('  --tools-prefix <prefix>')
-  process.exit(0)
-}
-
+  console.log('Optional flags:')
+  console.log('  --server-name <name>')
+  console.log('  --server-version <version>')
+  console.log('  --tools-prefix <prefix>')
+  console.log('  --allowed-root-endpoints <csv>')
+  console.log('    Example: --allowed-root-endpoints projects')
+  console.log('    Example: --allowed-root-endpoints agents,projects')
+  console.log('  --disable-write')
+  console.log('    Expose read-only tools and disable write-capable endpoints.')
+  console.log('  --enable-issues')
+  console.log('    With --disable-write, re-enable issue read/write endpoints.')
+  console.log('  --admin')
+  console.log('    Expose admin-only destructive endpoints (syncTasks, clearIssues).')
+  process.exit(0)
+}
+
 void runExampleMcpServer({
-  serverName: serverName ?? undefined,
-  serverVersion: serverVersion ?? undefined,
-  toolsPrefix,
-}).catch((error) => {
+  serverName: serverName ?? undefined,
+  serverVersion: serverVersion ?? undefined,
+  toolsPrefix,
+  allowedRootEndpoints,
+  disableWrite,
+  enableIssues,
+  admin,
+}).catch((error) => {
   console.error('Failed to start example-org MCP server', error)
   process.exit(1)
 })

package/mcp/client.test.ts

@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { ExampleMcpClient } from './client'
+
+type RawToolResponse = {
+  isError?: boolean
+  content: Array<{ type: 'text'; text: string }>
+}
+
+const toRawToolResponse = (data: unknown, isError = false): RawToolResponse => ({
+  isError,
+  content: [
+    {
+      type: 'text',
+      text: JSON.stringify(data),
+    },
+  ],
+})
+
+const toGitFileToolData = (content: string) => ({
+  ok: true,
+  status: 200,
+  body: {
+    path: 'README.md',
+    type: 'file',
+    encoding: 'base64',
+    size: Buffer.byteLength(content, 'utf8'),
+    content: Buffer.from(content, 'utf8').toString('base64'),
+  },
+})
+
+describe('ExampleMcpClient git file guard', () => {
+  let cacheDir: string
+  let client: ExampleMcpClient
+  let capturedRequests: unknown[]
+
+  beforeEach(async () => {
+    cacheDir = await fs.mkdtemp(path.join(os.tmpdir(), 'f0-mcp-client-test-'))
+    capturedRequests = []
+    client = new ExampleMcpClient({
+      maxInlineFileLines: 3,
+      fileCacheDir: cacheDir,
+      requestTimeoutMs: 1_000,
+    })
+  })
+
+  afterEach(async () => {
+    await fs.rm(cacheDir, { recursive: true, force: true })
+  })
+
+  const stubRequests = (handler: (request: any) => RawToolResponse): void => {
+    const internalClient = (client as any).client
+    internalClient.request = async (request: any) => {
+      capturedRequests.push(request)
+      return handler(request)
+    }
+  }
+
+  it('blocks large file responses unless allowLargeSize is set', async () => {
+    const content = ['line 1', 'line 2', 'line 3', 'line 4'].join('\n')
+    stubRequests(() => toRawToolResponse(toGitFileToolData(content)))
+
+    const response = await client.call('repo.contents.view', {
+      args: ['owner', 'repo', 'README.md'],
+    })
+
+    expect(response.isError).toBe(true)
+    expect((response.data as any).hint).toContain('allowLargeSize')
+    expect((response.data as any).stats.lines).toBe(4)
+  })
+
+  it('allows large file responses when allowLargeSize=true and strips client-only options', async () => {
+    const content = ['line 1', 'line 2', 'line 3', 'line 4'].join('\n')
+    stubRequests(() => toRawToolResponse(toGitFileToolData(content)))
+
+    const response = await client.call('repo.contents.view', {
+      args: ['owner', 'repo', 'README.md'],
+      options: {
+        allowLargeSize: true,
+      },
+    })
+
+    expect(response.isError).toBe(false)
+    expect((response.data as any).body.path).toBe('README.md')
+    expect((capturedRequests[0] as any).params.arguments.options).toBeUndefined()
+  })
+
+  it('downloads once and serves line-by-line reads from local cache', async () => {
+    const content = ['line 1', 'line 2', 'line 3', 'line 4'].join('\n')
+    stubRequests(() => toRawToolResponse(toGitFileToolData(content)))
+
+    const first = await client.call('repo.contents.view', {
+      args: ['owner', 'repo', 'README.md'],
+      options: {
+        line: 2,
+      },
+    })
+
+    expect(first.isError).toBe(false)
+    expect((first.data as any).lines).toEqual([{ line: 2, text: 'line 2' }])
+    expect(capturedRequests.length).toBe(1)
+
+    const second = await client.call('repo.contents.view', {
+      args: ['owner', 'repo', 'README.md'],
+      options: {
+        line: 3,
+      },
+    })
+
+    expect(second.isError).toBe(false)
+    expect((second.data as any).lines).toEqual([{ line: 3, text: 'line 3' }])
+    expect(capturedRequests.length).toBe(1)
+
+    const cacheEntries = await fs.readdir(cacheDir)
+    expect(cacheEntries.some((entry) => entry.endsWith('.txt'))).toBe(true)
+    expect(cacheEntries.some((entry) => entry.endsWith('.json'))).toBe(true)
+  })
+
+  it('keeps non-file tool calls unchanged', async () => {
+    stubRequests(() => toRawToolResponse({ ok: true, body: { result: 'pass-through' } }))
+
+    const response = await client.call('projects.listProjects')
+
+    expect(response.isError).toBe(false)
+    expect(response.data).toEqual({ ok: true, body: { result: 'pass-through' } })
+  })
+})

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) {
@@ -44,6 +228,8 @@ export interface ExampleMcpClientOptions {
   name?: string
   version?: string
   requestTimeoutMs?: number
+  maxInlineFileLines?: number
+  fileCacheDir?: string
 }
 
 export interface ExampleMcpCallArgs {
@@ -61,10 +247,14 @@ export type ExampleMcpCallResponse = {
 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',
@@ -110,7 +300,53 @@ export class ExampleMcpClient {
     return response.tools.map((tool) => tool.name)
   }
 
-  public async call(toolName: string, args: ExampleMcpCallArgs = {}): Promise<ExampleMcpCallResponse> {
+  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,6 +370,178 @@ export class ExampleMcpClient {
     }
   }
 
+  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[] = [],

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')
+  })
+})

package/mcp/server.ts

@@ -312,6 +312,10 @@ export interface ExampleMcpServerOptions {
   serverName?: string
   serverVersion?: string
   toolsPrefix?: string
+  allowedRootEndpoints?: string[]
+  disableWrite?: boolean
+  enableIssues?: boolean
+  admin?: boolean
 }
 
 export type ExampleMcpServerInstance = {
@@ -321,16 +325,73 @@ export type ExampleMcpServerInstance = {
   run: () => Promise<Server>
 }
 
+const READ_ONLY_TOOL_NAMES = new Set([
+  'agents.usage',
+  'agents.resolveAgentsRoot',
+  'agents.resolveAgentsRootFrom',
+  'agents.listAgents',
+  'agents.parseTargetSpec',
+  'agents.resolveTargetFile',
+  'agents.loadAgent',
+  'agents.loadAgentPrompt',
+  'projects.usage',
+  'projects.resolveProjectRoot',
+  'projects.listProjects',
+  'projects.listProjectDocs',
+  'projects.readProjectDoc',
+  'projects.resolveImplementationPlan',
+  'projects.fetchGitTasks',
+  'projects.readGitTask',
+  'projects.parseProjectTargetSpec',
+  'projects.resolveProjectTargetFile',
+])
+
+const isWriteCapableTool = (toolName: string): boolean => !READ_ONLY_TOOL_NAMES.has(toolName)
+const ISSUE_TOOL_NAMES = new Set([
+  'projects.fetchGitTasks',
+  'projects.readGitTask',
+  'projects.writeGitTask',
+  'projects.syncTasks',
+  'projects.clearIssues',
+])
+const isIssueTool = (toolName: string): boolean => ISSUE_TOOL_NAMES.has(toolName)
+const ADMIN_TOOL_NAMES = new Set([
+  'projects.syncTasks',
+  'projects.clearIssues',
+])
+const isAdminTool = (toolName: string): boolean => ADMIN_TOOL_NAMES.has(toolName)
+
 export const createExampleMcpServer = (options: ExampleMcpServerOptions = {}): ExampleMcpServerInstance => {
   const api: ApiEndpoint = {
     agents: agentsApi,
     projects: projectsApi,
   }
 
-  const tools = [
-    ...collectTools(api.agents, ['agents']),
-    ...collectTools(api.projects, ['projects']),
-  ]
+  const allRoots = Object.keys(api) as Array<keyof ApiEndpoint>
+  const selectedRoots = (() => {
+    if (!options.allowedRootEndpoints || options.allowedRootEndpoints.length === 0) {
+      return allRoots
+    }
+
+    const normalized = options.allowedRootEndpoints
+      .map((value) => value.trim())
+      .filter((value) => value.length > 0)
+
+    const unknown = normalized.filter((value) => !allRoots.includes(value as keyof ApiEndpoint))
+    if (unknown.length > 0) {
+      throw new Error(`Unknown root endpoints: ${unknown.join(', ')}. Allowed: ${allRoots.join(', ')}`)
+    }
+
+    return [...new Set(normalized)] as Array<keyof ApiEndpoint>
+  })()
+
+  const selectedTools = selectedRoots.flatMap((root) => collectTools(api[root], [root]))
+  const adminFilteredTools = Boolean(options.admin)
+    ? selectedTools
+    : selectedTools.filter((tool) => !isAdminTool(tool.name))
+  const tools = options.disableWrite
+    ? adminFilteredTools.filter((tool) => !isWriteCapableTool(tool.name) || (Boolean(options.enableIssues) && isIssueTool(tool.name)))
+    : adminFilteredTools
   const prefix = options.toolsPrefix
   const batchToolName = prefix ? `${prefix}.batch` : 'batch'
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foundation0/api",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Foundation 0 API",
   "type": "module",
   "bin": {
@@ -34,8 +34,8 @@
     "mcp": "bun run mcp/cli.ts",
     "test": "echo \"Error: no test specified\" && exit 1",
     "deploy": "pnpm publish --access public",
-    "version:patch": "pnpm version patch",
-    "version:minor": "pnpm version minor",
-    "version:major": "pnpm version major"
+    "version:patch": "pnpm version patch && git commit -am \"Bump version to %s\"",
+    "version:minor": "pnpm version minor && git commit -am \"Bump version to %s\"",
+    "version:major": "pnpm version major && git commit -am \"Bump version to %s\""
   }
 }