Spec MCP Server

Overview Schema Related Servers Score Discussions

Task Executor

task-executor

Execute specific development tasks by providing detailed implementation guidance, requirements, acceptance criteria, and code patterns for systematic project completion.

Instructions

Executes a specific task from tasks.md by providing detailed implementation guidance, requirements, acceptance criteria, and code patterns. This tool focuses on implementing one task thoroughly.

Input Schema

TableJSON Schema

Name	Required	Description
`project_path`	No	Path to the project directory (defaults to current directory)
`task_id`	Yes	Task ID to execute (e.g., T-1, T-2)
`update_status`	No	Whether to include instructions for updating task status (default: true)

Implementation Reference

src/server.ts:620-874 (registration)

Registers the 'task-executor' MCP tool with server.registerTool, specifying name, metadata, input schema, and handler function.

server.registerTool(
  'task-executor',
  {
    title: 'Task Executor',
    description: 'Executes a specific task from tasks.md by providing detailed implementation guidance, requirements, acceptance criteria, and code patterns. This tool focuses on implementing one task thoroughly.',
    inputSchema: {
      task_id: z.string().describe("Task ID to execute (e.g., T-1, T-2)"),
      project_path: z.string().optional().describe("Path to the project directory (defaults to current directory)"),
      update_status: z.boolean().optional().describe("Whether to include instructions for updating task status (default: true)")
    }
  },
  async ({ task_id, project_path = '.', update_status = true }) => {
    const prompt = `# Task Execution Guide for ${task_id}

## SIMPLICITY PRINCIPLES
1. Keep outputs simple, clean, and straightforward.
2. Do not cut scope or functionality to be "simple".
3. Implement only what’s needed to satisfy acceptance criteria.
4. Prefer minimal steps and sections; avoid ceremony.
5. Reuse existing patterns; avoid new abstractions unless essential.
6. Avoid overengineering — choose the smallest design that works.
7. Be concise in wording, complete in coverage.
8. Iterate: ship minimal complete, then improve.

## ⚠️ CRITICAL: TASK COMPLETION RULES
**DO NOT MARK TASK AS DONE UNLESS:**
1. ALL acceptance criteria checkboxes are marked \`[x]\` (not \`[ ]\`)
2. You have verified each checkbox is actually checked in tasks.md
3. Run task-checker tool FIRST to confirm all criteria are met
4. If ANY checkbox remains \`[ ]\`, keep status as "🟡 In Progress"
5. Count and report: "Checked X of Y acceptance criteria"

## PHASE 1: TASK RETRIEVAL
1. Read the tasks file: ${project_path}/.spec/specs/tasks.md
2. Locate Task ${task_id} and extract:
   - Current status (should be ⚪ Not Started or 🟡 In Progress)
   - Requirements and traceability links
   - Acceptance criteria (EARS format)
   - Implementation details
   - Dependencies
   - Testing requirements

## PHASE 2: PRE-EXECUTION CHECKS

### Dependency Verification
Check that all tasks listed in "Blocked By" are marked as ✅ Done.
If any dependencies are not complete, STOP and report the blockage.

### Context Gathering
1. Read steering documents if they exist:
   - ${project_path}/.spec/steering/tech.md for technology standards
   - ${project_path}/.spec/steering/structure.md for file organization
2. Read the tasks document: ${project_path}/.spec/specs/tasks.md
   - Use the Requirements section (R-X) and task details as the source of truth

${update_status ? `
## PHASE 3: STATUS UPDATE - MARK AS IN PROGRESS
Update the task status from ⚪ to 🟡:
\`\`\`
Edit ${project_path}/.spec/specs/tasks.md
Change: **Status**: ⚪ Not Started
To: **Status**: 🟡 In Progress
\`\`\`
` : ''}

## PHASE 4: IMPLEMENTATION PLAN

### Files to Create
From the "Files to Create" section of the task:
1. For each new file listed:
   - Create the file at the specified path
   - Implement according to the code patterns provided
   - Follow the project's coding conventions

### Files to Modify
From the "Files to Modify" section:
1. For each existing file:
   - Read the current content first
   - Make the specified modifications
   - Preserve existing functionality
   - Follow existing code patterns

### Code Implementation
Using the "Code Patterns and Examples" section:
1. Implement the interfaces/types exactly as specified
2. Follow the function signatures provided
3. Add proper error handling
4. Include necessary imports
5. Maintain consistency with existing code

## PHASE 5: ACCEPTANCE CRITERIA IMPLEMENTATION

For each acceptance criterion in EARS format:
- WHEN [condition] THEN THE SYSTEM SHALL [behavior]

Ensure your implementation:
1. Handles the specified condition
2. Produces the expected behavior
3. Includes error cases mentioned
4. Meets performance requirements
5. Satisfies security requirements

### Implementation Checklist:
□ All required files created
□ All required files modified
□ Each acceptance criterion has corresponding code
□ Error handling implemented
□ Edge cases covered
□ Security considerations addressed
□ Performance requirements met

## PHASE 6: TESTING IMPLEMENTATION

### Unit Tests
From "Unit Tests" section:
1. Create test file at specified location
2. Implement tests for:
   - Happy path scenarios
   - Error handling
   - Edge cases
   - Validation logic
   - Mocked dependencies

### Integration Tests
If specified:
1. Test API endpoints
2. Test database interactions
3. Test authentication/authorization
4. Test component communication

### Manual Testing
Follow the "Manual Testing Checklist":
1. Verify each requirement is met
2. Test on different screen sizes (if UI)
3. Test keyboard navigation (if UI)
4. Test error scenarios
5. Verify loading states
6. Test with slow network
7. Check accessibility

## PHASE 7: CODE QUALITY CHECKS

Use the documented commands from .spec/steering/tech.md to ensure quality.
Specifically, look for the "Essential Commands" section (Type Check, Lint/Format, Build, Test).
- If commands are documented: run them and fix issues found.
- If not documented: skip running and add a TODO to update tech.md.

Fix any issues before proceeding.

## PHASE 8: IMPLEMENTATION NOTES

### Key Considerations:
- **Security**: Implement input validation, sanitization, authorization
- **Performance**: Add caching, optimize queries, implement loading states
- **Accessibility**: Include ARIA labels, keyboard navigation, screen reader support
- **Mobile**: Handle touch interactions, responsive breakpoints, gestures
- **Error Handling**: User-friendly messages, fallback UI, retry logic
- **Logging**: Add debug info, error tracking, user action tracking

### Best Practices:
1. Follow existing code patterns in the project
2. Use existing utilities and helper functions
3. Maintain consistent naming conventions
4. Follow the project's typing conventions or type-safety practices
5. Keep functions small and focused
6. Write self-documenting code

${update_status ? `
## PHASE 9: TASK COMPLETION
Once implementation is complete and tested:

**⚠️ CRITICAL VERIFICATION BEFORE MARKING DONE:**
1. First, verify ALL checkboxes are checked:
   - Count total acceptance criteria
   - Ensure EVERY single one shows \`- [x]\` (not \`- [ ]\`)
   - If ANY remain unchecked, DO NOT mark as Done

2. Update task status to Done ONLY if ALL checkboxes are \`[x]\`:
\`\`\`
Edit ${project_path}/.spec/specs/tasks.md
Change: **Status**: 🟡 In Progress
To: **Status**: ✅ Done
\`\`\`

3. Check all acceptance criteria checkboxes:
\`\`\`
Change: - [ ] [Criterion]
To: - [x] [Criterion]
\`\`\`

**RULE: Status can be "Done" ONLY when 100% of checkboxes show \`[x]\`**
` : ''}

## PHASE 10: POST-EXECUTION

### Verify Completion:
1. **ALL acceptance criteria checkboxes marked \`[x]\` (MANDATORY)**
2. All acceptance criteria met
3. All tests passing
4. No compilation errors
5. No linting errors (or only acceptable warnings)
6. Build succeeds
7. Manual testing complete

**⚠️ If any checkbox is \`[ ]\`, task is NOT complete regardless of other factors**

### Document Any Issues:
If you encountered any problems or made significant decisions:
1. Note them in the task's Implementation Notes section
2. Update documentation if needed
3. Create follow-up tasks if necessary

### Next Steps:
1. Run task-checker tool to confirm task is complete
2. Check for newly unblocked tasks
3. Run task-orchestrator to identify next tasks

## EXECUTION SUMMARY

**Task**: ${task_id}
**Objective**: [Extract from task description]
**Key Requirements**: [List from acceptance criteria]
**Implementation Approach**: [Your planned approach]
**Testing Strategy**: [How you'll verify correctness]
**Risk Factors**: [Any concerns or blockers]

Remember: Focus on completing this ONE task thoroughly before moving to the next. Quality over quantity.

## ⚠️ IMPORTANT: THIS IS A SPEC MCP TOOL INSTRUCTION ⚠️

**YOU ARE NOW READING INSTRUCTIONS FROM THE SPEC MCP \`task-executor\` TOOL**

This tool has provided you with implementation guidance for Task ${task_id}.

**What you MUST do now:**
1. **IMPLEMENT** the task following the phases above
2. **UPDATE** the task status in ${project_path}/.spec/specs/tasks.md file (NOT internal TODO list)
3. **CHECK** acceptance criteria boxes as you complete them
4. **VERIFY** with Spec MCP \`task-checker\` tool when done

**Clarification:**
- Task status is tracked in the tasks.md FILE (not VSCode's internal TODO system)
- Update status by EDITING the tasks.md file directly
- After implementation, CALL the Spec MCP \`task-checker\` tool to verify

**DO NOT** just read these instructions - **ACTUALLY IMPLEMENT** the task now!`;

    return {
      content: [{
        type: "text",
        text: prompt
      }]
    };
  }
);

