mcp-stream-workflow-status/API.md

Stream Workflow Status API

REST API for accessing stream workflow status and commit data.

Server Configuration

The API server is configured via environment variables:

API_ENABLED=true    # Enable/disable API server
API_PORT=3001       # Port to listen on (default: 3001)

Starting the Server

The API server starts automatically when the MCP server starts if API_ENABLED=true:

# Start the server
pnpm build
node dist/server.js

# Or for development
pnpm dev

Server will be available at: http://localhost:3001

Endpoints

GET /api/stats

Get quick dashboard statistics.

Response:

{
  "activeStreams": 3,
  "inProgress": 5,
  "blocked": 1,
  "readyToStart": 2,
  "completedToday": 4,
  "totalCommits": 142,
  "commitsToday": 8
}

Example:

curl http://localhost:3001/api/stats

---

GET /api/streams

List all streams with optional filters.

Query Parameters:

• status (optional): Filter by stream status
  • Values: initializing, active, blocked, paused, completed, archived
• category (optional): Filter by stream category
  • Values: frontend, backend, infrastructure, testing, documentation, refactoring
• priority (optional): Filter by priority
  • Values: critical, high, medium, low

Response:

{
  "streams": [
    {
      "id": "stream-0100",
      "streamNumber": "0100",
      "title": "Fix pre-existing build issues",
      "category": "infrastructure",
      "priority": "critical",
      "status": "active",
      "progress": 45,
      "currentPhase": 2,
      "worktreePath": "/path/to/worktree",
      "branch": "stream-0100-fix-issues",
      "createdAt": "2025-12-11T10:00:00Z",
      "updatedAt": "2025-12-11T12:30:00Z",
      "phases": ["Phase 1", "Phase 2", "Phase 3"]
    }
  ],
  "total": 1
}

Examples:

# Get all streams
curl http://localhost:3001/api/streams

# Get active streams only
curl http://localhost:3001/api/streams?status=active

# Get high priority backend streams
curl http://localhost:3001/api/streams?category=backend&priority=high

---

GET /api/streams/:id

Get a single stream by ID.

Path Parameters:

• id: Stream identifier (e.g., stream-0100)

Response:

{
  "id": "stream-0100",
  "streamNumber": "0100",
  "title": "Fix pre-existing build issues",
  "category": "infrastructure",
  "priority": "critical",
  "status": "active",
  "progress": 45,
  "currentPhase": 2,
  "worktreePath": "/path/to/worktree",
  "branch": "stream-0100-fix-issues",
  "createdAt": "2025-12-11T10:00:00Z",
  "updatedAt": "2025-12-11T12:30:00Z",
  "phases": ["Phase 1", "Phase 2", "Phase 3"]
}

Example:

curl http://localhost:3001/api/streams/stream-0100

---

GET /api/commits

Get recent commits with optional filtering.

Query Parameters:

• limit (optional): Maximum number of commits to return (default: 20)
• streamId (optional): Filter commits by stream ID

Response:

{
  "commits": [
    {
      "id": 1,
      "streamId": "stream-0100",
      "commitHash": "abc123def456",
      "message": "feat(api): Implement Express REST API server",
      "author": "Developer <dev@example.com>",
      "filesChanged": 8,
      "timestamp": "2025-12-11T12:30:00Z"
    }
  ],
  "total": 1
}

Examples:

# Get 20 most recent commits
curl http://localhost:3001/api/commits

# Get 5 most recent commits
curl http://localhost:3001/api/commits?limit=5

# Get commits for specific stream
curl http://localhost:3001/api/commits?streamId=stream-0100

# Get 10 commits for specific stream
curl http://localhost:3001/api/commits?streamId=stream-0100&limit=10

---

Error Responses

All endpoints return standard error responses on failure:

{
  "error": "Failed to fetch streams",
  "details": "Database connection failed"
}

HTTP Status Codes:

• 200 - Success
• 404 - Resource not found (streams/:id only)
• 500 - Server error

---

CORS

CORS is enabled for all origins in development. Configure appropriately for production.

---

Dashboard

The API server also serves the React dashboard as static files:

http://localhost:3001/

All non-API routes fall back to serving the dashboard SPA (Single Page Application).

---

Testing

Test the API using the provided test script:

./test-api.sh

Or manually with curl:

# Health check via stats
curl http://localhost:3001/api/stats | jq '.'

# List all streams
curl http://localhost:3001/api/streams | jq '.streams | length'

# Get recent commits
curl http://localhost:3001/api/commits?limit=10 | jq '.commits[0]'