Agile Sentinel MCP

Transform technical analysis into structured agile tasks with CLI and MCP Server support.

Overview

Agile Sentinel MCP is a dual-mode TypeScript/Node.js tool that analyzes software projects, calculates quality metrics, generates prioritized backlogs, plans sprints, and synchronizes tasks with Notion databases.

Features

• Dual Mode Operation: Works as both a CLI tool and MCP Server for AI agents
• Technical Analysis: Analyzes code quality, security vulnerabilities, and technical debt
• Quality Scoring: Calculates project health scores with detailed breakdowns
• Backlog Generation: Automatically creates prioritized task backlogs
• Sprint Planning: Intelligently groups tasks into balanced sprints
• Changelog Generation: Creates structured changelogs from git history
• Notion Integration: Syncs tasks with Notion databases

Installation

npm install -g agile-sentinel-mcp

Usage

CLI Mode

Scan Command

Analyzes a project and generates a technical report:

agile scan ./my-project

# With options
agile scan ./my-project --output .agile/report.json --exclude "*.test.ts,*.spec.ts"

Options:

• --output, -o: Output file path (default: .agile/report.json)
• --exclude, -e: Comma-separated patterns to exclude
• --verbose, -v: Enable verbose logging

Output: Creates .agile/report.json and .agile/report.md

Backlog Command

Generates a prioritized task backlog from analysis report:

agile backlog .agile/report.json

# With options
agile backlog .agile/report.json --output .agile/backlog.json --format json

Options:

• --output, -o: Output file path (default: .agile/backlog.json)
• --format, -f: Output format: json or markdown (default: json)

Output: Creates .agile/backlog.json or .agile/backlog.md

Sprint Command

Plans sprints from task backlog:

agile sprint .agile/backlog.json

# With options
agile sprint .agile/backlog.json --max-effort 21 --sprint-duration 14

Options:

• --output, -o: Output file path (default: .agile/sprint-plan.json)
• --max-effort: Maximum effort points per sprint (default: 21)
• --sprint-duration: Sprint duration in days (default: 14)

Output: Creates .agile/sprint-plan.json

Changelog Command

Generates structured changelog from git history:

agile changelog ./my-project

# With options
agile changelog ./my-project --from v1.0.0 --to HEAD --output CHANGELOG.md

Options:

• --output, -o: Output file path (default: CHANGELOG.md)
• --from: Starting git reference (default: first commit)
• --to: Ending git reference (default: HEAD)

Output: Creates CHANGELOG.md

Notion Init Command

Initializes Notion integration:

agile notion init

Prompts for:

• Notion API Key (secret_...)
• Notion Database ID (32-character hex)

Saves configuration to .agile/config.json

Notion Sync Command

Synchronizes tasks with Notion database:

agile notion sync .agile/backlog.json

# With options
agile notion sync .agile/backlog.json --api-key secret_xxx --database-id xxx --dry-run

Options:

• --api-key: Notion API key (overrides config)
• --database-id: Notion database ID (overrides config)
• --dry-run: Preview changes without syncing

Output: Displays sync results (created, updated, failed)

MCP Server Mode

The MCP server allows AI agents to use Agile Sentinel's capabilities through the Model Context Protocol.

Setup

Configure in your AI agent's MCP settings (e.g., Claude Desktop, Cline):

{
  "mcpServers": {
    "agile-sentinel": {
      "command": "npx",
      "args": ["-y", "agile-sentinel-mcp"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "agile-sentinel": {
      "command": "agile-sentinel-mcp"
    }
  }
}

Available MCP Tools

The MCP server exposes 5 tools for AI agents:

1. analyze_project: Analyzes a software project and returns a comprehensive technical report

   • Input: projectPath (string), optional excludePatterns (array)
   • Output: Project report with findings, scores, and recommendations

2. generate_backlog: Generates a prioritized task backlog from an analysis report

   • Input: report (object or file path)
   • Output: Array of tasks with categories, priorities, and effort estimates

3. generate_sprint_plan: Creates balanced sprint plan from tasks

   • Input: tasks (array or file path), optional maxEffortPerSprint (number)
   • Output: Sprint plan with tasks organized by sprint

4. generate_changelog: Generates structured changelog from git history

   • Input: projectPath (string), optional fromRef and toRef
   • Output: Changelog with categorized commits and markdown format

5. sync_notion: Synchronizes tasks with Notion database

   • Input: tasks (array), optional apiKey and databaseId
   • Output: Sync results with created/updated/failed counts

Notion Integration Setup

1. Create Notion Integration

1. Go to Notion Integrations
2. Click "New integration"
3. Give it a name (e.g., "Agile Sentinel")
4. Select the workspace
5. Copy the "Internal Integration Token" (starts with secret_)

2. Create Notion Database

Create a database in Notion with these properties:

| Property | Type | Description | |----------|------|-------------| | Name | Title | Task title | | Status | Select | Task status (To Do, In Progress, Done) | | Priority | Select | Task priority (Critical, High, Medium, Low) | | Category | Select | Task category (Refactoring, Security, Documentation, Bug Fix, Technical Debt) | | Effort | Number | Effort estimate (Fibonacci: 1, 2, 3, 5, 8, 13) | | Sprint | Select | Sprint assignment (Sprint 1, Sprint 2, etc.) | | Source | Text | Source system (always "Agile Sentinel") |

3. Share Database with Integration

1. Open your database in Notion
2. Click "..." menu → "Add connections"
3. Select your integration

4. Get Database ID

The database ID is in the URL:

https://notion.so/workspace/DATABASE_ID?v=...
                          ^^^^^^^^^^^^^^^^

5. Configure Agile Sentinel

Run the init command:

agile notion init

Or manually create .agile/config.json:

{
  "notion": {
    "apiKey": "secret_...",
    "databaseId": "..."
  }
}

Configuration

Configuration file: .agile/config.json

{
  "notion": {
    "apiKey": "secret_...",
    "databaseId": "..."
  },
  "analysis": {
    "maxFileSize": 300,
    "excludePatterns": ["node_modules", "dist", ".git"]
  },
  "sprint": {
    "maxEffortPerSprint": 21,
    "sprintDuration": 14
  }
}

Configuration Options

Notion

• apiKey: Notion API key (required for sync)
• databaseId: Notion database ID (required for sync)

Analysis

• maxFileSize: Maximum file size in lines before flagging as large (default: 300)
• excludePatterns: Array of glob patterns to exclude from analysis

Sprint

• maxEffortPerSprint: Maximum effort points per sprint (default: 21)
• sprintDuration: Sprint duration in days (default: 14)

Quality Scoring

Agile Sentinel calculates a quality score (0-100) based on:

Base Score: 100

Deductions:

• Large Files: -1 per 100 lines over 300
• TODO/FIXME Comments: -0.5 per comment
• Security Vulnerabilities:
  • Critical: -10 per vulnerability
  • High: -5 per vulnerability
  • Medium: -2 per vulnerability
  • Low: -1 per vulnerability
• Change Hotspots: -5 per file with >10 changes
• Recurring Errors: -2 per error pattern in commits

Score Breakdown:

• Maintainability: Based on file size and code health
• Security: Based on vulnerability count and severity
• Code Health: Based on TODO/FIXME density
• Risk Level: Based on change concentration

Task Categories

Generated tasks are categorized as:

• Refactoring: Large files, code complexity
• Security: Security vulnerabilities
• Documentation: TODO comments
• Bug Fix: FIXME comments, recurring errors
• Technical Debt: Change hotspots, accumulated issues

Priority Levels

Tasks are prioritized as:

• Critical: Security vulnerabilities (critical/high)
• High: Large files, frequent changes
• Medium: TODO/FIXME comments
• Low: Minor improvements

Effort Estimation

Effort is estimated using Fibonacci sequence (1, 2, 3, 5, 8, 13) based on:

• Issue severity
• File size
• Complexity indicators

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run dev

Roadmap

• [ ] Dashboard SaaS for team collaboration
• [ ] Historical score tracking and trends
• [ ] Plugin system for custom analyzers
• [ ] Integration with Jira
• [ ] Integration with GitHub Issues
• [ ] CI/CD mode for automated analysis
• [ ] Custom rule configuration
• [ ] Multi-language support for reports

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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