src/server.ts:631-873 (handler)

The handler function constructs a detailed, phased prompt template providing step-by-step guidance for executing a specific task (reading tasks.md, implementing code/tests, updating status, verifying completion) and returns it as text content for the MCP client.

  async ({ task_id, project_path = '.', update_status = true }) => {
    const prompt = `# Task Execution Guide for ${task_id}

## SIMPLICITY PRINCIPLES
1. Keep outputs simple, clean, and straightforward.
2. Do not cut scope or functionality to be "simple".
3. Implement only what’s needed to satisfy acceptance criteria.
4. Prefer minimal steps and sections; avoid ceremony.
5. Reuse existing patterns; avoid new abstractions unless essential.
6. Avoid overengineering — choose the smallest design that works.
7. Be concise in wording, complete in coverage.
8. Iterate: ship minimal complete, then improve.

## ⚠️ CRITICAL: TASK COMPLETION RULES
**DO NOT MARK TASK AS DONE UNLESS:**
1. ALL acceptance criteria checkboxes are marked \`[x]\` (not \`[ ]\`)
2. You have verified each checkbox is actually checked in tasks.md
3. Run task-checker tool FIRST to confirm all criteria are met
4. If ANY checkbox remains \`[ ]\`, keep status as "🟡 In Progress"
5. Count and report: "Checked X of Y acceptance criteria"

## PHASE 1: TASK RETRIEVAL
1. Read the tasks file: ${project_path}/.spec/specs/tasks.md
2. Locate Task ${task_id} and extract:
   - Current status (should be ⚪ Not Started or 🟡 In Progress)
   - Requirements and traceability links
   - Acceptance criteria (EARS format)
   - Implementation details
   - Dependencies
   - Testing requirements

## PHASE 2: PRE-EXECUTION CHECKS

### Dependency Verification
Check that all tasks listed in "Blocked By" are marked as ✅ Done.
If any dependencies are not complete, STOP and report the blockage.

### Context Gathering
1. Read steering documents if they exist:
   - ${project_path}/.spec/steering/tech.md for technology standards
   - ${project_path}/.spec/steering/structure.md for file organization
2. Read the tasks document: ${project_path}/.spec/specs/tasks.md
   - Use the Requirements section (R-X) and task details as the source of truth

${update_status ? `
## PHASE 3: STATUS UPDATE - MARK AS IN PROGRESS
Update the task status from ⚪ to 🟡:
\`\`\`
Edit ${project_path}/.spec/specs/tasks.md
Change: **Status**: ⚪ Not Started
To: **Status**: 🟡 In Progress
\`\`\`
` : ''}

