Skip to content

Pedroshakoor/Devflow

BranchesTags

Repository files navigation

🔧 DevFlow MCP

Your AI senior dev teammate — orchestrate intelligent multi-step development workflows with persistent memory, safety, and stack intelligence.

License: MIT MCP TypeScript

✨ What is DevFlow MCP?

DevFlow MCP is an open-source Model Context Protocol server that transforms AI coding agents (Claude, Cursor, VS Code Copilot) into a proactive senior dev teammate.

Instead of one-shot code generation, DevFlow gives your AI agent:

  • 🧠 Persistent project memory — decisions, tech debt, architecture notes survive across sessions
  • ⚡ Multi-step workflow orchestration — safely chain schema → migration → API → tests → docs
  • 🛡️ Safety-first execution — sandboxed commands, approval gates, audit logs, rollback support
  • 📚 Stack intelligence — pre-built templates for Next.js TypeScript, FastAPI/Python, Express
  • 🔬 Dry-run mode — preview any workflow before committing to real changes
  • 🌿 Git-aware — auto-generates commit messages, branch management, diff review

🚀 Quick Start

npm (recommended)

# Install globally
npm install -g devflow-mcp

# Or use npx
npx devflow-mcp

From Source

git clone https://github.com/your-org/devflow-mcp
cd devflow-mcp
npm install
npm run build
npm start

Prerequisites: Node.js 18+, and Python/build tools for better-sqlite3 native compilation. On macOS: xcode-select --install. On Ubuntu: sudo apt-get install python3 make g++. On Windows: npm install --global windows-build-tools.

Docker

# Build from source
git clone https://github.com/your-org/devflow-mcp
cd devflow-mcp
docker-compose up

Note: A pre-built Docker image will be published to GitHub Container Registry once CI/CD is set up. Until then, build from source using the steps above.

🔌 Connecting to AI Clients

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "devflow": {
      "command": "npx",
      "args": ["devflow-mcp"],
      "env": {
        "DEVFLOW_PROJECT_NAME": "my-app",
        "DEVFLOW_STACK": "nextjs-ts"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "devflow": {
      "command": "node",
      "args": ["./node_modules/.bin/devflow-mcp"],
      "env": {
        "DEVFLOW_STACK": "nextjs-ts"
      }
    }
  }
}

VS Code (with MCP extension)

{
  "mcp.servers": {
    "devflow": {
      "command": "npx devflow-mcp",
      "transport": "stdio"
    }
  }
}

💡 Usage Examples

Initialize a project

You: Initialize DevFlow for my Next.js app called "shopify-clone"
AI: [calls initializeProject] ✅ DevFlow initialized! Stack: nextjs-ts auto-detected...

Implement a feature with a workflow

You: Implement user authentication using the nextjs-ts template
AI: [calls startWorkflow with template: {stack: "nextjs-ts", feature: "auth"}]
    ⏳ Workflow created with 5 steps. First step: Install next-auth...
    
You: Execute the first step
AI: [calls executeStep] ✅ Step completed: npm install next-auth...
    👋 Next step requires approval: Write auth.ts config
    
You: Looks good, approve it
AI: [calls approveStep] ✅ Approved. Running next step...

Store and recall decisions

You: Remember that we decided to use Zustand over Redux for state management because the app is small
AI: [calls addMemory, type: "decision"] 🏛️ Memory stored!

You: What state management approach did we decide on?
AI: [calls queryMemory] Found: "Decided to use Zustand over Redux..."

Dry-run a workflow

You: Show me what would happen if we set up the FastAPI auth endpoint, but don't actually do it
AI: [calls startWorkflow with dryRun: true] 🔬 [DRY RUN] Workflow preview...

Simulate CI locally

You: Run the full CI pipeline locally before I push
AI: [calls ciSimulate] ✅ TypeScript check passed | ✅ Tests passed | ✅ Build passed

🛠️ Available Tools

