ChurnFlow

ChurnFlow MCP Server enables you to run a microservice that processes capture and action items with AI assistance, while offering optional SQLite-backed features. It integrates with your preferred MCP client to capture, route, and manage tasks across domains with minimal friction and strong recovery from interruptions.

How to use

Start by launching the MCP server from your development environment and connect an MCP client (such as GitHub Copilot or another compatible assistant). You will capture ideas, create trackers, and let AI assist with routing, prioritization, and context switching. Use natural language prompts to add items like "Need to call parts supplier about carburetor for John Deere restoration" and let the system route them to the right tracker. You can query the system for status, list available trackers, or request a status update on ongoing work. The server supports both a local file-based workflow and optional database-backed features to enable full-text search, analytics, and AI learning patterns.

How to install

Prerequisites: you need Node.js 18 or newer, a compatible AI assistant such as GitHub Copilot, and an OpenAI API key for AI inference. You should also have an existing Churn system directory structure to house collections and trackers.

Install and set up the MCP server locally with these steps.

# Clone the repository
git clone https://github.com/jgsteeler/churnflow-mcp.git
cd churn-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Setup database (optional - enables advanced features)
npm run db:setup

Configuration and running

Configure the MCP client integration and AI settings to tailor how items are captured and routed. A sample configuration file is provided to define where your collections and trackers live, which AI provider to use, and the API key for AI inference.

{
  "collectionsPath": "/path/to/your/Collections",
  "trackingPath": "/path/to/your/tracking", 
  "crossrefPath": "/path/to/crossref.json",
  "aiProvider": "openai",
  "aiApiKey": "YOUR_OPENAI_API_KEY",
  "confidenceThreshold": 0.7
}

Starting the MCP server

After configuring, start the MCP server and connect it to your MCP client. The server exposes an npm script that runs the server in MCP mode.

npm run mcp

Using with GitHub Copilot

If you are using GitHub Copilot, configure the MCP server so Copilot can access the churn flow tools and trackers. You will use Copilot to capture items, check status, and list trackers.

{
  "mcpServers": {
    "churnflow": {
      "command": "tsx",
      "args": ["/path/to/churn-mcp/src/index.ts"],
      "cwd": "/path/to/churn-mcp"
    }
  }
}

Database features (optional)

Database support is optional and unlocks full-text search, analytics, and AI-driven learning. You can still operate in a file-only mode if you do not enable the database.

# Setup database (one-time)
npm run db:setup

# Reset database (development)
npm run db:reset

# View database (browser)
npm run db:studio

CLI usage (alternative)

If you prefer a direct command-line approach, you can capture items and query system status from the CLI.

# Direct capture via CLI
npm run cli capture "Complex task with multiple components"

# Check system status
npm run cli status

Available tools

capture

Capture new items with AI-assisted routing and context inference

status

Query the current status of trackers and items

list_trackers

List all available trackers and their metadata