FlowCheck MCP Server
Monitors Git repository state, providing real-time metrics, security scanning, and semantic search of commit history.
Uses OpenAI's API for smart intent verification, aligning code diffs with ticket descriptions.
Provides OpenTelemetry tracing for observability of MCP server operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@FlowCheck MCP Server check my branch for git hygiene and security issues"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
FlowCheck MCP Server
🛡️ Production-Grade Safety Layer for AI-First Development
Git hygiene monitoring + Security scanning + Semantic search + Full observability
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"| AgentAgent Rules (Recommended)
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 |
| Returns metrics + security_flags (PII/injection) |
| Returns actionable nudges + security warnings |
| Dynamically adjust thresholds |
v0.2 Smart Features (New)
Tool | Purpose |
| Semantic search - find commits by meaning |
| Smart Intent Verification - use "AI Judge" (BYOK LLM) to align diffs with tickets |
| 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:
Repo Config:
.flowcheck.json(in project root)Global Config:
~/.flowcheck/config.jsonDefaults
.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 conventionsAudit Logs: Append-only JSON Lines format in
~/.flowcheck/audit.logAll tool invocations are logged with trace IDs
Semantic Search
TF-IDF Vectorization: No external ML dependencies
SQLite Storage: Local index in
~/.flowcheck/semantic_index.dbFind commits by meaning, not just keywords
Installation & Deployment
Option 1: Docker (Recommended)
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 upFlowCheck 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-serverOption 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-serverDeployment
FlowCheck supports multiple deployment models:
Scenario | Time | Guide |
Local Development | 5 min | |
Production (Docker) | 10 min | |
Kubernetes | 30 min | |
CI/CD Integration | 15 min |
👉 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/flowcheckPhilosophy
FlowCheck embodies the principle that good Git hygiene enables good AI collaboration:
Smaller commits are easier for humans to review and audit
Frequent checkpoints prevent losing work during long sessions
Clean history makes it easier to understand what the AI changed
Non-blocking nudges preserve developer autonomy
License
MIT
Available Tools
9 toolsend_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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Security reviews for coding agents: diffs checked against your org policy and live infrastructure.
One searchable history across every AI coding tool, with secret scanning and a shared task board.
Checks AI-written code for leaked keys and made-up packages, on your machine. Never uploads code.
Deep security scans of repos you own from your editor: dependency CVEs, SAST, git-history secrets.
Related MCP Servers
- AlicenseBqualityDmaintenanceGives 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.1934 npmMIT
- AlicenseAqualityBmaintenanceEnforces team knowledge and workflow policies for AI coding agents by providing context, decisions, and gates before code changes are made.165Apache 2.0
- AlicenseNot gradedqualityCmaintenanceProvides cascading content protection for AI coding assistants by detecting and redacting PII, secrets, prompt injection, and system prompt leakage before they reach LLMs.MIT
- AlicenseBqualityDmaintenanceUniversal AI security layer for code scanning, PII detection, prompt injection defense, secret detection, dependency auditing, and audit logging.2720 PyPI3Apache 2.0