SDLC Assist MCP Server

An MCP (Model Context Protocol) server that gives AI assistants read access to your SDLC Assist project artifacts stored in Supabase.

What This Does

When connected to Claude Desktop or Claude Code, this server lets you have conversations about your SDLC projects:

"What projects do I have?"
"Show me the data model for the DEP Multi-Tenant project"
"What API endpoints handle authentication?"
"List all the screens for the HCP Portal"
"What tech stack did we choose?"

The AI reads your project data directly from Supabase — PRDs, architecture docs, data models, API contracts, screen inventories, and more. It can also generate IT cost estimations by calling Vertex AI Gemini directly with project context.

How MCP Works (Quick Primer)

You (in Claude Desktop)
  │  "What does the data model look like for DEP Multi-Tenant?"
  │
  ▼
Claude (the AI)
  │  Thinks: "I need the data model artifact for that project"
  │  Calls: sdlc_get_artifact(project_id="dc744778...", artifact_type="data_model")
  │
  ▼
This MCP Server
  │  Queries Supabase for the data_model_content column
  │  Returns the full markdown document
  │
  ▼
Claude (the AI)
  │  Reads the data model, answers your question
  ▼
You see the answer

MCP is just a protocol — a standardized way for AI to call functions. This server exposes 6 tools that the AI can call when it needs project data.

Available Tools

| Tool | What it does | |------|-------------| | sdlc_list_projects | Lists all projects with completion status | | sdlc_get_project_summary | Detailed overview of one project (artifacts, screens, files) | | sdlc_get_artifact | Fetches any artifact: PRD, architecture, data model, API contract, sequence diagrams, implementation plan, CLAUDE.md, or corporate guidelines | | sdlc_get_screens | Lists UI screens with metadata, optionally includes HTML prototypes | | sdlc_get_tech_preferences | Returns the tech stack choices for a project | | sdlc_generate_estimation | Generates Traditional vs AI-Assisted IT cost estimates by calling Vertex AI Gemini directly with project context. Requires all upstream artifacts (PRD, architecture, data model, API contract, implementation plan) to be generated first. |

Architecture

┌─────────────────────────────────────┐
│         MCP Client (Claude)         │
└──────────────┬──────────────────────┘
               │ MCP Protocol
               ▼
┌─────────────────────────────────────┐
│       sdlc-assist-mcp Server        │
│  (FastMCP · streamable-http/stdio)  │
├──────────────┬──────────────────────┤
│  Read Tools  │  Gemini Tools        │
│  (1-5)       │  (6)                 │
└──────┬───────┴──────────┬───────────┘
       │                  │
       ▼                  ▼
┌──────────────┐  ┌───────────────────┐
│   Supabase   │  │  Vertex AI Gemini │
│  PostgREST   │  │  (generateContent │
│  (httpx)     │  │   via REST API)   │
└──────────────┘  └───────────────────┘

Prerequisites

Python 3.10+
uv (recommended) or pip
A Supabase project with the SDLC Assist schema
Claude Desktop or Claude Code
(For estimation tool) Google Cloud project with Vertex AI Gemini API enabled

Setup

1. Clone and install

git clone https://github.com/ramseychad1/sdlc-assist-mcp.git
cd sdlc-assist-mcp

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .

2. Configure environment

cp .env.example .env

Edit .env with your credentials: ```

Required — Supabase

SUPABASE_URL=https://mtzcookrjzewywyirhja.supabase.co SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here

Optional — Vertex AI Gemini (only needed for sdlc_generate_estimation)

VERTEXAI_PROJECT_ID=sdlc-assist VERTEXAI_LOCATION=us-central1 ```

Find your Supabase service role key in: Supabase Dashboard → Settings → API → service_role (secret)

3. Test it works

# Quick syntax check
python -c "from sdlc_assist_mcp.server import mcp; print('Server loads OK')"

4. Connect to Claude Desktop

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this to the mcpServers section:

{
  "mcpServers": {
    "sdlc-assist": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/ABSOLUTE/PATH/TO/sdlc-assist-mcp",
        "sdlc-assist-mcp"
      ]
    }
  }
}

Or if using pip instead of uv:

{
  "mcpServers": {
    "sdlc-assist": {
      "command": "/ABSOLUTE/PATH/TO/sdlc-assist-mcp/.venv/bin/sdlc-assist-mcp"
    }
  }
}

Restart Claude Desktop. You should see the SDLC Assist tools in the tools menu.

5. Connect to Claude Code (Antigravity IDE)

claude mcp add sdlc-assist -- uv run --directory /ABSOLUTE/PATH/TO/sdlc-assist-mcp sdlc-assist-mcp

Project Structure

sdlc-assist-mcp/
├── pyproject.toml                          # Dependencies + entry point
├── Dockerfile                              # Cloud Run container image
├── deploy.sh                               # GCP deployment script
├── .env.example                            # Environment template
├── .gitignore
├── README.md
├── src/
│   └── sdlc_assist_mcp/
│       ├── __init__.py
│       ├── server.py                       # MCP server + all 6 tool definitions
│       ├── supabase_client.py              # Async Supabase REST client (httpx)
│       ├── vertex_client.py                # Async Vertex AI Gemini client (REST API)
│       └── models/
│           ├── __init__.py
│           └── inputs.py                   # Pydantic input models for tools
└── tests/
    └── (coming soon)

Deployment

The server supports two transports:

stdio (default) — For local use with Claude Desktop / Claude Code
streamable-http — For remote deployment on Cloud Run

Deploy to Cloud Run

./deploy.sh

This builds the container with Cloud Build, stores Supabase credentials in Secret Manager, and deploys to Cloud Run. See deploy.sh for full details.

Environment Variables (Cloud Run)

| Variable | Required | Description | |----------|----------|-------------| | SUPABASE_URL | Yes | Supabase project URL | | SUPABASE_SERVICE_ROLE_KEY | Yes | Supabase service role key (stored in Secret Manager) | | VERTEXAI_PROJECT_ID | For estimation tool | GCP project name (defaults to sdlc-assist) | | VERTEXAI_LOCATION | For estimation tool | GCP region (defaults to us-central1) |

Future Enhancements

Write tools — Update PRDs, add screens, modify artifacts
More Gemini-powered tools — Route additional generative tasks through Vertex AI Gemini
Search across artifacts — Find mentions of a term across all project documents
Project creation — Start new projects from the chat interface

sdlc-assist-mcp