@foundation0/api 1.0.1 → 1.1.1

package/README.md

@@ -1,6 +1,6 @@
-# F0 MCP Server
+# example-org MCP Server
 
-Install and register the F0 MCP server with the MCP-enabled agent/tooling you use.
+Install and register the example-org MCP server with the MCP-enabled agent/tooling you use.
 
 ## 1) Install
 
@@ -23,9 +23,13 @@ The runnable entrypoint is `f0-mcp` (available from `bin` when installed globall
 The server supports:
 
 - `GITEA_HOST` (recommended, required by git-backed tools)
-- `F0_GITEA_HOST` (fallback host variable)
+- `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:
 
@@ -37,7 +41,7 @@ Useful defaults:
 ### A) `.codex/config.toml`
 
 ```toml
-[mcp_servers.f0]
+[mcp_servers.example]
 command = "bun"
   args = ["x", "@foundation0/api", "f0-mcp"]
 enabled = true
@@ -45,7 +49,7 @@ startup_timeout_ms = 20_000
 env = {
   GITEA_HOST = "https://gitea.example.com",
   GITEA_TOKEN = "your-token",
-  MCP_TOOLS_PREFIX = "f0"
+  MCP_TOOLS_PREFIX = "example"
 }
 ```
 
@@ -61,9 +65,9 @@ args = []
 ```json
 {
   "mcpServers": {
-    "f0": {
+    "example": {
       "command": "bun",
-      "args": ["x", "@foundation0/api", "f0-mcp", "--tools-prefix", "f0"],
+      "args": ["x", "@foundation0/api", "f0-mcp", "--tools-prefix", "example"],
       "env": {
         "GITEA_HOST": "https://gitea.example.com",
         "GITEA_TOKEN": "your-token"
@@ -82,7 +86,7 @@ Use the same command/args/env block in your MCP server configuration area:
 ```json
 {
   "command": "bun",
-  "args": ["x", "@foundation0/api", "f0-mcp", "--tools-prefix", "f0"],
+  "args": ["x", "@foundation0/api", "f0-mcp", "--tools-prefix", "example"],
   "env": {
     "GITEA_HOST": "https://gitea.example.com",
     "GITEA_TOKEN": "your-token"
@@ -105,9 +109,20 @@ Add environment variables for host/token and optional `MCP_TOOLS_PREFIX`.
 f0-mcp --help
 
 # examples
-f0-mcp --tools-prefix=f0 --server-name=my-f0
+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

@@ -23,12 +23,25 @@ export interface AgentLoadResult {
   loaded: unknown
 }
 
+export interface AgentRunResult {
+  agentName: string
+  exitCode: number
+}
+
+export interface AgentCreateResult {
+  agentName: string
+  agentRoot: string
+  createdPaths: string[]
+}
+
 interface ActiveConfigInput {
   path: string
   required: boolean
 }
 
-const CLI_NAME = 'f0'
+const CLI_NAME = 'example'
+const AGENT_INITIAL_VERSION = 'v0.0.1'
+const DEFAULT_SKILL_NAME = 'coding-standards'
 const VERSION_RE = 'v?\\d+(?:\\.\\d+){2,}'
 const VERSION_RE_CORE = `(?:${VERSION_RE})`
 const VERSION_WITH_EXT_RE = new RegExp(`^(.+)\\.(${VERSION_RE})\\.([A-Za-z][A-Za-z0-9_-]*)$`)
@@ -36,13 +49,16 @@ const VERSION_ONLY_RE = new RegExp(`^(.+)\\.(${VERSION_RE})$`)
 const PRIORITIZED_EXTS = ['.md', '.json', '.yaml', '.yml', '.ts', '.js', '.txt']
 
 export function usage(): string {
-  return `Usage:\n  ${CLI_NAME} agents <agent-name> <file-path> --set-active\n  ${CLI_NAME} agents --list\n  ${CLI_NAME} agents <agent-name> load\n\n` +
-    `Examples:\n  ${CLI_NAME} agents coder /system/boot.v0.0.1 --set-active\n  ${CLI_NAME} agents coder /system/boot --set-active --latest\n  ${CLI_NAME} agents coder /skills/coding-standards.v0.0.1 --set-active\n  ${CLI_NAME} agents --list\n` +
+  return `Usage:\n  ${CLI_NAME} agents create <agent-name>\n  ${CLI_NAME} agents <agent-name> <file-path> --set-active\n  ${CLI_NAME} agents --list\n  ${CLI_NAME} agents <agent-name> load\n  ${CLI_NAME} agents <agent-name> run [codex-args...]\n\n` +
+    `Examples:\n  ${CLI_NAME} agents create reviewer\n  ${CLI_NAME} agents coder /system/boot.v0.0.1 --set-active\n  ${CLI_NAME} agents coder /system/boot --set-active --latest\n  ${CLI_NAME} agents coder /skills/coding-standards.v0.0.1 --set-active\n  ${CLI_NAME} agents --list\n` +
     `  ${CLI_NAME} agents coder load\n` +
+    `  ${CLI_NAME} agents coder run --model gpt-5\n` +
     `\n` +
     `file-path is relative to the agent root (leading slash required).\n` +
     `Use --latest to resolve /file-name to the latest version.\n` +
-    `The active file created is [file].active.<ext>.\n`
+    `The active file created is [file].active.<ext>.\n` +
+    `Use "run" to start codex with developer_instructions from system/prompt.ts.\n` +
+    `Set EXAMPLE_CODEX_BIN to pin a specific codex binary.\n`
 }
 
 export function resolveAgentsRoot(processRoot: string = process.cwd()): string {
@@ -76,6 +92,200 @@ export function listAgents(processRoot: string = process.cwd()): string[] {
     .sort((a, b) => a.localeCompare(b))
 }
 
+function normalizeAgentName(agentName: string): string {
+  if (!agentName || typeof agentName !== 'string') {
+    throw new Error('agent-name is required.')
+  }
+
+  const normalized = agentName.trim()
+  if (!normalized) {
+    throw new Error('agent-name is required.')
+  }
+
+  if (normalized.startsWith('-')) {
+    throw new Error(`Invalid agent-name: ${agentName}`)
+  }
+
+  if (normalized === '.' || normalized === '..' || normalized.includes('/') || normalized.includes('\\')) {
+    throw new Error(`Invalid agent-name: ${agentName}`)
+  }
+
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(normalized)) {
+    throw new Error(`Invalid agent-name: ${agentName}`)
+  }
+
+  return normalized
+}
+
+function titleCaseAgentName(agentName: string): string {
+  return agentName
+    .split(/[-_]+/)
+    .filter(Boolean)
+    .map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
+    .join(' ')
+}
+
+function buildBootDocument(agentName: string): string {
+  const title = titleCaseAgentName(agentName) || agentName
+  return `# ${title} Agent Boot (${AGENT_INITIAL_VERSION})
+
+You are the \`${agentName}\` agent.
+
+## Role
+- Follow the active workflow and execute scoped tasks.
+- Keep outputs concise, concrete, and implementation-focused.
+- Avoid changing unrelated files or behavior.
+
+## Startup Sequence
+1. Read active boot/workflow docs and enabled skills.
+2. Confirm scope and constraints before changes.
+3. Apply the smallest safe change set.
+4. Report changed files and outcomes.
+`
+}
+
+function buildWorkflowDocument(agentName: string): string {
+  return `# ${titleCaseAgentName(agentName) || agentName} Workflow (${AGENT_INITIAL_VERSION})
+
+1. Parse request and constraints.
+2. Identify exact files and minimal edits.
+3. Implement and verify changes.
+4. If blocked, stop and report the blocker.
+5. Return result summary with next actions if needed.
+`
+}
+
+function buildToolsConfig(): string {
+  return `${JSON.stringify({
+    tools: [
+      {
+        name: 'shell_command',
+        enabled: true,
+        description: 'Execute shell commands for file and workspace operations.',
+      },
+      {
+        name: 'apply_patch',
+        enabled: true,
+        description: 'Apply focused file edits safely.',
+      },
+      {
+        name: 'read_file',
+        enabled: true,
+        description: 'Read files when needed for context.',
+      },
+    ],
+    permissions: {
+      network: false,
+      write: true,
+      delete: true,
+    },
+  }, null, 2)}
+`
+}
+
+function buildModelConfig(): string {
+  return `${JSON.stringify({
+    provider: 'openai',
+    model: 'gpt-5',
+    temperature: 0.2,
+    max_tokens: 4096,
+    top_p: 0.95,
+  }, null, 2)}
+`
+}
+
+function buildDefaultSkillDocument(): string {
+  return `# Coding Standards (${AGENT_INITIAL_VERSION})
+
+- Keep changes minimal and focused on the request.
+- Preserve existing behavior unless explicitly changing it.
+- Prefer readable, deterministic implementations.
+`
+}
+
+const SYSTEM_PROMPT_TS_TEMPLATE = `import * as fs from 'fs'
+import * as path from 'path'
+
+const base = path.join(__dirname)
+const readActive = (p: string) => fs.readFileSync(path.join(base, p), 'utf8')
+
+export const boot = readActive('boot.active.md')
+export const workflow = readActive('workflow.active.md')
+export const tools = JSON.parse(readActive('tools.active.json'))
+export const model = JSON.parse(readActive('model.active.json'))
+
+export const prompt = [boot, workflow].join('\\n\\n')
+
+export const agentConfig = {
+  boot,
+  workflow,
+  tools,
+  model,
+  prompt,
+}
+`
+
+const SKILLS_TS_TEMPLATE = `import * as fs from 'fs'
+import * as path from 'path'
+
+export interface SkillFile {
+  id: string
+  version: string
+  activeFile: string
+  resolvedFile: string
+  content: string
+}
+
+const skillsDir = path.join(__dirname)
+const enabledListPath = path.join(skillsDir, 'enabled-skills.md')
+
+const resolveVersionAndId = (activeFile: string) => {
+  const baseName = path.basename(activeFile, '.active.md')
+  const resolved = \`\${baseName}.${AGENT_INITIAL_VERSION}.md\`
+  return {
+    id: baseName,
+    version: '${AGENT_INITIAL_VERSION}',
+    resolvedFile: resolved,
+  }
+}
+
+const enabledLines = fs
+  .readFileSync(enabledListPath, 'utf8')
+  .split(/\\r?\\n/)
+  .map((line) => line.trim())
+  .filter(Boolean)
+
+export const skills: SkillFile[] = enabledLines.map((activeFile) => {
+  const resolved = resolveVersionAndId(activeFile)
+  return {
+    ...resolved,
+    activeFile,
+    content: fs.readFileSync(path.join(skillsDir, resolved.resolvedFile), 'utf8'),
+  }
+})
+`
+
+const LOAD_TS_TEMPLATE = `import { readFileSync } from 'fs'
+import * as path from 'path'
+
+import { agentConfig } from './system/prompt'
+import { skills } from './skills/skills'
+
+const activeDoc = path.join(__dirname, 'system')
+
+const loadActive = (name: string) =>
+  readFileSync(path.join(activeDoc, name), 'utf8').trim()
+
+export const load = () => ({
+  ...agentConfig,
+  bootDoc: loadActive('boot.active.md'),
+  workflowDoc: loadActive('workflow.active.md'),
+  skills,
+})
+
+export type AgentBundle = ReturnType<typeof load>
+`
+
 export function parseTargetSpec(spec: string): VersionedFileSpec {
   if (!spec || typeof spec !== 'string') {
     throw new Error('file-path is required.')
@@ -285,6 +495,68 @@ function createWindowsSymlink(activeFile: string, sourceFile: string): boolean {
   return result.status === 0
 }
 
+export function createAgent(agentName: string, processRoot: string = process.cwd()): AgentCreateResult {
+  const normalizedAgentName = normalizeAgentName(agentName)
+  const agentsRoot = resolveAgentsRootFrom(processRoot)
+  const agentRoot = path.join(agentsRoot, normalizedAgentName)
+
+  if (fs.existsSync(agentRoot)) {
+    throw new Error(`Agent folder already exists: ${agentRoot}`)
+  }
+
+  const systemDir = path.join(agentRoot, 'system')
+  const skillsDir = path.join(agentRoot, 'skills')
+
+  fs.mkdirSync(systemDir, { recursive: true })
+  fs.mkdirSync(skillsDir, { recursive: true })
+
+  const createdPaths: string[] = []
+  const writeFile = (relativePath: string, content: string) => {
+    const absolutePath = path.join(agentRoot, relativePath)
+    fs.mkdirSync(path.dirname(absolutePath), { recursive: true })
+    fs.writeFileSync(absolutePath, content, 'utf8')
+    createdPaths.push(absolutePath)
+  }
+
+  const bootFileName = `boot.${AGENT_INITIAL_VERSION}.md`
+  const workflowFileName = `workflow.${AGENT_INITIAL_VERSION}.md`
+  const toolsFileName = `tools.${AGENT_INITIAL_VERSION}.json`
+  const modelFileName = `model.${AGENT_INITIAL_VERSION}.json`
+  const skillFileName = `${DEFAULT_SKILL_NAME}.${AGENT_INITIAL_VERSION}.md`
+  const activeSkillFileName = `${DEFAULT_SKILL_NAME}.active.md`
+
+  writeFile(path.join('system', bootFileName), buildBootDocument(normalizedAgentName))
+  writeFile(path.join('system', workflowFileName), buildWorkflowDocument(normalizedAgentName))
+  writeFile(path.join('system', toolsFileName), buildToolsConfig())
+  writeFile(path.join('system', modelFileName), buildModelConfig())
+  writeFile(path.join('system', 'prompt.ts'), SYSTEM_PROMPT_TS_TEMPLATE)
+
+  writeFile(path.join('skills', skillFileName), buildDefaultSkillDocument())
+  writeFile(path.join('skills', 'enabled-skills.md'), `${activeSkillFileName}\n`)
+  writeFile(path.join('skills', 'skills.ts'), SKILLS_TS_TEMPLATE)
+
+  writeFile('load.ts', LOAD_TS_TEMPLATE)
+
+  const createActiveLink = (versionedFile: string, activeFile: string) => {
+    const source = path.join(agentRoot, versionedFile)
+    const target = path.join(agentRoot, activeFile)
+    setActiveLink(source, target)
+    createdPaths.push(target)
+  }
+
+  createActiveLink(path.join('system', bootFileName), path.join('system', 'boot.active.md'))
+  createActiveLink(path.join('system', workflowFileName), path.join('system', 'workflow.active.md'))
+  createActiveLink(path.join('system', toolsFileName), path.join('system', 'tools.active.json'))
+  createActiveLink(path.join('system', modelFileName), path.join('system', 'model.active.json'))
+  createActiveLink(path.join('skills', skillFileName), path.join('skills', activeSkillFileName))
+
+  return {
+    agentName: normalizedAgentName,
+    agentRoot,
+    createdPaths: createdPaths.sort((a, b) => a.localeCompare(b)),
+  }
+}
+
 export function setActive(
   agentName: string,
   target: string,
@@ -362,6 +634,135 @@ export async function loadAgent(agentName: string, processRoot: string = process
   }
 }
 
+type SpawnCodexResult = {
+  status: number | null
+  signal: NodeJS.Signals | null
+  error?: Error
+}
+
+type SpawnCodexFn = (args: string[]) => SpawnCodexResult
+
+function getCodexCommand(): string {
+  const override = process.env.EXAMPLE_CODEX_BIN?.trim()
+  if (override) {
+    return override
+  }
+  if (process.platform === 'win32') {
+    // Prefer npm/pnpm cmd shim over stale codex.exe binaries.
+    return 'codex.cmd'
+  }
+  return 'codex'
+}
+
+const defaultSpawnCodex: SpawnCodexFn = (args) => {
+  const spawnOptions = {
+    stdio: 'inherit' as const,
+    env: process.env,
+  }
+
+  const primaryCommand = getCodexCommand()
+  const primary = spawnSync(primaryCommand, args, spawnOptions)
+  if (primary.error) {
+    const err = primary.error as NodeJS.ErrnoException
+    if (
+      process.platform === 'win32'
+      && !process.env.EXAMPLE_CODEX_BIN
+      && primaryCommand === 'codex.cmd'
+      && err.code === 'ENOENT'
+    ) {
+      return spawnSync('codex', args, spawnOptions)
+    }
+  }
+
+  return primary
+}
+
+function toExitCode(signal: NodeJS.Signals | null): number {
+  if (!signal) {
+    return 1
+  }
+  if (signal === 'SIGINT') {
+    return 130
+  }
+  if (signal === 'SIGTERM') {
+    return 143
+  }
+  return 1
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+async function resolvePromptValue(value: unknown): Promise<unknown> {
+  if (typeof value === 'function') {
+    return await value()
+  }
+  return value
+}
+
+function extractPromptString(value: unknown): string | null {
+  if (typeof value === 'string') {
+    return value
+  }
+  if (isRecord(value) && typeof value.prompt === 'string') {
+    return value.prompt
+  }
+  return null
+}
+
+export async function loadAgentPrompt(agentName: string, processRoot: string = process.cwd()): Promise<string> {
+  const agentsRoot = resolveAgentsRoot(processRoot)
+  const agentDir = path.join(agentsRoot, agentName)
+
+  if (!existsDir(agentDir)) {
+    throw new Error(`Agent folder not found: ${agentDir}`)
+  }
+
+  const promptFile = path.join(agentDir, 'system', 'prompt.ts')
+  if (!existsFile(promptFile)) {
+    throw new Error(`Prompt file not found for agent '${agentName}': ${promptFile}`)
+  }
+
+  const promptModuleUrl = pathToFileURL(promptFile).href
+  const promptModule = await import(promptModuleUrl)
+  const candidates = [
+    await resolvePromptValue(promptModule.prompt),
+    await resolvePromptValue(promptModule.agentConfig),
+    await resolvePromptValue(promptModule.default),
+  ]
+
+  for (const candidate of candidates) {
+    const promptText = extractPromptString(candidate)
+    if (promptText !== null) {
+      return promptText
+    }
+  }
+
+  throw new Error(`Prompt module for agent '${agentName}' must export a prompt string.`)
+}
+
+export async function runAgent(
+  agentName: string,
+  codexArgs: string[] = [],
+  processRoot: string = process.cwd(),
+  options: { spawnCodex?: SpawnCodexFn } = {}
+): Promise<AgentRunResult> {
+  const prompt = await loadAgentPrompt(agentName, processRoot)
+  const spawnCodex = options.spawnCodex ?? defaultSpawnCodex
+  const args = ['--config', `developer_instructions=${prompt}`, ...codexArgs]
+  const result = spawnCodex(args)
+
+  if (result.error) {
+    throw new Error(`Failed to start codex: ${result.error.message}`)
+  }
+
+  return {
+    agentName,
+    exitCode: typeof result.status === 'number' ? result.status : toExitCode(result.signal),
+  }
+}
+
 function validateActiveConfigInputs(agentDir: string): void {
   const issues: string[] = []
 
@@ -432,6 +833,7 @@ export async function main(argv: string[], processRoot: string = process.cwd()):
 
   const [scope, maybeAgentOrFlag, maybeTarget, ...rest] = argv
   const listMode = scope === 'agents' && maybeAgentOrFlag === '--list'
+  const createMode = scope === 'agents' && maybeAgentOrFlag === 'create'
 
   if (scope !== 'agents') {
     throw new Error('Expected command `agents` as first positional argument.')
@@ -445,9 +847,24 @@ export async function main(argv: string[], processRoot: string = process.cwd()):
     return listAgents(processRoot).join('\n')
   }
 
+  if (createMode) {
+    if (!maybeTarget) {
+      throw new Error('Missing required argument: <agent-name>.')
+    }
+
+    const unknownFlags = rest.filter(Boolean)
+    if (unknownFlags.length > 0) {
+      throw new Error(`Unknown flags for create mode: ${unknownFlags.join(', ')}`)
+    }
+
+    const result = createAgent(maybeTarget, processRoot)
+    const displayPath = path.relative(processRoot, result.agentRoot) || result.agentRoot
+    return `[${CLI_NAME}] created agent: ${result.agentName} (${displayPath})`
+  }
+
   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') {
@@ -458,11 +875,19 @@ export async function main(argv: string[], processRoot: string = process.cwd()):
     return JSON.stringify(result.loaded, null, 2)
   }
 
+  if (target === 'run') {
+    const result = await runAgent(agentName, rest, processRoot)
+    if (result.exitCode !== 0) {
+      process.exitCode = result.exitCode
+    }
+    return ''
+  }
+
   if (!agentName || !target) {
     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,31 +1,20 @@
-export type GitServiceApiExecutionResult<T = unknown> = {
-  mapping: Record<string, unknown>
-  request: {
-    url: string
-    method: string
-    headers: Record<string, string>
-    query: string[]
-    body?: unknown
-  }
-  response: {
-    headers: Record<string, string>
-  }
-  status: number
-  ok: boolean
-  body: T
-}
-
-export type GitServiceApiMethod = (...args: unknown[]) => Promise<GitServiceApiExecutionResult>
-
-export type GitServiceApi = {
-  [key: string]: GitServiceApi | GitServiceApiMethod
-}
+export type {
+  GitLabelManagementApi,
+  GitLabelManagementDefaults,
+  GitRepositoryLabel,
+  GitServiceApi,
+  GitServiceApiExecutionResult,
+  GitServiceApiMethod,
+} from '../git/packages/git/src/index.ts'
 
 export {
+  attachGitLabelManagementApi,
   buildGitApiMockResponse,
   callIssueDependenciesApi,
+  createGitLabelManagementApi,
   createGitServiceApi,
+  extractRepositoryLabels,
   extractDependencyIssueNumbers,
   resolveProjectRepoIdentity,
   syncIssueDependencies,
-} from './dist/git.js'
+} from '../git/packages/git/src/index.ts'

package/mcp/cli.mjs

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