@ai_design_agency/sdd-mcp

MCP (Model Context Protocol) server for the SDD Platform. Exposes spec, process, and session management as Claude-callable tools.

Overview

This package is a thin HTTP client that translates MCP tool calls into Platform API requests. All business logic, validation, and authorization remain centralized in the Platform API.

Claude Code → MCP Server → Platform API → Database

Installation

npm install @ai_design_agency/sdd-mcp

Configuration

The MCP server requires two environment variables:

SDD_API_URL=https://your-platform-api.example.com
SDD_API_TOKEN=your-bearer-token

Claude Code Configuration

Add to your Claude Code MCP settings (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "sdd": {
      "command": "npx",
      "args": ["@ai_design_agency/sdd-mcp"],
      "env": {
        "SDD_API_URL": "https://sdd-api.your-domain.com",
        "SDD_API_TOKEN": "${SDD_API_TOKEN}"
      }
    }
  }
}

Available Tools

Spec Management

| Tool | Description | | ------------- | --------------------------------------- | | spec_create | Create a new SDD specification | | spec_get | Get a spec by ID or spec_number | | spec_update | Update spec content, section, or status | | spec_list | List specs with optional filters | | spec_search | Semantic search across specs |

Process Management

| Tool | Description | | ---------------- | ---------------------------------- | | process_list | List available processes/workflows | | process_get | Get process details by ID | | process_search | Semantic search across processes | | process_tests | Get test scenarios for a process | | process_create | Create a new process definition | | process_update | Update an existing process | | process_delete | Delete a process definition |

Note: Write operations (process_create, process_update, process_delete) require a JWT token with processes:write scope.

Session Management

| Tool | Description | | ---------------- | ----------------------------------- | | session_start | Start a new work session for a spec | | session_update | Update session notes | | session_end | End a work session |

Tool Examples

Create a Spec

{
  "tool": "spec_create",
  "arguments": {
    "type": "FEA",
    "title": "User Authentication",
    "content": "# Feature: User Authentication\n\n## Summary\n..."
  }
}

Search Specs

{
  "tool": "spec_search",
  "arguments": {
    "query": "authentication login",
    "type": "FEA",
    "limit": 5
  }
}

Create a Process

{
  "tool": "process_create",
  "arguments": {
    "name": "Spec Creation Workflow",
    "description": "Standard workflow for creating SDD specifications",
    "content": "# Spec Creation Workflow\n\n## Steps\n1. Analyze request...",
    "process_id": "spec-create",
    "domain": "spec-lifecycle"
  }
}

Start a Session

{
  "tool": "session_start",
  "arguments": {
    "spec_id": "uuid-or-spec-number",
    "notes": "Starting implementation of auth feature"
  }
}

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Run tests
npm test

# Type check
npm run type-check

Architecture

This MCP server follows the thin client pattern established in INV-202512024:

• No Business Logic: All validation, authorization, and workflow logic stays in Platform API
• Type Safety: Uses @ai_design_agency/sdd-core for shared types
• Bearer Token Auth: Token passed to Platform API in Authorization header
• Structured Errors: API errors translated to MCP-friendly format

Related Packages

• @ai_design_agency/sdd-core - Shared TypeScript types

Spec Reference

• Spec ID: FEA-202601002
• Parent Epic: EPC-202512003 (SDD Future State Design)

Built by AIDA