@foundation0/api 1.1.0 → 1.1.2

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.mjs

@@ -32,6 +32,6 @@ try {
     process.exit(1)
   }
 
-  console.error('Failed to launch example-org MCP server', error)
+  console.error('Failed to launch f0-mcp server', error)
   process.exit(1)
 }

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) => {
-  console.error('Failed to start example-org MCP server', error)
-  process.exit(1)
-})
+  serverName: serverName ?? undefined,
+  serverVersion: serverVersion ?? undefined,
+  toolsPrefix,
+  allowedRootEndpoints,
+  disableWrite,
+  enableIssues,
+  admin,
+}).catch((error) => {
+  console.error('Failed to start f0-mcp server', error)
+  process.exit(1)
+})

package/mcp/client.test.ts

@@ -0,0 +1,142 @@
+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' } })
+  })
+
+  it('keeps plain-text tool responses as data when JSON parsing fails', async () => {
+    stubRequests(() => ({
+      isError: false,
+      content: [{ type: 'text', text: 'not-json' }],
+    }))
+
+    const response = await client.call('projects.listProjects')
+
+    expect(response.isError).toBe(false)
+    expect(response.text).toBe('not-json')
+    expect(response.data).toBe('not-json')
+  })
+})