Skip to main content
Glama
FlowCheck MCP Server

FlowCheck MCP Server

by backslash-ux

FlowCheck MCP Server

🛡️ Production-Grade Safety Layer for AI-First Development

Git hygiene monitoring + Security scanning + Semantic search + Full observability

License: MIT Python 3.10+ MCP Compatible


Why FlowCheck?

AI coding assistants are incredibly productive—but they can also create massive, hard-to-review changesets and security risks. FlowCheck is a production-grade safety layer that:

  • 🔍 Monitors Git state in real-time during AI-assisted coding

  • 🔒 Scans for security issues (PII, secrets, prompt injection attacks)

  • 🔎 Semantic history search - find commits by meaning, not keywords

  • 📊 Tracks flow health (time, lines, branch age, drift from main)

  • 📝 Full observability (OpenTelemetry traces, audit logs)

  • 🎯 Intent validation (ticket-to-diff alignment)

  • 🤖 Designed for AI agents with enforceable rules

Think of FlowCheck as a "smart fitness watch with a biometric lock" for your codebase—it helps you code faster while actively defending against security threats.

Related MCP server: Hivelore

AI-First Design

FlowCheck is built specifically for the agentic coding workflow:

flowchart LR
    Agent["🤖 AI Agent<br/>(Claude, Cursor, etc)"]
    FC["🛡️ FlowCheck<br/>MCP Server"]
    Git["📁 Git Repo<br/>(.git)"]

    Agent -->|"get_flow_state()"| FC
    FC -->|"analyze"| Git
    Git -->|"metrics"| FC
    FC -->|"status: warning<br/>security_flags: [...]"| Agent

    Agent -->|"⏸️ Pause & suggest<br/>checkpoint commit"| Agent

Copy rules/flowcheck-rules.md to your AI tool's rules directory:

# For Cursor
cp rules/flowcheck-rules.md .cursor/rules/

# For Claude Projects
cp rules/flowcheck-rules.md .claude/rules/

# For other tools
cp rules/flowcheck-rules.md .agent/rules/

This instructs AI agents to automatically check Git hygiene before starting tasks and to pause when thresholds are exceeded.

Quick Start

Installation

git clone https://github.com/backslash-ux/flowcheck.git
cd flowcheck

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Claude Desktop Integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "flowcheck": {
      "command": "/path/to/flowcheck/.venv/bin/python",
      "args": ["-m", "flowcheck.server"],
      "env": {
        "PYTHONPATH": "/path/to/flowcheck/src"
      }
    }
  }
}

MCP Tools

Core Tools

Tool

Purpose

get_flow_state

Returns metrics + security_flags (PII/injection)

get_recommendations

Returns actionable nudges + security warnings

set_rules

Dynamically adjust thresholds

v0.2 Smart Features (New)

Tool

Purpose

search_history

Semantic search - find commits by meaning

verify_intent

Smart Intent Verification - use "AI Judge" (BYOK LLM) to align diffs with tickets

sanitize_content

PII/secret redaction before sharing with AI

Example: verify_intent (Smart Mode)

{
  "alignment_score": 0.4,
  "is_aligned": false,
  "ticket_id": "42",
  "scope_creep_warnings": ["Scope Creep Detected by AI Judge"],
  "reasoning": "The ticket asks for a bug fix in auth, but the diff contains a full refactor of the billing module."
}

Configuration

FlowCheck supports hierarchical configuration:

  1. Repo Config: .flowcheck.json (in project root)

  2. Global Config: ~/.flowcheck/config.json

  3. Defaults

.flowcheck.json Example

{
  "max_minutes_without_commit": 45,
  "intent": {
    "provider": "openai",
    "model": "gpt-4o",
    "api_key_env": "OPENAI_API_KEY"
  }
}

Ignoring Files (.flowcheckignore)

Create a .flowcheckignore file in your repo root to exclude files from analysis (uses gitignore syntax):

tests/fixtures/
*.min.js
legacy/

Security Features

Guardian Layer

  • PII Detection: Emails, phone numbers, SSNs, credit cards

  • Secret Scanning: AWS keys, GitHub tokens, API keys, passwords

  • Injection Filtering: Detects prompt injection attacks in diffs

Observability

  • OpenTelemetry Traces: gen_ai.* semantic conventions

  • Audit Logs: Append-only JSON Lines format in ~/.flowcheck/audit.log

  • All tool invocations are logged with trace IDs

  • TF-IDF Vectorization: No external ML dependencies

  • SQLite Storage: Local index in ~/.flowcheck/semantic_index.db

  • Find commits by meaning, not just keywords

Installation & Deployment

Get FlowCheck running in 30 seconds:

# Clone and setup
git clone https://github.com/backslash-ux/flowcheck.git
cd flowcheck

