@foundation0/api 1.0.0

package/mcp/server.ts

@@ -0,0 +1,461 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+import * as agentsApi from '../agents.ts'
+import * as projectsApi from '../projects.ts'
+
+type ApiMethod = (...args: unknown[]) => unknown
+type ToolInvocationPayload = {
+  args?: unknown[]
+  options?: Record<string, unknown>
+  [key: string]: unknown
+}
+type BatchToolCall = {
+  tool: string
+  args?: unknown[]
+  options?: Record<string, unknown>
+  [key: string]: unknown
+}
+type BatchToolCallPayload = {
+  calls: BatchToolCall[]
+  continueOnError: boolean
+}
+type BatchResult = {
+  index: number
+  tool: string
+  isError: boolean
+  data: unknown
+}
+type ToolDefinition = {
+  name: string
+  method: ApiMethod
+  path: string[]
+}
+
+type ToolNamespace = Record<string, unknown>
+
+type ApiEndpoint = {
+  agents: ToolNamespace
+  projects: ToolNamespace
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const normalizePayload = (payload: unknown): { args: string[]; options: Record<string, unknown> } => {
+  if (!isRecord(payload)) {
+    return {
+      args: [],
+      options: {},
+    }
+  }
+
+  const explicitArgs = Array.isArray(payload.args) ? payload.args : undefined
+  const explicitOptions = isRecord(payload.options) ? payload.options : undefined
+
+  const args = explicitArgs ? explicitArgs.map((entry) => String(entry)) : []
+  const options: Record<string, unknown> = explicitOptions ? { ...explicitOptions } : {}
+
+  for (const [key, value] of Object.entries(payload)) {
+    if (key === 'args' || key === 'options') {
+      continue
+    }
+
+    if (value !== undefined) {
+      options[key] = value
+    }
+  }
+
+  return {
+    args,
+    options,
+  }
+}
+
+const normalizeBatchToolCall = (
+  call: unknown,
+  index: number,
+): { tool: string; payload: ToolInvocationPayload } => {
+  if (!isRecord(call)) {
+    throw new Error(`Invalid batch call at index ${index}: expected object`)
+  }
+
+  const tool = typeof call.tool === 'string' ? call.tool.trim() : ''
+  if (!tool) {
+    throw new Error(`Invalid batch call at index ${index}: missing "tool"`)
+  }
+
+  const args = Array.isArray(call.args) ? call.args : []
+  const { options, ...extras } = call
+  const normalized: ToolInvocationPayload = {
+    args,
+    options: isRecord(options) ? options : {},
+  }
+
+  for (const [key, value] of Object.entries(extras)) {
+    if (value !== undefined) {
+      normalized.options[key] = value
+    }
+  }
+
+  return {
+    tool,
+    payload: normalized,
+  }
+}
+
+const normalizeBatchPayload = (payload: unknown): BatchToolCallPayload => {
+  if (!isRecord(payload)) {
+    throw new Error('Batch tool call requires an object payload')
+  }
+
+  if (!Array.isArray(payload.calls)) {
+    throw new Error('Batch tool call requires a "calls" array')
+  }
+
+  const calls = payload.calls.map((call, index) => normalizeBatchToolCall(call, index))
+
+  return {
+    calls: calls.map(({ tool, payload }) => ({
+      tool,
+      ...payload,
+    })),
+    continueOnError: Boolean(payload.continueOnError),
+  }
+}
+
+const collectTools = (api: ToolNamespace, namespace: string[], path: string[] = []): ToolDefinition[] => {
+  const tools: ToolDefinition[] = []
+  const currentPath = [...path, ...namespace]
+
+  for (const [segment, value] of Object.entries(api)) {
+    if (typeof value !== 'function') {
+      continue
+    }
+
+    tools.push({
+      name: [...currentPath, segment].join('.'),
+      method: value as ApiMethod,
+      path: [...currentPath, segment],
+    })
+  }
+
+  return tools
+}
+
+const buildToolName = (tool: ToolDefinition, prefix?: string): string =>
+  prefix ? `${prefix}.${tool.name}` : tool.name
+
+const buildToolList = (tools: ToolDefinition[], batchToolName: string, prefix?: string) => {
+  const toolEntries = tools.map((tool) => ({
+    name: buildToolName(tool, prefix),
+    description: `Call API method ${tool.path.join('.')}`,
+    inputSchema: {
+      type: 'object',
+      additionalProperties: true,
+      properties: {
+        args: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Positional arguments',
+        },
+        options: {
+          type: 'object',
+          additionalProperties: true,
+          description: 'Named options',
+        },
+      },
+    },
+  }))
+
+  const batchTool = {
+    name: batchToolName,
+    description:
+      'Preferred mode for client calls: execute multiple MCP tool calls in one request with parallel execution.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: true,
+      properties: {
+        calls: {
+          type: 'array',
+          minItems: 1,
+          items: {
+            type: 'object',
+            additionalProperties: true,
+            properties: {
+              tool: {
+                type: 'string',
+                description: 'Full MCP tool name to execute',
+              },
+              args: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Positional args for the tool',
+              },
+              options: {
+                type: 'object',
+                additionalProperties: true,
+                description: 'Tool invocation options',
+              },
+            },
+            required: ['tool'],
+          },
+          description: 'List of tool calls to execute',
+        },
+        continueOnError: {
+          type: 'boolean',
+          description: 'Whether to continue when a call in the batch fails',
+          default: false,
+        },
+      },
+      required: ['calls'],
+    },
+  }
+
+  return [...toolEntries, batchTool]
+}
+
+type ToolInvoker = (args: string[], options: Record<string, unknown>) => unknown[]
+
+const buildOptionsOnly = (args: string[], options: Record<string, unknown>): unknown[] => {
+  const invocationArgs: unknown[] = [...args]
+  if (Object.keys(options).length > 0) {
+    invocationArgs.push(options)
+  }
+  return invocationArgs
+}
+
+const buildOptionsThenProcessRoot = (args: string[], options: Record<string, unknown>): unknown[] => {
+  const invocationArgs: unknown[] = [...args]
+  const remaining = { ...options }
+  const processRoot = remaining.processRoot
+  if (typeof processRoot === 'string') {
+    delete remaining.processRoot
+  }
+
+  if (Object.keys(remaining).length > 0) {
+    invocationArgs.push(remaining)
+  }
+  if (typeof processRoot === 'string') {
+    invocationArgs.push(processRoot)
+  }
+
+  return invocationArgs
+}
+
+const buildProcessRootThenOptions = (args: string[], options: Record<string, unknown>): unknown[] => {
+  const invocationArgs: unknown[] = [...args]
+  const remaining = { ...options }
+  const processRoot = remaining.processRoot
+  if (typeof processRoot === 'string') {
+    delete remaining.processRoot
+  }
+
+  if (typeof processRoot === 'string') {
+    invocationArgs.push(processRoot)
+  }
+  if (Object.keys(remaining).length > 0) {
+    invocationArgs.push(remaining)
+  }
+
+  return invocationArgs
+}
+
+const buildProcessRootOnly = (args: string[], options: Record<string, unknown>): unknown[] => {
+  const invocationArgs: unknown[] = [...args]
+  const processRoot = options.processRoot
+  if (typeof processRoot === 'string') {
+    invocationArgs.push(processRoot)
+  }
+  return invocationArgs
+}
+
+const toolInvocationPlans: Record<string, ToolInvoker> = {
+  'agents.setActive': buildProcessRootThenOptions,
+  'agents.resolveAgentsRootFrom': buildProcessRootOnly,
+  'projects.setActive': buildProcessRootThenOptions,
+  'projects.generateSpec': buildOptionsThenProcessRoot,
+  'projects.syncTasks': buildOptionsThenProcessRoot,
+  'projects.clearIssues': buildOptionsThenProcessRoot,
+  'projects.fetchGitTasks': buildOptionsThenProcessRoot,
+  'projects.readGitTask': buildOptionsThenProcessRoot,
+  'projects.writeGitTask': buildOptionsThenProcessRoot,
+  'agents.resolveTargetFile': buildOptionsOnly,
+  'projects.resolveProjectTargetFile': buildOptionsOnly,
+  'agents.loadAgent': buildProcessRootOnly,
+  'agents.main': buildProcessRootOnly,
+  'agents.resolveAgentsRoot': buildProcessRootOnly,
+  'agents.resolveAgentsRootFrom': buildProcessRootOnly,
+  'agents.listAgents': buildProcessRootOnly,
+  'projects.resolveProjectRoot': buildProcessRootOnly,
+  'projects.listProjects': buildProcessRootOnly,
+  'projects.listProjectDocs': buildProcessRootOnly,
+  'projects.readProjectDoc': buildProcessRootOnly,
+  'projects.main': buildProcessRootOnly,
+}
+
+const invokeTool = async (tool: ToolDefinition, payload: unknown): Promise<unknown> => {
+  const { args, options } = normalizePayload(payload)
+  const invoke = toolInvocationPlans[tool.name] ?? ((rawArgs, rawOptions) => {
+    const invocationArgs = [...rawArgs]
+    if (Object.keys(rawOptions).length > 0) {
+      invocationArgs.push(rawOptions)
+    }
+    return invocationArgs
+  })
+  const invocationArgs = invoke(args, options)
+
+  return Promise.resolve(tool.method(...invocationArgs))
+}
+
+export interface F0McpServerOptions {
+  serverName?: string
+  serverVersion?: string
+  toolsPrefix?: string
+}
+
+export type F0McpServerInstance = {
+  api: ApiEndpoint
+  tools: ToolDefinition[]
+  server: Server
+  run: () => Promise<Server>
+}
+
+export const createF0McpServer = (options: F0McpServerOptions = {}): F0McpServerInstance => {
+  const api: ApiEndpoint = {
+    agents: agentsApi,
+    projects: projectsApi,
+  }
+
+  const tools = [
+    ...collectTools(api.agents, ['agents']),
+    ...collectTools(api.projects, ['projects']),
+  ]
+  const prefix = options.toolsPrefix
+  const batchToolName = prefix ? `${prefix}.batch` : 'batch'
+
+  const server = new Server(
+    {
+      name: options.serverName ?? 'f0-api',
+      version: options.serverVersion ?? '1.0.0',
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    },
+  )
+
+  const toolByName = new Map<string, ToolDefinition>(tools.map((tool) => [buildToolName(tool, prefix), tool]))
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: buildToolList(tools, batchToolName, prefix),
+  }))
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const requestedName = request.params.name
+
+    if (requestedName === batchToolName) {
+      try {
+        const { calls, continueOnError } = normalizeBatchPayload(request.params.arguments)
+        const executions = calls.map(({ tool, args = [], options = {} }, index) => ({ tool, args, options, index }))
+        const results = await Promise.all(
+          executions.map(async ({ tool, args, options, index }) => {
+            const toolDefinition = toolByName.get(tool)
+            if (!toolDefinition) {
+              return {
+                index,
+                tool,
+                isError: true,
+                data: `Unknown tool: ${tool}`,
+              } as BatchResult
+            }
+
+            try {
+              const data = await invokeTool(toolDefinition, { args, options })
+              return {
+                index,
+                tool,
+                isError: false,
+                data,
+              } as BatchResult
+            } catch (error) {
+              if (continueOnError) {
+                return {
+                  index,
+                  tool,
+                  isError: true,
+                  data: error instanceof Error ? error.message : String(error),
+                } as BatchResult
+              }
+              throw error
+            }
+          }),
+        )
+
+        return {
+          isError: results.some((result) => result.isError),
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(results, null, 2),
+            },
+          ],
+        }
+      } catch (error) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: 'text',
+              text: error instanceof Error ? error.message : String(error),
+            },
+          ],
+        }
+      }
+    }
+
+    const tool = toolByName.get(requestedName)
+
+    if (!tool) {
+      throw new Error(`Unknown tool: ${requestedName}`)
+    }
+
+    try {
+      const data = await invokeTool(tool, request.params.arguments)
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(data, null, 2),
+          },
+        ],
+      }
+    } catch (error) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: 'text',
+            text: error instanceof Error ? error.message : String(error),
+          },
+        ],
+      }
+    }
+  })
+
+  const run = async (): Promise<Server> => {
+    await server.connect(new StdioServerTransport())
+    return server
+  }
+
+  return { api, tools, server, run }
+}
+
+export const runF0McpServer = async (options: F0McpServerOptions = {}): Promise<Server> => {
+  const instance = createF0McpServer(options)
+  return instance.run()
+}
+
+export const normalizeToolCallNameForServer = (prefix: string | undefined, toolName: string): string =>
+  prefix ? toolName.replace(new RegExp(`^${prefix}\\.`), '') : toolName

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@foundation0/api",
+  "version": "1.0.0",
+  "description": "Foundation 0 API",
+  "type": "module",
+  "bin": {
+    "f0-mcp": "./mcp/cli.mjs",
+    "f0-mcp-server": "./mcp/cli.mjs"
+  },
+  "private": false,
+  "main": "agents.ts",
+  "keywords": [
+    "foundation0",
+    "f0",
+    "api"
+  ],
+  "author": "",
+  "license": "ISC",
+  "files": [
+    "agents.ts",
+    "git.ts",
+    "dist/git.js",
+    "taskgraph-parser.ts",
+    "projects.ts",
+    "mcp"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build:git": "bun build ../git/packages/git/src/index.ts --target bun --format esm --minify --outfile ./dist/git.js",
+    "mcp": "bun run mcp/cli.ts",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "deploy": "pnpm prepublishOnly && pnpm publish --access public",
+    "version:patch": "pnpm version patch",
+    "version:minor": "pnpm version minor",
+    "version:major": "pnpm version major"
+  }
+}