1.1.7 • Published 5d agoCLI

@epicdm/flowstate-mcp

Licence

Apache-2.0

Version

1.1.7

Deps

Size

6.6 MB

Vulns

Weekly

Summary Dependency Versions

FlowState MCP Server

Model Context Protocol (MCP) server for Epic FlowState with dynamic collection support and TODO scanner integration.

Features

Dynamic Collection Operations - Full CRUD operations for all RxDB collections
TODO Scanner - Bidirectional sync between code comments and FlowState tasks
Spec Management - Create and manage specifications with milestone workflows
Workspace & Codebase Management - Organize projects and code repositories
Approval Workflows - Document and action approval management
Observability Integration (Optional) - Monitor errors, logs, and sessions with AI-enhanced analysis

Installation

The easiest way to use FlowState MCP is directly from npm using npx:

Quick Setup (Recommended)

Add to your MCP client configuration (e.g., Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "flowstate": {
      "command": "npx",
      "args": ["-y", "@epicdm/flowstate-mcp"],
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "RXDB_SERVER_URL": "http://localhost:7080",
        "RXDB_AUTH_TOKEN": "your-auth-token",
        "RXDB_DOMAIN_ID": "your-domain-id",
        "USER_ID": "your-user-id",
        "ORG_ID": "your-org-id"
      }
    }
  }
}

The -y flag automatically accepts the npx prompt, and the package will always use the latest published version.

Alternative: Global Installation

If you prefer to install globally:

npm install -g @epicdm/flowstate-mcp

Then configure your MCP client:

{
  "mcpServers": {
    "flowstate": {
      "command": "flowstate-mcp",
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "RXDB_SERVER_URL": "http://localhost:7080",
        "RXDB_AUTH_TOKEN": "your-auth-token",
        "RXDB_DOMAIN_ID": "your-domain-id"
      }
    }
  }
}

Using .env File

The MCP server automatically loads environment variables from a .env file in your project root.

1. Create or update your project's .env file:

# Project root .env file
RXDB_SERVER_URL=http://localhost:7080
RXDB_AUTH_TOKEN=dev-token
RXDB_DOMAIN_ID=epic-flow-dev
USER_ID=your-user-id
ORG_ID=your-org-id

2. Simplified MCP client configuration:

{
  "mcpServers": {
    "flowstate": {
      "command": "npx",
      "args": ["-y", "@epicdm/flowstate-mcp"],
      "env": {
        "PROJECT_PATH": "/path/to/your/project"
      }
    }
  }
}

Note: The MCP server will automatically load all configuration from the .env file in PROJECT_PATH. You only need to specify PROJECT_PATH in the MCP client config.

Environment Variables

Variable	Description	Required	Default
`PROJECT_PATH`	Path to your project root	Yes	`cwd()`
`RXDB_SERVER_URL`	RxDB server URL	Yes	-
`RXDB_AUTH_TOKEN` or `AUTH_TOKEN`	Authentication token	Yes	-
`RXDB_DOMAIN_ID` or `DOMAIN_ID`	Domain identifier	Yes	-
`USER_ID`	User identifier	No	-
`ORG_ID`	Organization identifier	No	-
`OBS_SERVER_URL`	Observability server URL	No	-
`OBS_API_KEY`	Observability API key	No	-

Variable Loading Priority (highest to lowest):

MCP client configuration
Project .env file (auto-loaded from PROJECT_PATH)
System environment variables

Available Tools

Collection Operations

See CRUD Tools Documentation for complete details on:

collection-list-available - List all available collections
collection-get-info - Get schema information for a collection
collection-create - Create a new document
collection-get - Get a document by ID
collection-update - Update a document
collection-delete - Delete a document
collection-query - Query documents with selectors
collection-list - List documents with minimal fields (id, title, name) for token efficiency

Token-Optimized List Operations

The collection-list tool is optimized for minimal token usage:

Projection: Returns only id, title, and name fields
Default limit: 20 items per request
Max limit: 20 items (enforced)
Pagination: Use offset parameter with nextOffset from response meta

Example with pagination:

// First page
{ "tool": "collection-list", "params": { "collection": "tasks" } }
// Response includes: { meta: { limit: 20, offset: 0, hasMore: true, nextOffset: 20, total: 100 } }

// Next page
{ "tool": "collection-list", "params": { "collection": "tasks", "offset": 20 } }

Environment variable overrides:

MCP_LIST_DEFAULT_LIMIT - Default items per request (default: 20, hard cap: 100)
MCP_LIST_MAX_LIMIT - Maximum allowed limit (default: 20, hard cap: 100)

Note: When MCP_LIST_DEFAULT_LIMIT exceeds MCP_LIST_MAX_LIMIT, the default is automatically clamped to the max limit.

TODO Scanner Tool

Tool: scan_todos_in_project

Scan project for TODO comments and sync with FlowState tasks.

Parameters:

dryRun (boolean): Preview changes without modifying files
summaryOnly (boolean): Generate summary without syncing
filePath (string): Scan specific file only

