Project Handoffs MCP Server

Instructions

Implementation Reference

• src/index.ts:151-176 (handler)

  Core handler function in ProjectManager that executes the create_next_step logic: validates template, checks dependencies, generates ID/timestamps, persists to project data file.

  async createNextStep(projectId: string, step: Omit<NextStep, 'id' | 'created' | 'lastModified'>): Promise<NextStep> {
    this.validateTemplate('next_step', step);
    
    const data = await this.loadProjectData(projectId);
    
    const newStep: NextStep = {
      ...step,
      id: `step_${Date.now()}`,
      created: new Date().toISOString(),
      lastModified: new Date().toISOString(),
    };
  
    // Validate dependencies exist
    if (step.dependencies?.length) {
      const missingDeps = step.dependencies.filter(
        depId => !data.nextSteps.some(s => s.id === depId)
      );
      if (missingDeps.length > 0) {
        throw new ProjectError(`Dependencies not found: ${missingDeps.join(', ')}`, projectId);
      }
    }
  
    data.nextSteps.push(newStep);
    await this.saveProjectData(projectId, data);
    return newStep;
  }

• src/index.ts:325-344 (schema)

  Input schema definition for the create_next_step tool, specifying parameters, types, descriptions, and required fields.

  inputSchema: {
    type: "object",
    properties: {
      projectId: { type: "string", description: "Project identifier" },
      title: { type: "string", description: "Brief title of the next step" },
      description: { type: "string", description: "Detailed description of work" },
      priority: { 
        type: "string",
        enum: ["core-critical", "full-required", "enhancement"],
        description: "Implementation priority level"
      },
      parentStepId: { type: "string", description: "ID of parent step if this is a substep" },
      dependencies: { 
        type: "array",
        items: { type: "string" },
        description: "IDs of steps that must be completed first"
      }
    },
    required: ["projectId", "title", "description", "priority"]
  }

• src/index.ts:448-466 (registration)

  MCP CallToolRequest handler case that processes arguments and invokes the createNextStep method, returning the result.

  case "create_next_step":
    const step = await projectManager.createNextStep(
      args.projectId as string,
      {
        projectId: args.projectId as string,
        title: args.title as string,
        description: args.description as string,
        priority: args.priority as NextStep['priority'],
        parentStepId: args.parentStepId as string,
        dependencies: args.dependencies as string[] || [],
        status: 'open'
      }
    );
    return {
      content: [{
        type: "text",
        text: JSON.stringify(step, null, 2)
      }]
    };

• src/index.ts:322-344 (registration)

  Tool registration in ListToolsResponse, defining name, description, and input schema for create_next_step.

  {
    name: "create_next_step",
    description: "Create a new next step in a project",
    inputSchema: {
      type: "object",
      properties: {
        projectId: { type: "string", description: "Project identifier" },
        title: { type: "string", description: "Brief title of the next step" },
        description: { type: "string", description: "Detailed description of work" },
        priority: { 
          type: "string",
          enum: ["core-critical", "full-required", "enhancement"],
          description: "Implementation priority level"
        },
        parentStepId: { type: "string", description: "ID of parent step if this is a substep" },
        dependencies: { 
          type: "array",
          items: { type: "string" },
          description: "IDs of steps that must be completed first"
        }
      },
      required: ["projectId", "title", "description", "priority"]
    }

• src/index.ts:89-106 (helper)

  Helper method called by createNextStep to validate input against HANDOFF_TEMPLATES for 'next_step'.

  private validateTemplate(type: string, data: Record<string, any>): void {
    const template = HANDOFF_TEMPLATES[type];
    if (!template) return; // Non-templated types are valid
  
    const missingFields = template.fields
      .filter(field => field.required)
      .filter(field => {
        const fieldName = field.name.toLowerCase().replace(/\s+/g, '_');
        return !data[fieldName] && !data[field.name];
      });
  
    if (missingFields.length > 0) {
      throw new ProjectError(
        `Missing required fields for ${type}: ${missingFields.map(f => f.name).join(', ')}`,
        data.projectId || 'validation'
      );
    }
  }