Agile MCP
A comprehensive agile backlog management system built with the Model Context Protocol (MCP), featuring project isolation, multi-agent support, and interactive visualization
Overview
Agile MCP provides a complete agile backlog management solution that bridges AI agents and human teams. It consists of three integrated components:
- MCP Server: Exposes agile backlog tools via Model Context Protocol for AI agents (Claude, etc.)
- Web UI: Interactive dashboard for humans with dependency graphs and hierarchy trees
- Shared Database: SQLite database with project isolation and security auditing
Key Features
🔒 Project Isolation
- Identifier-based security: Each project has a unique identifier
- Multi-project support: Manage multiple repositories in a single database
- Access control: AI agents can only access items from their registered project
- Security auditing: All access attempts logged for compliance
🤖 MCP Server (AI Agent Interface)
- Epic, Story, and Task Management: Full CRUD operations
- Sprint & Iteration Planning: Create sprints, manage capacity, track velocity
- Burndown Tracking: Daily snapshots and burndown chart data
- Dependency Tracking: Create dependencies with circular dependency prevention
- Conflict Detection: Track modifications to detect concurrent edits
- Export Capabilities: Export backlog data for analysis
- MCP Resources: Read-only views for backlog overview and dependencies
🌐 Web UI (Human Interface)
- Project Management: Register and switch between projects
- Full CRUD Operations: Create, edit, and delete epics, stories, and tasks
- Sprint Management: Create and manage sprints, add/remove stories
- Sprint Board: Kanban-style board with drag-and-drop (5 status columns)
- Burndown Charts: Visual burndown tracking with ideal vs actual lines
- Velocity Reports: Historical velocity calculation for sprint planning
- Backlog List View: Filterable list with sprint and epic filtering
- Dependency Graph: Interactive React Flow visualization showing story dependencies
- Hierarchy Tree: D3-powered tree view of Epic → Story → Task relationships
- Responsive Design: Mobile-friendly interface with adaptive layouts
💾 Database & Security
- SQLite with WAL mode: Fast, reliable local storage
- Foreign key constraints: Cascade deletes maintain data integrity
- Automatic migrations: Database schema updates applied automatically
- Security logs: Audit trail for unauthorized access attempts
- Conflict detection: Track concurrent modifications
Architecture
agile-mcp/
├── mcp-server/ # MCP server for AI agent access
│ ├── src/
│ │ ├── tools/ # Tool handlers (project, epic, story, task, dependency)
│ │ ├── resources/ # MCP resource handlers
│ │ └── index.ts # Server entry point
│ └── package.json
├── web-ui/ # React visualization dashboard
│ ├── server/ # Express REST API server (port 3004)
│ ├── src/
│ │ ├── components/ # React components
│ │ ├── utils/ # API client
│ │ └── types/ # TypeScript types
│ └── package.json
├── shared/ # Shared database schema & types
│ └── src/
│ ├── database.ts # SQLite database class
│ └── types.ts # Shared TypeScript types
└── agile-backlog.db # SQLite database file
Quick Start
Prerequisites
- Node.js 18+
- npm 9+
Installation
# Install dependencies for all workspaces
npm install
# Build shared package
cd shared && npm run build && cd ..
# Build MCP server
cd mcp-server && npm run build && cd ..
Usage
For AI Agents (MCP Server)
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"agile-mcp": {
"command": "node",
"args": ["/absolute/path/to/agile-mcp/mcp-server/dist/index.js"]
}
}
}
Then in Claude:
Register this project: "my-app"
Create an epic for user authentication
Add a story for login functionality to that epic
For Humans (Web UI)
cd web-ui
npm run dev
Visit http://localhost:3004 to access:
- Backlog List (
/) - Filterable story list with CRUD operations and sprint filtering - Sprint Board (
/project/:id/sprint/:sprintId) - Kanban board for active sprints - Burndown Chart (
/project/:id/sprint/:sprintId/burndown) - Sprint burndown visualization - Dependency Graph (
/project/:id/dag) - Interactive dependency visualization - Hierarchy Tree (
/project/:id/tree) - Epic → Story → Task hierarchy
Core Concepts
Projects
Each project represents a codebase/repository with its own isolated backlog:
- Unique identifier (e.g.,
"frontend-app","api-service") - All epics, stories, and tasks belong to a project
- AI agents must register projects before creating backlog items
Epics, Stories, and Tasks
Standard agile hierarchy:
- Epics: High-level feature areas or initiatives
- Stories: User stories with priority, points, and status
- Tasks: Actionable sub-items of stories
Sprints & Iterations
Time-boxed work periods with capacity planning:
- Sprint lifecycle: planning → active → completed
- Story assignment: Add/remove stories from sprints
- Capacity tracking: Monitor committed vs completed points
- Burndown charts: Track remaining work over time
- Velocity metrics: Calculate historical team velocity
- Daily snapshots: Record progress for burndown visualization
Dependencies
Story-to-story relationships:
- blocks / blocked_by dependency types
- Automatic circular dependency detection
- Visualized in dependency graph view
Status Workflow
All items follow this workflow:
todo → in_progress → review → done
↓ ↑
blocked ────────┘
Technology Stack
| Layer | Technology |
|---|---|
| MCP Protocol | @modelcontextprotocol/sdk |
| Database | SQLite (better-sqlite3) |
| Backend API | Express.js, TypeScript |
| Frontend | React 18, TypeScript, Vite |
| Graph Visualization | React Flow (@xyflow/react) |
| Tree Visualization | D3.js |
| Styling | Tailwind CSS |
| Icons | Lucide React |
Documentation
- QUICKSTART.md - Get started in 5 minutes
- ARCHITECTURE.md - Technical architecture and design
- MCP_SERVER.md - Complete MCP tool reference for AI agents
- API_REFERENCE.md - REST API documentation for developers
- DEPLOYMENT.md - Production deployment guide
Example Workflows
AI Agent Workflow
// 1. Register project
Tool: register_project
{
"project_identifier": "my-app",
"name": "My Application",
"description": "Main application project"
}
// 2. Create epic
Tool: create_epic
{
"project_identifier": "my-app",
"agent_identifier": "claude",
"title": "User Authentication",
"description": "Implement secure user authentication"
}
// 3. Create story
Tool: create_story
{
"project_identifier": "my-app",
"agent_identifier": "claude",
"epic_id": 1,
"title": "Login page",
"description": "Create login UI with email and password",
"priority": "high",
"points": 5
}
// 4. Add dependency
Tool: add_dependency
{
"project_identifier": "my-app",
"agent_identifier": "claude",
"story_id": 2,
"depends_on_story_id": 1,
"dependency_type": "blocks"
}
Web UI Workflow
- Open http://localhost:3004
- Select project from dropdown (or create new project)
- Click "New Epic" to create an epic
- Click "New Story" to create a story
- Click "New Sprint" to create a sprint for iteration planning
- Add stories to sprints from story detail pages
- View active sprint board by clicking "Active Sprint" button
- Track progress with burndown charts
- Use edit/delete icons for modifications
- Switch to "Dependency Graph" to visualize relationships
- Switch to "Hierarchy Tree" to see the full hierarchy
Security Features
Project Isolation
- Each project has a unique identifier
- All MCP tools validate project access
- Cross-project access attempts are blocked and logged
Audit Trail
- Security logs track all access violations
- Event types:
unauthorized_access,project_violation,conflict_detected - Accessible via
/api/security-logsendpoint
Conflict Detection
- Tracks
last_modified_byfor all entities - Detects concurrent modifications
- Warns when multiple agents edit the same item
Development
Build All Packages
npm run build
Watch Mode
# MCP server
cd mcp-server && npm run dev
# Web UI (runs both API server and Vite dev server)
cd web-ui && npm run dev
Database Location
The SQLite database is created at ./agile-backlog.db in the project root.
Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
License
MIT License - see LICENSE file for details
Support
- Issues: Report bugs or request features via GitHub issues
- Documentation: See docs/ directory for detailed guides
- MCP SDK: https://github.com/anthropics/mcp
Built with ❤️ for seamless AI-human collaboration in agile development