FlowLink MCP Server

The Missing Link for Claude Code - A minimalist MCP server that makes files tangible, trackable, and instantly accessible through clickable links directly in the Claude Code REPL.

🎯 Vision

FlowLink transforms Claude Code into the ultimate file-centric development environment. It makes files you work with visible, accessible, and manageable through intelligent tracking and rich link rendering.

✨ Features

Core Capabilities

• 🔗 Clickable File Links - Files appear as clickable links that open in VS Code or default apps
• 📊 Smart File Tracking - Automatically tracks files created, modified, or mentioned
• 🔍 Powerful Search - Search by name, path, tags, or content preview
• 👁️ Rich Previews - Intelligent file previews based on file type
• 📂 Project Awareness - Automatically detects and groups files by project
• 🏷️ Tagging System - Organize files with custom tags
• 📈 Statistics - Track file usage patterns and project activity

Science-Ready Features

• Data File Intelligence - Special handling for CSV, Excel, JSON files
• Reproducibility Tracking - Maintain file manifests for experiments
• Auto-Detection - Detects files mentioned in Claude's responses
• Batch Processing - Track multiple files at once

🚀 Installation

Prerequisites

• Node.js 16+
• npm or yarn
• Claude Code with MCP support

Install from npm

npm install -g flowlink-mcp

Configure Claude Code

Add to your ~/.claude/mcp_servers.json:

{
  "flowlink": {
    "command": "npx",
    "args": ["flowlink-mcp"],
    "env": {
      "FLOWLINK_DB": "~/.flowlink/flowlink.db",
      "FLOWLINK_AUTO_TRACK": "true",
      "FLOWLINK_PREVIEW_LENGTH": "500"
    }
  }
}

Install from Source

1. Clone the repository:

git clone https://github.com/james-m-jordan/flowlink-mcp.git
cd flowlink-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Configure Claude Code with local path:

{
  "flowlink": {
    "command": "node",
    "args": ["/absolute/path/to/flowlink-mcp/dist/index.js"],
    "env": {
      "FLOWLINK_DB": "~/.flowlink/flowlink.db",
      "FLOWLINK_AUTO_TRACK": "true",
      "FLOWLINK_PREVIEW_LENGTH": "500"
    }
  }
}

📖 Usage

Available Tools

track_file

Track a file in the FlowLink database.

Arguments:
- path (required): Path to the file to track
- project: Optional project name
- tags: Optional array of tags
- generatePreview: Whether to generate preview (default: true)

Example:
track_file path="/path/to/analysis.csv" tags=["qPCR", "experiment-23"]

list_recent

List recently accessed files.

Arguments:
- count: Number of files to return (default: 10)
- type: Filter by file type (e.g., "csv", "python")
- project: Filter by project name

Example:
list_recent count=5 type="python"

search_files

Search for files by name, path, or tags.

Arguments:
- query (required): Search query
- limit: Maximum results (default: 20)

Example:
search_files query="analysis" limit=10

open_file

Open a file in the default application or VS Code.

Arguments:
- path (required): Path to the file
- inVSCode: Open in VS Code (default: false)

Example:
open_file path="/path/to/script.py" inVSCode=true

preview_file

Generate a preview of a file's contents.

Arguments:
- path (required): Path to the file

Example:
preview_file path="/path/to/data.csv"

file_stats

Get statistics about tracked files.

No arguments required

Example:
file_stats

detect_files

Detect file paths mentioned in text.

Arguments:
- text (required): Text to search for file mentions
- autoTrack: Automatically track detected files (default: false)

Example:
detect_files text="Created analysis.csv and figures/plot.png" autoTrack=true

clean_old_files

Remove files older than specified days from tracking.

Arguments:
- daysOld: Remove files not accessed in this many days (default: 30)

Example:
clean_old_files daysOld=60

🎨 Link Format Examples

Scientific Data Files

