gsd-mcp-server

MCP server for the GSD (Get Shit Done) lifecycle framework. Exposes GSD project state, phases, milestones, and commands as MCP tools and resources.

Features

• 34 tools — manage project lifecycle via MCP tool calls
• 6 resources — read project files (state, roadmap, requirements, config, help)
• Zod-validated inputs — type-safe parameter validation
• Secure execution — no shell injection (execFileSync with argument arrays)

Quick Start

Run instantly with npx (no install needed):

npx -y @md0ar/gsd-mcp-server

Or install globally:

```bash
npm install -g @md0ar/gsd-mcp-server

Configuration

opencode.jsonc

{
  "mcp": {
    "gsd-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "@md0ar/gsd-mcp-server"],
      "enabled": true,
      "timeout": 30000
    }
  }
}

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "gsd-mcp-server": {
      "command": "npx",
      "args": ["-y", "@md0ar/gsd-mcp-server"]
    }
  }
}

Cursor

.cursor/mcp.json

{
  "mcpServers": {
    "gsd-mcp-server": {
      "command": "npx",
      "args": ["-y", "gsd-mcp-server"]
    }
  }
}

VS Code

.vscode/mcp.json

{
  "servers": {
    "gsd-mcp-server": {
      "command": "npx",
      "args": ["-y", "@md0ar/gsd-mcp-server"]
    }
  }
}

Always use -y with npx to skip the confirmation prompt — MCP hosts need non-interactive execution.

Requirements

• Node.js 18+
• GSD framework — the server wraps the GSD CLI. Install opencode to use the full GSD lifecycle.

Tools

| Tool | Params | Description | |------|--------|-------------| | gsd_state | — | Current project state | | gsd_progress | — | Next step in the GSD lifecycle | | gsd_new_project | name, description? | Initialize a new project | | gsd_new_milestone | name | Start a new milestone | | gsd_map_codebase | — | Analyze existing codebase | | gsd_discuss_phase | phase | Capture implementation decisions | | gsd_list_phases | — | List roadmap phases | | gsd_plan_phase | phase | Create task plans | | gsd_execute_phase | phase | Execute phase plans | | gsd_verify_work | phase | Verify phase work | | gsd_quick | task, full? | Ad-hoc task | | gsd_debug | issue | Systematic debugging | | gsd_spike | idea, quick? | Throwaway experiment | | gsd_sketch | idea | UI design sketch | | gsd_complete_milestone | version | Archive milestone | | gsd_add_todo | description | Capture todo | | gsd_check_todos | area? | List pending todos | | gsd_ship | phase | Create PR | | gsd_add_phase | description | Add new phase | | gsd_insert_phase | after, description | Insert phase | | gsd_settings | — | Configure toggles | | gsd_set_profile | profile | Switch model profile | | gsd_run | command | Run any GSD command | | gsd_validate | check, repair? | Run validation (consistency/health/agents) | | gsd_roadmap_analyze | — | Full roadmap + disk status analysis | | gsd_phase_complete | phase | Mark a phase as complete | | gsd_config_get | key | Read config value | | gsd_config_set | key, value | Write config value | | gsd_commit | message, files? | Commit planning docs to git | | gsd_scaffold | type, phase, name? | Create document templates | | gsd_audit_uat | — | Scan phases for unresolved verification | | gsd_websearch | query, limit?, freshness? | Web search via Brave API | | gsd_todo_complete | filename | Mark todo as completed | | gsd_workstreams | action, name? | Manage parallel workspaces |

Resources

| URI | Description | |-----|-------------| | gsd://state | Current project state | | gsd://project | Project definition | | gsd://roadmap | Phase roadmap | | gsd://requirements | Feature requirements | | gsd://config | Planning config | | gsd://help | Command reference |

Testing

npm test

Runs 188 tests across three suites: 94 main + 37 edge + 57 functional (real GSD project).

Publishing (for maintainers)

# 1. Log in to npm
npm login

# 2. Publish to npm
npm publish

# 3. Publish to MCP Registry (optional)
npx -y @modelcontextprotocol/publisher login
npx -y @modelcontextprotocol/publisher publish

Requirements:

• npm account
• GitHub account (for MCP Registry auth)
• Granular Access Token with Read and write scope for CI/CD

License

MIT