Example:

{
  "tool": "scan_todos_in_project",
  "params": {
    "dryRun": false
  }
}

Spec Management

spec-create - Create new specification with milestone structure
spec-status - Get specification status and progress
spec-list - List all specifications
spec-execute-task - Execute or queue a task
spec-workflow-guide - Get workflow guide
spec-update-phase - Update phase document content
spec-get-phase - Get phase document content
spec-create-tasks - Create tasks from markdown list
spec-get-tasks - Get all tasks for a spec
spec-start-task - Start a task
spec-stop-task - Stop a task
spec-update-task - Update task fields

Workspace Management

workspace-create - Create a new workspace
workspace-list - List workspaces with filters
workspace-get - Get workspace details
workspace-update - Update workspace fields
workspace-archive - Archive a workspace

Codebase Management

codebase-create - Create a new codebase with Git config
codebase-list - List codebases with filters
codebase-get - Get codebase details
codebase-update - Update codebase configuration
codebase-archive - Archive a codebase
codebase-validate - Validate codebase configuration

Approval Workflows

approvals - Manage approval workflow (request, status, delete)

Observability Tools (Optional)

16 additional tools available when OBS_SERVER_URL and OBS_API_KEY are configured:

Error Management

obs__errors-list - Query errors with filters (level, time range, session)
obs__errors-stats - Get error statistics with aggregation options
obs__error-get - Get detailed error with stack trace and source map

Example Usage:

// List fatal errors from last 24 hours
{
  "tool": "obs__errors-list",
  "params": {
    "projectId": "proj_123",
    "level": "fatal",
    "timeRange": "24h",
    "limit": 50
  }
}

// Get error statistics by platform
{
  "tool": "obs__errors-stats",
  "params": {
    "projectId": "proj_123",
    "timeRange": "7d",
    "groupBy": "platform"
  }
}

Log Management

obs__logs-list - Query logs with filters (level, text search, session)
obs__logs-search - Advanced log search with query syntax
obs__log-get - Get detailed log event with context

Example Usage:

// Search logs for database errors
{
  "tool": "obs__logs-search",
  "params": {
    "projectId": "proj_123",
    "query": "database AND (timeout OR connection)",
    "level": "error",
    "limit": 100
  }
}

Session Management

obs__sessions-list - List user sessions with filters
obs__sessions-get - Get session details with environment
obs__sessions-breadcrumbs - Get session breadcrumbs timeline

Example Usage:

// Get session breadcrumbs for debugging
{
  "tool": "obs__sessions-breadcrumbs",
  "params": {
    "sessionId": "sess_abc123"
  }
}
// Returns: Navigation trail, user actions, network events

Project Management

obs__projects-list - List all observability projects
obs__projects-get - Get project details and statistics
obs__projects-create - Create new observability project

Example Usage:

// Create new project for application monitoring
{
  "tool": "obs__projects-create",
  "params": {
    "name": "my-web-app",
    "description": "Production monitoring for web application",
    "metadata": {
      "environment": "production",
      "platform": "web"
    }
  }
}
// Returns: Project ID and API key for SDK initialization

AI-Enhanced Analysis

obs__debug-error - AI-powered error analysis with pattern detection
obs__compare-errors - Compare multiple errors to find common patterns
obs__suggest-fixes - Get AI-generated fix suggestions for errors
obs__create-task-from-error - Create FlowState task from error

Example Usage:

// Debug error with AI analysis
{
  "tool": "obs__debug-error",
  "params": {
    "errorId": "error_xyz789"
  }
}
// Returns:
// - Error pattern classification (9 types)
// - Severity assessment
// - Root cause analysis
// - 3-5 suggested fixes with code examples
// - Related session context

// Create task from error
{
  "tool": "obs__create-task-from-error",
  "params": {
    "errorId": "error_xyz789",
    "projectId": "proj_123"
  }
}
// Returns: Task ID with embedded error context and fix suggestions

Supported Error Patterns:

null_reference - Null/undefined property access
type_error - Type mismatches and coercion issues
network_error - Failed API calls and network requests
async_error - Promise rejections and async/await issues
state_error - Invalid state transitions
validation_error - Data validation failures
resource_error - Missing resources (files, modules, APIs)
timeout_error - Operation timeouts
unknown - Unclassified errors

See OBSERVABILITY_INTEGRATION.md for detailed configuration and usage.

Development

# Install dependencies
yarn install

# Build
yarn build

# Run tests
yarn test

# Watch mode for development
yarn build --watch

Architecture

The MCP server provides a bridge between Claude/AI assistants and the FlowState ecosystem:

MCP Client (Claude/Cursor)
    ↓
MCP Server (flowstate-mcp)
    ↓
RxDB Client (@epic-flow/flowstate-rxdb-client)
    ↓
FlowState Database

Documentation

CRUD Tools Documentation - Complete guide to collection operations
Observability Integration - Optional observability tools setup and usage

License

MIT