📊 [analysis.csv](file:///path/to/analysis.csv) - 2.3KB · 5m ago · 📂 qPCR-study · 🏷️ experiment, raw-data
  > Headers: Sample, Ct_Value, Gene, Condition
  > Rows: 96 shown (of total file)
  > Sample data:
  >   Row 1: Control-1, 23.5, GAPDH...

Code Files

🐍 [analysis.py](vscode://file//path/to/analysis.py:1:1) - 4.2KB · 1h ago · 📂 data-pipeline
  > import pandas as pd
  > import numpy as np
  > 
  > def analyze_qpcr(data_file):
  >     """Analyze qPCR data with normalization"""

Project Grouping

### Recent Files (8)

#### 📂 experiment-2024

📊 [raw_data.csv](file:///path/to/raw_data.csv) - 15.3KB · just now
📈 [figure1.png](file:///path/to/figure1.png) - 234KB · 2m ago
🐍 [analysis.py](vscode://file//path/to/analysis.py:1:1) - 8.1KB · 5m ago

#### 📂 manuscript

📄 [methods.md](vscode://file//path/to/methods.md:1:1) - 12KB · 1h ago
📄 [results.md](vscode://file//path/to/results.md:1:1) - 18KB · 2h ago

⚙️ Configuration

Environment Variables

Create a .env file based on .env.example:

# Database path (optional, defaults to ~/.flowlink/flowlink.db)
FLOWLINK_DB=/custom/path/to/flowlink.db

# Auto-track files mentioned in Claude responses
FLOWLINK_AUTO_TRACK=true

# Preview settings
FLOWLINK_PREVIEW_LENGTH=500
FLOWLINK_PREVIEW_LINES=10

# Cleanup settings
FLOWLINK_CLEANUP_DAYS=30

🔬 Science Workflows

Experiment Tracking

# Claude: "I'll analyze your qPCR data"
# Creates: analysis_2024_01_15.csv
# FlowLink: 📊 Created: [analysis_2024_01_15.csv](file:///path/to/analysis_2024_01_15.csv) (2.3KB)

# Track with metadata
track_file path="analysis_2024_01_15.csv" project="qPCR-study" tags=["validated", "figure-3"]

Project Organization

# List all files from today's experiments
list_recent project="exp-2024-01-15" count=20

# Search for specific analysis
search_files query="normalized" project="exp-2024-01-15"

Reproducibility

# Get statistics for a project
file_stats

# Clean up old temporary files
clean_old_files daysOld=7

🏗️ Architecture

flowlink-mcp/
├── src/
│   ├── index.ts              # MCP server entry
│   ├── core/
│   │   ├── Database.ts        # SQLite persistence
│   │   ├── FileTracker.ts     # File tracking logic
│   │   ├── LinkRenderer.ts    # Rich link formatting
│   │   └── PreviewGenerator.ts # Intelligent previews
│   └── types/
│       └── index.ts           # TypeScript definitions
├── dist/                      # Compiled JavaScript
└── data/
    └── flowlink.db           # SQLite database

🧪 Development

Build from Source

npm run build     # Build TypeScript
npm run dev       # Watch mode
npm run test      # Run tests

Testing with Inspector

npx @modelcontextprotocol/inspector node dist/index.js

📊 Performance

• File tracking: <10ms
• Recent files query: <20ms
• Search operation: <50ms
• Link rendering: <5ms
• Memory usage: <50MB
• Database size: <10MB for 10,000 files

🔒 Security

• Path traversal prevention
• Sandboxed file access
• No arbitrary code execution
• Input sanitization
• Secure URL generation

🤝 Contributing

Contributions welcome! Please read our Contributing Guide first.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Built for the Claude Code community
• Inspired by the needs of scientific computing workflows
• Uses the Model Context Protocol SDK

🚦 Roadmap

Version 1.0 (Current)

• ✅ Core file tracking
• ✅ Rich link rendering
• ✅ Smart previews
• ✅ Project detection
• ✅ Search capabilities

Version 1.1 (Planned)

• [ ] File watching for changes
• [ ] Bulk operations
• [ ] Export capabilities
• [ ] Advanced filtering

Version 2.0 (Future)

• [ ] Cloud sync
• [ ] Team collaboration
• [ ] Version control integration
• [ ] Analytics dashboard

💬 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

FlowLink - Making files tangible in Claude Code 🔗