# Configure environment
cp .env.example .env
nano .env  # Add your API keys

# Start the stack
docker-compose up

FlowCheck is now running at http://localhost:8000

See Docker Deployment Guide for:

  • Local development setup

  • Production deployment

  • Image variants (production/slim/dev)

  • Troubleshooting

Option 2: Python Package

pip install git+https://github.com/backslash-ux/flowcheck.git

# Set environment variables
export ANTHROPIC_API_KEY=sk-ant-xxxxx

# Start server
flowcheck-server

Option 3: From Source

git clone https://github.com/backslash-ux/flowcheck.git
cd flowcheck

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/

# Start server
flowcheck-server

Deployment

FlowCheck supports multiple deployment models:

Scenario

Time

Guide

Local Development

5 min

Docker

Production (Docker)

10 min

Docker.md

Kubernetes

30 min

Kubernetes.md

CI/CD Integration

15 min

CI-CD.md

👉 Deployment Guide for full options

Development

# Setup development environment
docker-compose -f docker-compose.dev.yml up

# Or use Python venv
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src/flowcheck

Philosophy

FlowCheck embodies the principle that good Git hygiene enables good AI collaboration:

  1. Smaller commits are easier for humans to review and audit

  2. Frequent checkpoints prevent losing work during long sessions

  3. Clean history makes it easier to understand what the AI changed

  4. Non-blocking nudges preserve developer autonomy

License

MIT

Available Tools

9 tools
end_sessionA

End the current FlowCheck session.

Call this at the end of a task to finalize audit records.

Returns: Dictionary with final session statistics.

Inputs: no named parameters. Returns: object

get_flow_stateA

Get current flow state metrics with security scanning.

Returns metrics about repository health including:

  • minutes_since_last_commit: Time elapsed since last commit

  • uncommitted_lines: Total lines changed

  • uncommitted_files: Number of modified files

  • branch_name: Current Git branch

  • status: Health indicator (ok, warning, danger)

  • security_flags: Any detected security issues

Inputs: repo_path (required). Returns: object

get_recommendationsA

Get actionable recommendations with security awareness.

Analyzes repository and returns suggestions based on:

  • Commit frequency and change size thresholds

  • Branch age and main-branch synchronization

  • Security scan results

Inputs: repo_path (required). Returns: object

get_session_infoA

Get information about the current session.

Returns session statistics including:

  • session_id: Unique session identifier

  • tool_calls: Number of tool calls in this session

  • duration_seconds: Session duration

Returns: Dictionary with session information.

Inputs: no named parameters. Returns: object

sanitize_contentA

Sanitize content by redacting secrets and PII.

Use this before including file contents in prompts or outputs. Replaces sensitive data with [REDACTED_TYPE] tokens.

Inputs: content (required). Returns: object

search_historyA

Search commit history semantically.

Find commits by meaning rather than exact keyword matching. Example: "authentication changes" finds commits about OAuth, login, tokens.

Inputs: query (required), repo_path (required), top_k. Returns: object

set_rulesB

Update FlowCheck configuration thresholds.

Supported parameters:

  • max_minutes_without_commit: Minutes before suggesting checkpoint (default: 60)

  • max_lines_uncommitted: Lines before suggesting split (default: 500)

Inputs: config (required). Returns: object

start_sessionA

Start a new FlowCheck session for audit correlation.

Sessions help correlate tool calls across a task for auditing. Call this at the beginning of a task.

Inputs: agent_id. Returns: object

verify_intentA

Validate current work against ticket requirements.

Checks if code changes align with the stated ticket/task. Flags scope creep using GitHub Issues integration.

Inputs: repo_path (required), ticket_id (required), context. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 9 tools

    Disambiguation5/5

    All nine tools target distinct actions: session lifecycle (start/end), state retrieval, recommendations, history search, content sanitization, configuration, and intent verification. Even related tools like get_flow_state and get_recommendations are clearly differentiated by their outputs and purposes.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case (e.g., start_session, get_flow_state, sanitize_content). No mixing of naming conventions or vague verbs are present.

    Tool Count5/5

    Nine tools is an appropriate number for the server's purpose of managing flow sessions, scanning, and recommendations. Each tool serves a well-defined role without redundancy or excessive granularity.

    Completeness4/5

    The tool set covers the essential workflows: session management, state metrics, recommendations, history search, content sanitization, configuration, and intent verification. A minor gap is the lack of a tool to list or manage past sessions, but the core functionality is well-covered.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Gives AI coding assistants persistent memory, safety controls, and project awareness by tracking coding sessions, protecting critical files from modifications, and managing approval workflows with automatic changelog generation.
      19
      34 npm
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Universal AI security layer for code scanning, PII detection, prompt injection defense, secret detection, dependency auditing, and audit logging.
      27
      20 PyPI
      3
      Apache 2.0