agentbay_project_onboard

Instructions

Implementation Reference

• src/index.ts:246-293 (handler)

  The function that executes the tool logic: sends an onboard POST request to /api/v1/projects/${projectId}/onboard, then assembles a rich text response with project brief, file tree (first 50 files), open tasks, known pitfalls, last handoff, recent failures, directives, session ID, and a message.

  async ({ projectId, agentName, capabilities }) => {
    const data = await apiPost(`/api/v1/projects/${projectId}/onboard`, {
      agentName: agentName || 'mcp-agent',
      capabilities,
    });
    if (data.error) return { content: [{ type: 'text' as const, text: `Error: ${data.error}` }] };
  
    let text = `# ${data.project?.name || 'Project'}\n`;
    if (data.project?.brief) text += `\n## Brief\n${data.project.brief}\n`;
  
    text += `\n## Codebase (${data.files?.count || 0} files, ${data.files?.totalSizeKB || 0}KB)\n`;
    if (data.files?.tree?.length) {
      text += data.files.tree.slice(0, 50).map((f: any) => `  ${f.path} (${(f.sizeBytes / 1024).toFixed(1)}KB)`).join('\n') + '\n';
    }
  
    const openTasks = data.tasks?.open || [];
    if (openTasks.length) {
      text += `\n## Open Tasks (${openTasks.length})\n`;
      text += openTasks.map((t: any) => `  - [${t.priority}] ${t.title} (${t.id})`).join('\n') + '\n';
    }
  
    const pitfalls = data.knowledge?.pitfalls || [];
    if (pitfalls.length) {
      text += `\n## Known Pitfalls (${pitfalls.length})\n`;
      text += pitfalls.slice(0, 5).map((k: any) => `- **${k.title}**: ${k.content.substring(0, 150)}`).join('\n') + '\n';
    }
  
    if (data.lastHandoff) {
      text += `\n## Last Handoff\nFrom: ${data.lastHandoff.fromAgent || 'unknown'}\n${data.lastHandoff.summary}\n`;
    }
  
    // Surface recent failures so agents don't repeat mistakes
    const failures = data.recentFailures || [];
    if (failures.length) {
      text += `\n## ⚠ Recent Failures — Do NOT Repeat (${failures.length})\n`;
      text += failures.map((f: any) => `- **${f.title}**: ${f.content.substring(0, 200)}`).join('\n') + '\n';
    }
  
    // Directives — baked into every onboard response
    if (data.directives?.length) {
      text += `\n## Directives\n`;
      text += data.directives.map((d: string) => `- ${d}`).join('\n') + '\n';
    }
  
    if (data.sessionId) text += `\nSession ID: ${data.sessionId}\n`;
    text += `\n---\n${data.message}`;
    return { content: [{ type: 'text' as const, text }] };
  }

• src/index.ts:241-245 (schema)

  Input validation using Zod: requires a projectId string, with optional agentName string and capabilities string array.

  {
    projectId: z.string().describe('Project ID'),
    agentName: z.string().optional().describe('Your agent name/framework'),
    capabilities: z.array(z.string()).optional().describe('Your capabilities'),
  },

• src/index.ts:238-244 (registration)

  Registration of the tool via server.tool('agentbay_project_onboard', ...) with a descriptive comment 'Tool 14: Project Onboard'.

  server.tool(
    'agentbay_project_onboard',
    'One-call onboarding: returns project brief, file tree, open tasks, knowledge, recent failures to avoid, directives, active agents, and policies. Call this first when connecting to a project. Follow the directives in the response.',
    {
      projectId: z.string().describe('Project ID'),
      agentName: z.string().optional().describe('Your agent name/framework'),
      capabilities: z.array(z.string()).optional().describe('Your capabilities'),