Tool Description
initializeProject Set up DevFlow for a project
getProjectContext View current project state
indexRepo Index codebase for smart search
addMemory Store knowledge (decisions, debt, bugs)
queryMemory Full-text search memories
listMemories Browse stored knowledge
deleteMemory Remove stale memories
startWorkflow Create multi-step workflow
executeStep Run next workflow step
approveStep Approve a pending step
skipStep Skip a workflow step
getWorkflowStatus Check workflow progress
listWorkflows View all workflows
listTemplates Browse stack templates
previewTemplate Preview template steps
gitStatus Git working tree status
gitDiff Show file diffs
gitCommit Commit with AI message
gitLog Recent commit history
gitBranch Create & checkout branches
runCommand Safe sandboxed execution
runTests Run test suite (auto-detected)
readFile Safe file reading
writeFile Safe file writing
updateConfig Update DevFlow settings
ciSimulate Local CI/CD simulation
getAuditLog View action history

📚 Stack Templates

Next.js TypeScript (nextjs-ts)

Full-stack Next.js 14 App Router with Tailwind CSS and shadcn/ui.

Features: auth api-routes ui-component page middleware

FastAPI Python (fastapi-python)

Production FastAPI with Pydantic v2, SQLAlchemy 2.0, Alembic migrations.

Features: auth endpoint model migration test

Express TypeScript (express-ts)

Type-safe Express API with Prisma ORM and Zod validation.

Features: route middleware model

⚙️ Configuration

Create .devflow/config.json or use environment variables:

{
  "projectName": "my-app",
  "stack": "nextjs-ts",
  "rootDir": "/path/to/project",
  "packageManager": "pnpm",
  "approvalRequired": true,
  "sandboxEnabled": true,
  "blockedPaths": ["node_modules", ".git", "dist"],
  "logLevel": "info"
}

Environment variables:

Variable Default Description
DEVFLOW_PROJECT_NAME my-project Project name
DEVFLOW_STACK generic Stack type
DEVFLOW_ROOT_DIR cwd Project root path
LOG_LEVEL info Logging level
DEVFLOW_DEBUG 0 Verbose debug mode

🏗️ Architecture

devflow-mcp/
├── src/
│   ├── index.ts          # MCP server entry + tool registration
│   ├── config.ts         # Config loading & validation
│   ├── db.ts             # SQLite + schema migrations
│   ├── logger.ts         # Pino structured logging
│   ├── audit.ts          # Audit trail
│   ├── memory/
│   │   └── index.ts      # FTS5-powered RAG memory
│   ├── workflows/
│   │   └── orchestrator.ts  # Multi-step workflow engine
│   ├── templates/
│   │   └── index.ts      # Stack-specific step templates
│   ├── git/
│   │   └── index.ts      # Git integration via simple-git
│   ├── safety/
│   │   └── sandbox.ts    # Command allowlist + path validation
│   └── tools/
│       ├── project.ts    # initializeProject, getProjectContext, indexRepo
│       ├── memory.ts     # addMemory, queryMemory, listMemories
│       ├── workflows.ts  # startWorkflow, executeStep, approveStep
│       ├── git.ts        # gitStatus, gitDiff, gitCommit, runCommand, runTests
│       ├── safety.ts     # readFile, writeFile, ciSimulate, getAuditLog
│       └── templates.ts  # listTemplates, previewTemplate
├── .devflow/             # Auto-created per project
│   ├── config.json       # Project config
│   ├── devflow.db        # SQLite: memory, workflows, audit
│   └── logs/            # Log files
├── docker-compose.yml
├── Dockerfile
└── README.md

Key Design Decisions:

  • SQLite with FTS5 for zero-dependency RAG — works offline, no vector DB setup needed
  • Step-based workflows with explicit approval gates prevent runaway AI actions
  • Command allowlist + path validation prevents sandbox escapes
  • Audit log tracks every action for accountability and rollback
  • Transport: stdio (primary) — simple, compatible with all MCP clients

🤝 Contributing

We love contributions! DevFlow is MIT-licensed and community-driven.

  1. Fork the repo
  2. Create a feature branch: git checkout -b feat/my-feature
  3. Make your changes with tests
  4. Run CI: npm run typecheck && npm test
  5. Submit a PR with a clear description

Areas we'd love help with:

  • Additional stack templates (Remix, SvelteKit, Django, Rails...)
  • Web dashboard UI
  • ChromaDB/LanceDB vector DB integration
  • VS Code extension
  • Docker-in-Docker sandboxing
  • Rollback/undo functionality

See CONTRIBUTING.md for details.

📄 License

MIT © Pedro Shakoor

Built with ❤️ for developers who want AI that ships, not just suggests.

About

No description, website, or topics provided.

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages