Project Handoffs MCP Server

Instructions

Implementation Reference

• src/index.ts:206-242 (handler)

  Core handler function in ProjectManager that executes the create_handoff logic: validates template, loads project data, verifies session/step, updates statuses, creates and saves the handoff object.

  async createHandoff(
    projectId: string,
    sessionId: string,
    handoff: Omit<Handoff, 'id' | 'sessionId' | 'timestamp'>
  ): Promise<Handoff> {
    this.validateTemplate('handoff', handoff);
    
    const data = await this.loadProjectData(projectId);
    
    const session = data.workingSessions.find(s => s.id === sessionId);
    if (!session) {
      throw new ProjectError(`Session not found: ${sessionId}`, projectId);
    }
    if (session.endTime) {
      throw new ProjectError(`Session already ended: ${sessionId}`, projectId);
    }
  
    const step = data.nextSteps.find(s => s.id === session.nextStepId);
    if (!step) {
      throw new ProjectError(`Associated next step not found: ${session.nextStepId}`, projectId);
    }
  
    session.endTime = new Date().toISOString();
    step.status = 'completed';
    step.lastModified = new Date().toISOString();
  
    const newHandoff: Handoff = {
      ...handoff,
      id: `handoff_${Date.now()}`,
      sessionId,
      timestamp: new Date().toISOString()
    };
  
    data.handoffs.push(newHandoff);
    await this.saveProjectData(projectId, data);
    return newHandoff;
  }

• src/index.ts:361-381 (schema)

  Input schema definition for the create_handoff tool, specifying properties, types, descriptions, and required fields.

  inputSchema: {
    type: "object",
    properties: {
      projectId: { type: "string", description: "Project identifier" },
      sessionId: { type: "string", description: "Working session ID" },
      completedWork: { type: "string", description: "Summary of completed work" },
      codeState: { type: "string", description: "Current state of codebase" },
      environmentState: { type: "string", description: "Development environment state" },
      unresolvedIssues: {
        type: "array",
        items: { type: "string" },
        description: "List of unresolved issues"
      },
      newNextSteps: {
        type: "array",
        items: { type: "string" },
        description: "List of new next steps identified"
      }
    },
    required: ["projectId", "sessionId", "completedWork", "codeState", "environmentState"]
  }

• src/index.ts:358-382 (registration)

  Tool registration in the ListTools response, defining name, description, and input schema for create_handoff.

  {
    name: "create_handoff",
    description: "Complete a working session with handoff details",
    inputSchema: {
      type: "object",
      properties: {
        projectId: { type: "string", description: "Project identifier" },
        sessionId: { type: "string", description: "Working session ID" },
        completedWork: { type: "string", description: "Summary of completed work" },
        codeState: { type: "string", description: "Current state of codebase" },
        environmentState: { type: "string", description: "Development environment state" },
        unresolvedIssues: {
          type: "array",
          items: { type: "string" },
          description: "List of unresolved issues"
        },
        newNextSteps: {
          type: "array",
          items: { type: "string" },
          description: "List of new next steps identified"
        }
      },
      required: ["projectId", "sessionId", "completedWork", "codeState", "environmentState"]
    }
  },

• src/index.ts:480-497 (handler)

  MCP CallToolRequest handler case that parses arguments and delegates to ProjectManager.createHandoff, returning the result as JSON text content.

  case "create_handoff":
    const handoff = await projectManager.createHandoff(
      args.projectId as string,
      args.sessionId as string,
      {
        completedWork: args.completedWork as string,
        codeState: args.codeState as string,
        environmentState: args.environmentState as string,
        unresolvedIssues: args.unresolvedIssues as string[] || [],
        newNextSteps: args.newNextSteps as string[] || []
      }
    );
    return {
      content: [{
        type: "text",
        text: JSON.stringify(handoff, null, 2)
      }]
    };