Skip to main content

Bridging Microsoft Spec Kit to Amazon Q Developer with MCP

· 6 min read
Akhan Zhakiyanov
Akhan Zhakiyanov
Lead engineer
warning

This is just a workaround while waiting for native spec-kit support for Q Developer:

  1. ✅ Amazon Q Developer CLI Enhancement: PR #2799 was created to add custom prompt support
  2. 🚧 Spec Kit Implementation: PR #600 by Heejae Kim is implementing native Q Developer support

As outlined in GitHub's official announcement, developers can now use their AI tool of choice (Claude, Gemini, Cursor, Copilot, etc) for spec-driven development with GitHub's open source Spec Kit, but Q Developer users are left out of this unified experience.

We can address this missing piece with local stdio MCP server bridge while we wait for native support to land in Spec Kit.

What is Spec-Driven Development?​

Spec-driven development starts with detailed, executable specifications that directly generate working implementations leveraging existing AI tools capabilities

This approach offers several key benefits:

  • Consistency: Specifications ensure all team members understand requirements the same way
  • Traceability: Clear connection between requirements and implementation
  • AI-Friendly: Structured specifications work better with AI code generation
  • Documentation: Specifications serve as living documentation
  • Quality: Reduces ambiguity and miscommunication

How Spec-Kit Unifies Spec-Driven Development​

Spec-Kit provides a comprehensive set of commands that work consistently across all supported AI assistants:

CommandPurposeExample
specifyCreate detailed specifications from natural languagespecify "user authentication with email/password"
planGenerate implementation plans from specificationsplan auth_spec.md
implementGenerate code from specificationsimplement auth_spec.md --output ./src
analyzeReview project state and provide insightsanalyze ./my-project
tasksBreak down work into actionable taskstasks auth_spec.md
init_projectInitialize new spec-kit projectsinit_project my-app --ai claude

Without a unified framework, spec-driven development becomes fragmented:

  • Inconsistent workflows - Each AI assistant has different ways to handle specifications
  • Manual coordination - Developers must manually manage the flow from idea → spec → code
  • Tool switching - Different tools for different phases of development
  • Lost context - Specifications and code become disconnected over time

The Challenge with Amazon Q Developer​

In September 2025, Hiroki Yamazaki opened GitHub issue #15 requesting support for Amazon Q Developer CLI and IDE.

The Spec Kit team investigated the request, they discovered that Amazon Q Developer lacked the necessary extensibility features:

  • No custom slash commands - Spec Kit relies on custom commands like /specify, /plan, /implement
  • No custom prompts - The ability to inject structured prompts into conversations
  • Limited integration APIs - No direct way to extend Q Developer's functionality

Recognizing these limitations, the community took action:

  1. Amazon Q Developer CLI Enhancement: PR #2799 was created to add custom prompt support
  2. VSCode Integration Request: Issue #7984 requested workspace-local prompt storage
  3. Spec Kit Implementation: PR #600 by Heejae Kim is implementing native Q Developer support

This creates the perfect use case for an MCP bridge - providing immediate access to spec-driven development while the official integration is being developed.

The Solution: MCP Bridge​

We'll build an MCP server that acts as a translator between Q Developer and Spec Kit:

Q Developer ←→ MCP Server ←→ Spec Kit CLI/Templates

The MCP server acts as a protocol translator, converting Q Developer's tool calls into spec-kit operations.

1. MCP Server Implementation​

The MCP server implementation is available at https://github.com/ahanoff/spec-kit-mcp-go. This Go-based server provides a complete bridge between Amazon Q Developer and Microsoft's Spec-Kit.

The server works as a global MCP server, allowing you to manage multiple projects and work from any directory without needing to restart the server when switching between projects.

2. Installation and Setup​

Complete setup process:

# 1. Clone the repository
git clone https://github.com/ahanoff/spec-kit-mcp-go.git
cd spec-kit-mcp-go

# 2. Build the MCP server
chmod +x build.sh
./build.sh

# 3. Verify the build
ls -la spec-kit-mcp-go

# 4. Install spec-kit globally
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 5. Test spec-kit installation
specify --version

This creates the binary executable that Q Developer can use to communicate with Spec-Kit.

3. Q Developer Configuration​

Configure Q Developer to use the MCP server by adding to ~/.aws/amazonq/mcp.json:

{
  "mcpServers": {
    "spec-kit": {
      "type": "stdio",
      "command": "/path/to/spec-kit-mcp-go/spec-kit-mcp-go",
      "timeout": 120000
    }
  }
}

4. Testing the Integration​

Verify the server works:

# Check MCP server status
q mcp status --name spec-kit

# Test the binary directly
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | ./spec-kit-mcp-go

# Start Q Developer
q

In the Q chat session, you can now use natural language:

Use the init_project tool to create a new spec-kit project called "my-app"
Use the specify tool to create a specification for user authentication with email and password
Use the plan tool to generate an implementation plan from the spec file temp_spec.md
Use the implement tool to generate code from the specification

Resources​