INTEGRATION.md

Integration Summary: MCP Server + Spec Kit

Changes Made

MCP Server Repository (mcp-speckit-kiro)

1. Automatic Update Checking

• Checks GitHub API for latest commit SHA in templates/commands/
• Stores version in .kiro/prompts/.version
• Auto-updates prompts when new version detected
• Skips update check when using local source (SPECKIT_SOURCE)

How it works:

# On each startup:
1. Check if .kiro/prompts/ exists
2. If exists, compare local .version with GitHub latest commit SHA
3. If different, re-download prompts
4. Update .version file

2. Bootstrap Modes

• GitHub Mode (default): Downloads from github.com/github/spec-kit/main/templates/commands/
• Local Mode: Copies from $SPECKIT_SOURCE/templates/commands/ when env var set

Spec Kit Repository (spec-kit)

1. MCP Detection

Added has_mcp_speckit_server() function that checks:

• If mcp-speckit-kiro command is installed
• If Kiro CLI config has speckit MCP server configured

Checks these config locations:

• macOS: ~/Library/Application Support/kiro-cli/config.json
• Linux: ~/.config/kiro-cli/config.json
• Windows: %APPDATA%/kiro-cli/config.json

2. Skip Prompt Copying

When specify init is run with --ai kiro:

• Checks if MCP server is configured
• If yes, skips copying .kiro/prompts/ directory
• Shows message: "Skipping .kiro/prompts (MCP server will provide prompts)"

User Workflows

Workflow 1: Using MCP Server (Recommended for Kiro)

# 1. Install MCP server
uv tool install --from git+https://github.com/YOUR_ORG/mcp-speckit-kiro.git mcp-speckit-kiro

# 2. Configure Kiro CLI
# Edit ~/Library/Application Support/kiro-cli/config.json:
{
  "mcpServers": {
    "speckit": {
      "command": "mcp-speckit-kiro"
    }
  }
}

# 3. Initialize project (prompts NOT copied)
specify init my-project --ai kiro

# 4. Use prompts via MCP
cd my-project
kiro-cli chat
/prompt speckit.constitution Create principles...

Benefits:

• Prompts auto-update from GitHub
• No local prompt files to maintain
• Single source of truth

Workflow 2: Local Prompts (Traditional)

# 1. Initialize project (prompts copied)
specify init my-project --ai kiro
# (MCP not detected, so .kiro/prompts/ is created)

# 2. Use local prompts
cd my-project
kiro-cli chat
/speckit.constitution Create principles...

Benefits:

• Works offline
• Can customize prompts locally
• No external dependencies

Workflow 3: Development with Local Spec Kit

# 1. Configure MCP with local source
# Edit ~/Library/Application Support/kiro-cli/config.json:
{
  "mcpServers": {
    "speckit": {
      "command": "mcp-speckit-kiro",
      "env": {
        "SPECKIT_SOURCE": "/path/to/spec-kit"
      }
    }
  }
}

# 2. Initialize project
specify init my-project --ai kiro

# 3. Prompts come from local spec-kit source
# Changes to /path/to/spec-kit/templates/commands/*.md are immediately available

Version Management

MCP Server Updates

Prompts are automatically checked for updates on each MCP server startup:

# Force update by deleting version file
rm .kiro/prompts/.version

# Next MCP invocation will check and update if needed

Manual Update

# Delete prompts to force re-download
rm -rf .kiro/prompts

# Next MCP invocation will re-bootstrap

Configuration Examples

Production (Auto-update from GitHub)

{
  "mcpServers": {
    "speckit": {
      "command": "mcp-speckit-kiro"
    }
  }
}

Development (Local source, no updates)

{
  "mcpServers": {
    "speckit": {
      "command": "mcp-speckit-kiro",
      "env": {
        "SPECKIT_SOURCE": "/Users/you/projects/spec-kit"
      }
    }
  }
}

Commits

mcp-speckit-kiro

• d8ea863 - Add automatic update checking for GitHub prompts

spec-kit

• ceed2cb - Skip .kiro/prompts when MCP server is detected