## PHASE 4: IMPLEMENTATION PLAN

### Files to Create
From the "Files to Create" section of the task:
1. For each new file listed:
   - Create the file at the specified path
   - Implement according to the code patterns provided
   - Follow the project's coding conventions

### Files to Modify
From the "Files to Modify" section:
1. For each existing file:
   - Read the current content first
   - Make the specified modifications
   - Preserve existing functionality
   - Follow existing code patterns

### Code Implementation
Using the "Code Patterns and Examples" section:
1. Implement the interfaces/types exactly as specified
2. Follow the function signatures provided
3. Add proper error handling
4. Include necessary imports
5. Maintain consistency with existing code

## PHASE 5: ACCEPTANCE CRITERIA IMPLEMENTATION

For each acceptance criterion in EARS format:
- WHEN [condition] THEN THE SYSTEM SHALL [behavior]

Ensure your implementation:
1. Handles the specified condition
2. Produces the expected behavior
3. Includes error cases mentioned
4. Meets performance requirements
5. Satisfies security requirements

### Implementation Checklist:
□ All required files created
□ All required files modified
□ Each acceptance criterion has corresponding code
□ Error handling implemented
□ Edge cases covered
□ Security considerations addressed
□ Performance requirements met

## PHASE 6: TESTING IMPLEMENTATION

