ClawHire MCP

Instructions

Implementation Reference

• src/tools/list_applications.ts:73-195 (handler)

  The main handler (execute function) for list_applications tool. Validates session, calls backend API, formats application data with match scores and AI fluency badges, groups results by status, and returns paginated results with next step suggestions.

  async execute(input: Input) {
    // Validate session
    const session = getSession(input.session_id);
    if (!session) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              error: {
                code: 'INVALID_SESSION',
                message: '会话已过期或无效，请重新调用 register_company',
              },
            }, null, 2),
          },
        ],
        isError: true,
      };
    }
  
    try {
      const response = await listApplications({
        session_id: input.session_id,
        job_token: input.job_token,
        status: input.status,
        page: input.page,
        page_size: input.page_size,
      });
  
      const { data } = response;
  
      // Format applications
      const formattedApplications = data.applications.map(app => ({
        application_id: app.application_id,
        job: {
          token: app.job_token,
          post: app.job_post,
        },
        candidate: {
          id: app.candidate_id,
          headline: app.candidate_headline,
          source: app.candidate_source,
          source_badge: sourceBadgeMap[app.candidate_source] || app.candidate_source,
        },
        match: {
          score: app.match_score,
          reasons: app.match_reasons,
        },
        ai_fluency: {
          badge: app.ai_fluency_badge,
          label: app.ai_fluency_badge === 'ai_power_user' ? 'AI高级用户'
            : app.ai_fluency_badge === 'verified_mcp_user' ? 'MCP用户'
            : app.ai_fluency_badge === 'ai_aware' ? 'AI了解者'
            : '未标识',
        },
        application: {
          status: app.status,
          status_text: statusTextMap[app.status] || app.status,
          applied_at: app.applied_at,
          cover_note: app.cover_note,
        },
      }));
  
      // Group by status for summary
      const statusCounts = data.applications.reduce((acc, app) => {
        acc[app.status] = (acc[app.status] || 0) + 1;
        return acc;
      }, {} as Record<string, number>);
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              data: {
                applications: formattedApplications,
                summary: {
                  total: data.total,
                  by_status: statusCounts,
                  ai_fluent_candidates: data.applications.filter(
                    a => a.ai_fluency_badge === 'ai_power_user' || a.ai_fluency_badge === 'verified_mcp_user'
                  ).length,
                },
              },
              pagination: {
                page: data.page,
                page_size: data.page_size,
              },
              meta: {
                session_id: session.session_id,
              },
              next_steps: formattedApplications.length > 0
                ? [
                    '调用 view_candidate 查看感兴趣的候选人详细档案',
                    '高匹配度候选人建议优先联系',
                  ]
                : [
                    '暂无新申请，调用 search_candidates 主动寻找候选人',
                    '调用 list_jobs 查看职位状态',
                  ],
            }, null, 2),
          },
        ],
        isError: false,
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : '获取申请列表失败';
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              error: {
                code: 'LIST_APPLICATIONS_FAILED',
                message: errorMessage,
              },
            }, null, 2),
          },
        ],
        isError: true,
      };
    }
  },

• src/tools/list_applications.ts:12-36 (schema)

  Zod input schema definition for list_applications tool. Defines validation for session_id (required), job_token (optional), status enum, page and page_size parameters with appropriate constraints.

  const inputSchema = z.object({
    session_id: z.string()
      .describe('会话 ID，从 register_company 获取'),
    
    job_token: z.string()
      .optional()
      .describe('按职位过滤（可选），不提供则显示所有职位的申请'),
    
    status: z.enum(['submitted', 'viewed', 'shortlisted', 'rejected'])
      .optional()
      .describe('按状态过滤：submitted=新申请, viewed=已查看, shortlisted=已筛选, rejected=已拒绝'),
    
    page: z.number()
      .int()
      .positive()
      .optional()
      .describe('页码'),
    
    page_size: z.number()
      .int()
      .positive()
      .max(50)
      .optional()
      .describe('每页数量'),
  });

• src/tools/index.ts:33-57 (registration)

  Registration of listApplicationsTool - imported from list_applications.ts, exported, and added to the allTools registry array for MCP server initialization.

  import { listApplicationsTool } from './list_applications.js';
  import { requestOutreachTool } from './request_outreach.js';
  
  // Export all tools
  export {
    registerCompanyTool,
    postJobTool,
    listJobsTool,
    searchCandidatesTool,
    viewCandidateTool,
    listApplicationsTool,
    requestOutreachTool,
  };
  
  // Tool registry for server initialization
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  export const allTools: Tool<any>[] = [
    registerCompanyTool,
    postJobTool,
    listJobsTool,
    searchCandidatesTool,
    viewCandidateTool,
    listApplicationsTool,
    requestOutreachTool,
  ];

• src/backend-api.ts:311-340 (helper)

  Backend API helper for list_applications. Defines ListApplicationsInput/Output interfaces and the listApplications function that makes GET requests to /applications endpoint with query parameters.

  export interface ListApplicationsInput {
    session_id: string;
    job_token?: string;
    status?: string;
    page?: number;
    page_size?: number;
  }
  
  export interface ListApplicationsOutput {
    applications: Application[];
    total: number;
    page: number;
    page_size: number;
  }
  
  export async function listApplications(
    input: ListApplicationsInput
  ): Promise<ApiResponse<ListApplicationsOutput>> {
    const params = new URLSearchParams();
    params.append('session_id', input.session_id);
    if (input.job_token) params.append('job_token', input.job_token);
    if (input.status) params.append('status', input.status);
    if (input.page !== undefined) params.append('page', input.page.toString());
    if (input.page_size !== undefined) params.append('page_size', input.page_size.toString());
  
    return apiRequest(`/applications?${params.toString()}`, {
      method: 'GET',
      sessionId: input.session_id,
    });
  }