fluxloop-mcp 0.1.0

Fluxloop MCP server providing repository analysis and documentation tools.

Fluxloop MCP Server

Model Context Protocol server providing AI-assisted integration guidance for Fluxloop SDK.

This package exposes tools for documentation Q&A, repository analysis, framework detection, and integration planning. It helps developers integrate Fluxloop into their projects by analyzing code structure and recommending appropriate setup steps.

Requirements

• Python 3.11+
• macOS or Linux (Windows users can use WSL2)
• Git (for local development)

Features

Implemented (M0-M2)

• FAQ Tool: RAG-based documentation search with citations from indexed Fluxloop guides
• Repository Analysis: Scans languages, package managers, entry points, LOC, and risk flags
• Framework Detection: Identifies Express, FastAPI, Next.js, NestJS with confidence scoring
• Integration Steps: Generates framework-specific checklists with package manager awareness
• Edit Plan Proposal: Creates structured edit plans with anchors, payload, post-checks, and rollback
• Plan Validation: Verifies file existence, anchor patterns, and duplicate code detection
• End-to-End Workflow: analyze → detect → steps → plan → validate pipeline in one call

Indexing & Knowledge Base

• Document ingestion from docs/, packages/website/docs-{cli,sdk}, samples/
• Chunk-based storage (JSONL + SQLite metadata)
• BM25 + embedding hybrid retrieval (local FAISS or remote Qdrant)
• Recipe registry for framework-specific integration patterns

MCP Protocol

• stdio-based server with structured type: response/error format
• Handshake capability discovery
• Supports id-based request/response correlation

Installation

From Source (Development)

cd packages/mcp
pip install -e .

From PyPI (Planned)

pip install fluxloop-mcp

Quick Start

1. Install

pip install fluxloop-mcp

2. Build the Knowledge Index

# Default output: ~/.fluxloop/mcp/index/dev
packages/mcp/scripts/rebuild_index.sh

3. Test FAQ Query

python -m fluxloop_mcp.server --once --query "How to integrate FastAPI?"

4. Run as MCP Server (stdio)

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "fluxloop": {
      "command": "fluxloop-mcp",
      "args": [],
      "env": {
        "MCP_VECTOR_BACKEND": "faiss",
        "MCP_INDEX_MODE": "bundled"
      }
    }
  }
}

Restart Cursor/Claude Desktop. The MCP server will be available for queries.

5. Analyze a Repository

from fluxloop_mcp.tools import AnalyzeRepositoryTool, DetectFrameworksTool

profile = AnalyzeRepositoryTool().analyze({"root": "."})
print(profile)

frameworks = DetectFrameworksTool().detect({"repository_profile": profile})
print(frameworks)

6. Run Full Integration Workflow

from fluxloop_mcp.tools import RunIntegrationWorkflowTool

result = RunIntegrationWorkflowTool().run({"root": "."})
print(result.keys())  # profile, detection, integration_steps, edit_plan, validation

7. Local Development Environment

git clone https://github.com/chuckgu/fluxloop.git
cd fluxloop/packages/mcp
pip install -e ".[dev]"
pytest

Available Tools

Tool	Description
handshake	Returns server name, version, and capabilities
faq	Searches indexed documentation and returns answer + citations
analyze_repository	Scans project structure, languages, package managers, entry points
detect_frameworks	Identifies frameworks with confidence scores and recommended patterns
generate_integration_steps	Creates framework-specific integration checklist
propose_edit_plan	Generates structured edit plan with anchors and validation
validate_edit_plan	Verifies plan structure and checks file/anchor existence
run_integration_workflow	Executes full pipeline from analysis to validated plan

Configuration

Environment Variables

• MCP_VECTOR_BACKEND: faiss (default) | qdrant | none
• MCP_QDRANT_URL: Qdrant server URL (if using remote backend)
• MCP_QDRANT_API_KEY: Qdrant API key
• MCP_INDEX_MODE: bundled | download | remote
• MCP_INDEX_PATH: Custom index directory (default: ~/.fluxloop/mcp/index/dev)
• MCP_AUTO_UPDATE: true to allow automatic index download when newer releases are detected

Architecture

fluxloop_mcp/
├── server.py           # stdio MCP server entry point
├── tools/              # Tool implementations
│   ├── faq.py
│   ├── analyze_repository.py
│   ├── detect_frameworks.py
│   ├── generate_integration_steps.py
│   ├── propose_edit_plan.py
│   ├── validate_edit_plan.py
│   └── run_integration_workflow.py
├── index/              # Document indexing & retrieval
│   ├── ingestor.py
│   ├── store.py
│   ├── retriever.py
│   ├── embedder.py
│   └── validator.py
├── recipes/            # Framework integration recipes
│   └── registry.py
└── schemas/            # JSON schemas for validation
    ├── repository_profile.json
    ├── edit_plan.json
    └── runner_pattern_metadata.json

Roadmap

M3: Quality & Stabilization (Next)

• pytest test suite for all tools with golden fixtures
• CI integration for index validation
• Comprehensive MCP protocol documentation
• Structured logging and error code standardization
• Performance benchmarks and caching improvements

Future Enhancements

• Expand recipe coverage (Django, Flask, Svelte, etc.)
• AST-based code modification (beyond pattern matching)
• Streaming progress events for long-running workflows
• LLM-enhanced answer synthesis for FAQ
• Direct file editing with approval workflow
• Integration with VS Code extension for UI-based workflow

Release Checklist

When publishing to PyPI:

1. Bump the version in pyproject.toml and update this README if necessary.
2. Run the quality checks:

   pip install -e ".[dev]"
   pytest
   ruff check fluxloop_mcp
   mypy fluxloop_mcp
   

3. Verify index rebuild succeeds:

   scripts/rebuild_index.sh
   

4. Build distribution artifacts:

   scripts/build.sh
   

5. Upload to PyPI (optionally via TestPyPI first):

   twine upload --repository testpypi dist/*
   twine upload dist/*
   

6. Tag the release and push:

   git tag mcp-v0.1.0
   git push origin mcp-v0.1.0
   

Contributing

See CONTRIBUTING.md for development guidelines.

License

Apache 2.0 - See LICENSE