### Unit Tests
From "Unit Tests" section:
1. Create test file at specified location
2. Implement tests for:
   - Happy path scenarios
   - Error handling
   - Edge cases
   - Validation logic
   - Mocked dependencies

### Integration Tests
If specified:
1. Test API endpoints
2. Test database interactions
3. Test authentication/authorization
4. Test component communication

### Manual Testing
Follow the "Manual Testing Checklist":
1. Verify each requirement is met
2. Test on different screen sizes (if UI)
3. Test keyboard navigation (if UI)
4. Test error scenarios
5. Verify loading states
6. Test with slow network
7. Check accessibility

## PHASE 7: CODE QUALITY CHECKS

Use the documented commands from .spec/steering/tech.md to ensure quality.
Specifically, look for the "Essential Commands" section (Type Check, Lint/Format, Build, Test).
- If commands are documented: run them and fix issues found.
- If not documented: skip running and add a TODO to update tech.md.

Fix any issues before proceeding.

## PHASE 8: IMPLEMENTATION NOTES

### Key Considerations:
- **Security**: Implement input validation, sanitization, authorization
- **Performance**: Add caching, optimize queries, implement loading states
- **Accessibility**: Include ARIA labels, keyboard navigation, screen reader support
- **Mobile**: Handle touch interactions, responsive breakpoints, gestures
- **Error Handling**: User-friendly messages, fallback UI, retry logic
- **Logging**: Add debug info, error tracking, user action tracking

### Best Practices:
1. Follow existing code patterns in the project
2. Use existing utilities and helper functions
3. Maintain consistent naming conventions
4. Follow the project's typing conventions or type-safety practices
5. Keep functions small and focused
6. Write self-documenting code

${update_status ? `
## PHASE 9: TASK COMPLETION
Once implementation is complete and tested:

**⚠️ CRITICAL VERIFICATION BEFORE MARKING DONE:**
1. First, verify ALL checkboxes are checked:
   - Count total acceptance criteria
   - Ensure EVERY single one shows \`- [x]\` (not \`- [ ]\`)
   - If ANY remain unchecked, DO NOT mark as Done

2. Update task status to Done ONLY if ALL checkboxes are \`[x]\`:
\`\`\`
Edit ${project_path}/.spec/specs/tasks.md
Change: **Status**: 🟡 In Progress
To: **Status**: ✅ Done
\`\`\`

3. Check all acceptance criteria checkboxes:
\`\`\`
Change: - [ ] [Criterion]
To: - [x] [Criterion]
\`\`\`

**RULE: Status can be "Done" ONLY when 100% of checkboxes show \`[x]\`**
` : ''}

## PHASE 10: POST-EXECUTION

### Verify Completion:
1. **ALL acceptance criteria checkboxes marked \`[x]\` (MANDATORY)**
2. All acceptance criteria met
3. All tests passing
4. No compilation errors
5. No linting errors (or only acceptable warnings)
6. Build succeeds
7. Manual testing complete

**⚠️ If any checkbox is \`[ ]\`, task is NOT complete regardless of other factors**

### Document Any Issues:
If you encountered any problems or made significant decisions:
1. Note them in the task's Implementation Notes section
2. Update documentation if needed
3. Create follow-up tasks if necessary

### Next Steps:
1. Run task-checker tool to confirm task is complete
2. Check for newly unblocked tasks
3. Run task-orchestrator to identify next tasks

## EXECUTION SUMMARY

**Task**: ${task_id}
**Objective**: [Extract from task description]
**Key Requirements**: [List from acceptance criteria]
**Implementation Approach**: [Your planned approach]
**Testing Strategy**: [How you'll verify correctness]
**Risk Factors**: [Any concerns or blockers]

Remember: Focus on completing this ONE task thoroughly before moving to the next. Quality over quantity.

## ⚠️ IMPORTANT: THIS IS A SPEC MCP TOOL INSTRUCTION ⚠️

**YOU ARE NOW READING INSTRUCTIONS FROM THE SPEC MCP \`task-executor\` TOOL**

This tool has provided you with implementation guidance for Task ${task_id}.

**What you MUST do now:**
1. **IMPLEMENT** the task following the phases above
2. **UPDATE** the task status in ${project_path}/.spec/specs/tasks.md file (NOT internal TODO list)
3. **CHECK** acceptance criteria boxes as you complete them
4. **VERIFY** with Spec MCP \`task-checker\` tool when done

**Clarification:**
- Task status is tracked in the tasks.md FILE (not VSCode's internal TODO system)
- Update status by EDITING the tasks.md file directly
- After implementation, CALL the Spec MCP \`task-checker\` tool to verify

**DO NOT** just read these instructions - **ACTUALLY IMPLEMENT** the task now!`;

    return {
      content: [{
        type: "text",
        text: prompt
      }]
    };
  }

src/server.ts:625-629 (schema)

Zod-based input schema defining parameters for the task-executor tool: required task_id, optional project_path and update_status.

inputSchema: {
  task_id: z.string().describe("Task ID to execute (e.g., T-1, T-2)"),
  project_path: z.string().optional().describe("Path to the project directory (defaults to current directory)"),
  update_status: z.boolean().optional().describe("Whether to include instructions for updating task status (default: true)")
}

Tool Definition Quality

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the tool as executing a task by 'providing detailed implementation guidance', which implies a read-only or advisory role rather than direct code execution, but it doesn't clarify permissions, side effects, or output format. For a tool named 'executor' with zero annotation coverage, this is a significant gap in transparency about its actual behavior and limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is highly concise and well-structured in two sentences. The first sentence clearly states the purpose and key components (guidance, requirements, etc.), and the second sentence emphasizes the focus on thorough implementation. Every word earns its place with no redundancy or fluff, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description is partially complete. It adequately explains the purpose and scope but lacks details on behavioral aspects like output format, error handling, or integration with sibling tools. Without annotations or output schema, the description should do more to compensate, but it provides a basic foundation that is minimally viable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the schema already documents all three parameters (project_path, task_id, update_status) with clear descriptions. The tool description adds no additional parameter semantics beyond what's in the schema, such as examples for task_id format or implications of update_status. This meets the baseline for high schema coverage but doesn't enhance understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Executes a specific task from tasks.md by providing detailed implementation guidance, requirements, acceptance criteria, and code patterns.' It specifies the verb ('executes'), resource ('task from tasks.md'), and scope ('one task thoroughly'), distinguishing it from siblings like 'task-checker' or 'task-orchestrator'. However, it doesn't explicitly contrast with all siblings (e.g., 'generate-codebase-analysis'), keeping it from a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides minimal guidance on when to use this tool. It mentions 'focuses on implementing one task thoroughly', which implies usage for detailed task execution, but offers no explicit when-to-use rules, prerequisites, or alternatives among siblings like 'task-orchestrator' or 'task-checker'. This lack of comparative context leaves the agent with insufficient guidance for tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/karol-f/spec-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server