MCP Sdlc Tracker

🚀 SQLite MCP Tracker Server

The SQLite MCP Tracker Server is a Model Context Protocol (MCP) server. It offers task and project tracking capabilities based on SQLite through standardized tools and resources, facilitating efficient management throughout the Software Development Lifecycle (SDLC).

✨ Features

• SDLC Entity Management: Enables comprehensive tracking across the entire Software Development Lifecycle.
• Full SDLC Workflow Support: Covers Epics, User Stories, Tasks, Bugs, and Test Cases, ensuring seamless workflow management.
• Integrated Wiki System: Comes with an integrated wiki for project documentation, featuring entity linking and a 256 - character title limit.
• Comments System: Allows stakeholders to provide feedback and collaborate on all entities, with comment counts for easy reference.
• Epic Dependencies: Epics can depend on other epics, similar to user story dependencies.
• Workflow Enforcement: Ensures proper stakeholder ownership and status transitions.
• Automatic Status Changes: Automatically reopens closed stories when bugs are reported and reopens parent epics when stories move to QA.
• Audit Trail: Tracks ownership and status transitions for full traceability.
• Data Validation: Performs comprehensive input validation and foreign key constraint checking.
• Boolean Field Handling: Converts archived fields to proper boolean values (true/false instead of 0/1).
• HTTP API: Provides REST endpoints for database initialization, SDLC entities, and wiki pages.
• Web UI: Offers a tabbed dashboard interface with SDLC tracker and wiki sections, displaying entity numbers.
• Error Handling: Displays clear error messages for invalid operations and constraint violations.
• SQLite Backend: Utilizes SQLite with better - sqlite3 for efficient operations.

📦 Installation

npm install

💻 Usage Examples

Running the Server

npm start

Or for development with auto - restart:

npm run dev

Initializing the Database

Before using any other tools, you must initialize the database. You have two options:

Option 1: MCP Tool (Recommended for AI Agents)

1. Call the initialize tool and provide your current working directory path (e.g., "/Users/username/project").
2. The tool will create .project_tracker.db in that directory and set up all necessary tables.

Option 2: HTTP API (For Web Applications)

1. Start the server: npm start.
2. Call POST /api/initialize with: {"currentProjectLocation": "/path/to/project"}.
3. The API will create .project_tracker.db and establish the database connection.

Connecting to MCP Clients

This server uses stdio transport, so it can be connected to any MCP - compatible client. Below are setup instructions for popular AI coding agents:

Claude Code

claude mcp add --transport stdio my - tracker "npm start"

OpenCode

Add to your OpenCode MCP configuration:

{
  "mcpServers": {
    "sdlc - tracker": {
      "command": "npm",
      "args": ["start"],
      "cwd": "/path/to/your/project"
    }
  }
}

OpenAI Codex

Add to ~/.codex/config.toml:

[[mcp]]
name = "sdlc - tracker"
command = "npm"
args = ["start"]
cwd = "/path/to/your/project"

Windsurf

Configure in Windsurf's MCP settings with stdio transport and command npm start.

Cursor

1. Open Cursor settings.
2. Navigate to MCP section.
3. Add new server with:
   • Transport: stdio
   • Command: npm start
   • Working directory: /path/to/your/project

VS Code

1. Install an MCP extension (like "MCP" or "Claude Code").
2. Configure with stdio transport.
3. Set command to npm start.

Web UI Access

npm start
# Then visit the URL shown in the console (typically http://localhost:3000)

Web UI Features:

• Tabbed Interface: Separate SDLC Tracker and Wiki sections.
• Dashboard Overview: Visual representation of all SDLC entities with clear entity identification.
• Entity Number Display: All cards show entity type and ID (e.g., "User Story #5: Implement authentication").
• Wiki Browsing: Card - based wiki page display with metadata and tags.
• Wiki Archive: Archive wiki pages with confirmation dialogs and optional reason tracking.
• Dependency Visualization: Clickable dependency links for epics and user stories.
• Comment Counts: Display of comment counts on all entities.
• Interactive Navigation: Click entities to view detailed information.
• Wiki Page Rendering: Full Markdown support with linked SDLC entities.
• Real - time Updates: Automatic refresh of data changes.

Other MCP - Compatible Clients

• Cline: Configure in settings with stdio transport.
• Roo Code: Add server configuration with npm start command.
• Continue: Add to config.json with stdio transport.
• Zed: Configure in MCP settings panel.

For all clients, ensure you're running the command from your project directory where the SDLC tracker database should be initialized.

📚 Documentation

Tools Available

Database Management

• initialize: Initialize the SDLC tracker database in the specified project directory. You must provide your current working directory path (e.g., "/Users/username/project").

Epic Management

• create_epics: Create multiple epics with title, description, and productmanager assignment.
• list_epics: List epics with optional status filtering (excludes archived by default).
  • dependencies_resolved: Filter epics by dependency resolution status (true/false).
• update_epic: Update epic title, description, status, assignment, and phases.
• archive_epic: Archive epics (product managers only).

User Story Management

• create_user_stories: Create multiple user stories with epic association, acceptance criteria, and story points.
• list_user_stories: List user stories with filtering by epic, status, or assignee (excludes archived by default).
  • dependencies_resolved: Filter user stories by dependency resolution status (true/false).
• update_user_story_content: Update user story title, description, and story points (all stakeholders).
• update_user_story_acceptance_criteria: Update user story acceptance criteria (product managers only).
• archive_user_story: Archive user stories (product managers only).

Task Management

• create_tasks: Create multiple tasks with user story association, time estimates, and architect/developer assignment.
• list_tasks: List tasks with optional filtering by user story, status, assignee, and dependency relationships.
  • depends_on: Filter tasks that depend on a specific task ID.
  • depended_by: Filter tasks that are depended on by a specific task ID.
  • has_dependencies: Filter tasks that have (true) or don't have (false) any dependencies.
  • dependencies_resolved: Filter tasks by dependency resolution status (true/false).

Bug Tracking

• create_bugs: Create multiple bug reports with severity levels, reporter, and assignee information.
• list_bugs: List bugs with optional filtering by status, severity, reporter, assignee.

Test Case Management

• create_test_cases: Create multiple test cases with preconditions, steps, expected results, and tester/productmanager assignment.
• list_test_cases: List test cases with optional filtering by status, assignee.

Workflow Management

• update_entity_status: Update status and/or assignment of any SDLC entity with audit trail recording and intelligent workflow suggestions.
• manage_story_dependencies: Add or remove dependencies for multiple user stories in bulk.
• manage_epic_dependencies: Add or remove dependencies for multiple epics in bulk.
• manage_task_dependencies: Add or remove dependencies for multiple tasks in bulk (tasks must belong to same user story).
• Automatic Status Changes: Bugs created on closed stories automatically reopen them to QA, stories moving to QA automatically reopen their parent epics.

Intelligent Workflow Suggestions

The system provides intelligent workflow guidance across the entire SDLC:

• Task Closure Intelligence: When a task is moved to "Closed" status, the system automatically checks if all tasks in the user story are now closed.
• User Story Advancement: If all tasks are closed and the user story is not already in QA/UAT/Closed status, the system suggests moving the user story to "QA" status.
• Task Dependency Intelligence: When a task is closed, the system checks for dependent tasks and suggests moving them to "In Progress" if all their dependencies are satisfied.
• Bug Status Intelligence: When bugs change status, the system provides targeted suggestions:
  • "Fixed" bugs: Suggest QA verification.
  • "Closed" bugs: Check if regression tests exist, suggest creating if missing.
  • "Open" bugs: Suggest developer reassignment if assigned to tester.
• Automatic Status Changes: Beyond suggestions, the system automatically handles workflow transitions:
  • Bugs created on closed stories automatically reopen them to "QA" status.
  • Stories moving to "QA" automatically reopen their parent epics from "Closed" to "Open".
• User Story Validation: Prevents moving user stories to "In Progress" without acceptance criteria and test cases.
• Proactive Guidance: Helps teams maintain proper SDLC workflow without manual tracking.

Example Responses:

Task Dependency Intelligence:

{
  "success": true,
  "entity_type": "task",
  "entity_id": 5,
  "old_status": "Review",
  "new_status": "Closed",
  "workflow_suggestions": [
    {
      "entity_type": "task",
      "entity_id": 7,
      "suggested_action": "start_task",
      "reason": "All dependencies for task \"Implement API\" are now completed",
      "suggested_status": "In Progress"
    }
  ]
}

Bug Status Intelligence:

{
  "success": true,
  "entity_type": "bug",
  "entity_id": 3,
  "old_status": "In Progress",
  "new_status": "Fixed",
  "workflow_suggestions": [
    {
      "entity_type": "bug",
      "entity_id": 3,
      "suggested_action": "qa_verification",
      "reason": "Bug has been marked as fixed and should be verified by QA",
      "suggested_status": "In Progress"
    }
  ]
}

User Story Validation:

{
  "content": ["Please ask product manager to add acceptance criteria"],
  "structuredContent": {
    "success": false,
    "entity_type": "user_story",
    "entity_id": 1,
    "error": "Please ask product manager to add acceptance criteria"
  },
  "isError": true
}

Comments Support

• create_comments: Create comments on any SDLC entity for stakeholder feedback.
• get_comments: Retrieve comments for a specific SDLC entity.

Wiki Management

• create_wiki_page: Create wiki pages with Markdown content, tags, and category classification (titles limited to 256 characters).
• update_wiki_page: Update wiki page content, metadata, and tags (titles limited to 256 characters).
• list_wiki_pages: List wiki pages with filtering by category, status, tags, or search terms.
• get_wiki_page: Get detailed wiki page content with linked entities.
• manage_wiki_links: Add or remove links between wiki pages and SDLC entities.
• archive_wiki_page: Archive wiki pages (moves to Archived status).

Knowledge Graph Generation

• get_knowledge_graph: Generate and return the knowledge graph for the initialized project, analyzing Python, JavaScript/TypeScript, and Java files to extract imports, classes, functions, and dependencies.

Error Handling & Validation

The server includes comprehensive error handling and data validation:

Input Validation

• Required Fields: All required fields are validated using Zod schemas.
• Data Types: Proper type checking for all inputs.
• Enum Values: Stakeholder roles and status values are strictly validated.

Foreign Key Validation

• Reference Checking: All foreign key references (epic_id, user_story_id, task_id) are validated before database operations.
• Clear Error Messages: Invalid references return specific error messages (e.g., "Invalid epic IDs: 999").
• Constraint Enforcement: Database constraints are checked and violations are handled gracefully.

Error Response Format

• Consistent Structure: All tools return structured error responses with clear messages.
• Partial Success: Creation tools can return both successful and failed operations in a single response.
• Validation Errors: Input validation failures include detailed field - level error information.

Example Error Responses

// Foreign key validation error
"Invalid epic IDs: 999"

// Input validation error
{
  "code": "too_small",
  "minimum": 1,
  "message": "Title is required"
}

// Constraint violation
"FOREIGN KEY constraint failed"

HTTP API

The server also provides a REST API for web applications and direct HTTP access:

Endpoints

• GET /api/status: Get database initialization status and server information.
• POST /api/initialize: Initialize database with project location.
  • Request: {"currentProjectLocation": "/path/to/project"}.
  • Response: Database connection status.
• GET /api/epics: List all epics with comment counts and dependencies.
• GET /api/epic/:id: Get specific epic details.
• GET /api/story/:id: Get specific user story details.
• GET /api/task/:id: Get specific task details.
• GET /api/bug/:id: Get specific bug details.
• GET /api/test - case/:id: Get specific test case details.
• GET /api/comments/:entityType/:entityId: Get comments for any entity.
• GET /api/wiki: List all wiki pages with metadata and tags.
• GET /api/wiki/:id: Get specific wiki page with full content and linked entities.
• GET /api/wiki/search?q = term: Search wiki pages by title or content.
• GET /api/get - knowledge - graph: Generate and retrieve knowledge graph data for the initialized project.
  • Response: JSON object with tree structure and file analysis.

Features

• Comment Counts: All entities include comment_count field.
• Dependency Information: Epics and user stories include dependency arrays.
• Boolean Fields: Proper boolean values (true/false) for archived fields.
• JSON Responses: All endpoints return structured JSON data.

Resources Available

• database_schema: Provides information about the database schema and table structures.

Knowledge Graph

The knowledge graph tools analyze project codebases to create structured representations of the codebase:

Supported Languages

• Python (.py): Extracts imports, classes, functions, and function calls.
• JavaScript/TypeScript (.js, .ts, .jsx, .tsx): Extracts ES6/CommonJS imports, classes, functions, and calls.
• Java (.java): Extracts imports, classes, methods, and method calls.

Output Format

The knowledge graph is saved as .kg.json in the project root and contains:

{
  "t": "Project tree structure as text",
  "f": [
    {
      "f": "relative/file/path",
      "i": ["import1", "import2"],
      "c": ["Class1", "Class2"],
      "fn": ["function1", "function2"],
      "ca": ["call1", "call2"]
    }
  ]
}

Usage

• Automatically excludes build directories, node_modules, and generated files.
• Requires project initialization first (like other tools).
• Generates knowledge graph at runtime without storing files.
• Can be used for code analysis, dependency visualization, and project understanding.

Database Schema

The initialize tool creates a SQLite database file .project_tracker.db in the specified directory with a complete SDLC schema:

Core SDLC Entities

Audit Trail Tables

• Ownership Transitions: Tracks all ownership changes between stakeholders.
• Status Transitions: Tracks all status changes with timestamps and actors.

Indexes

• Performance indexes on all foreign keys and commonly filtered columns.
• Composite indexes for efficient entity - type queries.
• Comments entity index for fast entity - based filtering.

SDLC Workflow

The server implements a complete Software Development Lifecycle with proper stakeholder ownership:

Entity States & Transitions

• Epics: New → Open → Closed (owned by productmanager).
• User Stories: New → In Progress → QA → UAT → Closed (productmanager → architect → developer → tester → productmanager).
  • Validation: Cannot move to 'In Progress' without acceptance criteria and test cases.
• Tasks: New → In Progress → Review → Closed (architect → developer → architect).
• Bugs: Open → In Progress → Review → Fixed → Closed (any stakeholder can be involved).
  • Validation: 'Review' can only be set from 'In Progress', cannot jump directly to 'Fixed'.
• Test Cases: New, Passed, Failed (tester → productmanager → tester).

Stakeholders

• productmanager: Product management.
• programmanager: Program management.
• architect: Solution architecture.
• developer: Development team.
• tester: Quality assurance.

Story Dependencies

Stories can have dependencies on other stories to model complex project relationships:

• Many - to - Many Relationships: One story can depend on multiple stories, and multiple stories can depend on one story.
• Dependency Validation: Prevents circular dependencies and self - dependencies.
• Smart Ordering: list_user_stories returns stories with least/fewest dependencies first.
• Bulk Management: Add/remove dependencies for multiple stories in single operations.
• Visual Indicators: Dependency counts shown in UI with clickable links.

Epic Dependencies

Epics can have dependencies on other epics to model complex project relationships:

• Many - to - Many Relationships: One epic can depend on multiple epics, and multiple epics can depend on one epic.
• Dependency Validation: Prevents circular dependencies and self - dependencies.
• Bulk Management: Add/remove dependencies for multiple epics in single operations.
• Visual Indicators: Dependency counts shown in UI with clickable links.
• API Support: Full REST API support for epic dependency management.

Task Dependencies

Tasks can have dependencies on other tasks within the same user story to model task execution order:

• Same User Story Constraint: Tasks can only depend on other tasks within the same user story.
• Dependency Validation: Prevents circular dependencies, self - dependencies, and cross - story dependencies.
• Bulk Management: Add/remove dependencies for multiple tasks in single operations.
• Visual Indicators: Dependency counts shown in UI with clickable links.
• API Support: Full MCP API support for task dependency management.

Dependencies Resolved Status

All list operations (list_epics, list_user_stories, list_tasks) include a dependencies_resolved boolean field that indicates whether all dependencies of an entity are in 'Closed' status:

• Dynamic Calculation: Computed in real - time when listing entities.
• Filtering Support: All list operations support dependencies_resolved filter parameter.
• Workflow Visibility: Helps teams identify entities ready for work.
• API Integration: Available in both MCP tools and REST API endpoints.

Phase Management

Entities can be assigned to custom phases for project organization:

• Phase: Custom phase name (e.g., "Planning", "Development", "Testing", "Deployment").
• Phase Status: Current status within the phase (e.g., "Not Started", "In Progress", "Completed", "Blocked").
• Optional: Phases are completely optional and don't affect core workflow transitions.
• Flexible: Phase names are free - form text, allowing custom project - specific phases.
• Filtering: All list operations support filtering by phase and phase_status parameters.
• Setting: Phases can be set during entity creation or updated via update_entity_status.

User Story Permissions & Archiving

User stories have restricted update permissions and archiving capabilities:

• Content Updates: All stakeholders can update title, description, and story points.
• Acceptance Criteria: Only Product Managers can update acceptance criteria.
• Archiving: Only Product Managers can archive user stories with reason tracking.
• Archived Stories: Hidden from default views, accessible with include_archived: true.
• Audit Trail: All content and acceptance criteria changes are fully audited.

Comments System

• Comments can be added to any SDLC entity by any stakeholder.
• Supports threaded discussions and feedback on requirements, implementations, and issues.
• Maintains full audit trail with author and timestamps.

Audit Trail

All ownership and status transitions are recorded in audit tables for complete traceability.

Project Folder Access

The MCP server requires explicit initialization with the project directory path for security reasons. The initialize tool must be called first with your current working directory path before any other tools can be used.

Example Usage

Once connected to an MCP client, you can:

Database Initialization

1. "Initialize the database with path '/Users/username/my - project'".

Epic Management

1. "Create epics: 'User Authentication System' and 'Payment Processing'".
2. "List all open epics".

User Story Creation

3. "Create user stories: 'As a user, I want to login with email/password' (5 points) and 'As a user, I want to reset my password' (3 points) for epic 1" (Note: Epic ID is validated - invalid references return clear error messages).
4. "Create user story with phase: 'Implement user dashboard' (8 points) for epic 1 with phase 'Development' and phase_status 'Planning'".
5. "List user stories in progress assigned to developer".
6. "List user stories in 'Development' phase".

Task Breakdown

5. "Create tasks: 'Implement password hashing' (4 hours) and 'Create login UI' (6 hours) for user story 1 assigned to developer" (Note: User story references are validated).
6. "Create task with phase: 'Write unit tests' (3 hours) for user story 1 with phase 'Testing' and phase_status 'Not Started'".
7. "List tasks that are in progress".
8. "List tasks in 'Testing' phase with 'Not Started' status".
9. "Update task 1 status to 'Closed'".
10. "Update task 2 phase to 'Testing' and phase_status 'In Progress'".

Story Dependencies

11. "Add dependencies: Story 2 depends on Story 1, Story 3 depends on Story 2".
12. "Remove dependency: Story 3 no longer depends on Story 2".
13. "List user stories ordered by dependencies (least dependent first)".

Epic Dependencies

14. "Add dependencies: Epic 2 depends on Epic 1, Epic 3 depends on Epic 2".
15. "Remove dependency: Epic 3 no longer depends on Epic 2".
16. "List epics with dependency information".

Bug Tracking

7. "Create bugs: 'Login fails on mobile devices' (Critical, reported by tester) and 'Password reset email not sent' (High, reported by productmanager)" (Note: User story and task references are validated if provided).
8. "List all open bugs with high severity".

Test Case Creation

9. "Create test cases: 'Verify user can login successfully' and 'Verify password reset works' for user story 1" (Note: User story references are validated if provided).
10. "List test cases that have failed".

Comments and Collaboration

11. "Add comment on user story 1: 'Need to ensure security best practices' by architect".
12. "Add comment on bug 1: 'Validation should check email format' by developer".

Wiki Documentation

13. "Create wiki page: 'API Authentication Guide' with content about OAuth2 flow, category 'technical', tags ['authentication', 'security', 'api']".
14. "Create wiki page: 'Deployment Process' with step - by - step deployment instructions, category 'process', tags ['deployment', 'ci - cd']".
15. "List all wiki pages in technical category".
16. "Update wiki page content for 'API Authentication Guide' with additional OAuth2 details".
17. "Link wiki page 'API Authentication Guide' to user story 1 and task 2".
18. "Search wiki pages for 'authentication'".

Workflow Management

13. "Update user story 1 status to 'In Progress' transitioned by architect".
14. "Update task 1 status to 'Closed' transitioned by developer".

Dependencies Resolved Filtering

15. "List epics with all dependencies resolved".
16. "List user stories that have unresolved dependencies".
17. "List tasks ready to start (dependencies resolved)".

Knowledge Graph Generation

18. "Get knowledge graph data for the initialized project".

Bug Status Management

18. "Update bug 1 status to 'Review' (must come from 'In Progress')".
19. "Update bug 2 status to 'Fixed' (triggers QA verification suggestion)".

🔧 Technical Details

The server is written in TypeScript and uses:

• @modelcontextprotocol/sdk: Official MCP TypeScript SDK.
• better - sqlite3: High - performance SQLite library.
• zod: Schema validation for tool inputs/outputs.

Recent Improvements

• Automatic Workflow Transitions: Bugs on closed stories reopen them to QA, stories moving to QA reopen their epics.
• Enhanced UI Entity Display: Dashboard cards show entity type and numbers (e.g., "User Story #5: Title").
• Wiki Archive UI: Archive wiki pages from the web interface with confirmation dialogs.
• Wiki Title Validation: 256 - character limit on wiki page titles for better usability.
• Wiki System: Complete wiki functionality with Markdown pages, tags, categories, and SDLC entity linking.
• Tabbed Web UI: Enhanced dashboard with separate SDLC Tracker and Wiki sections.
• Wiki API: Full REST API for wiki page management and search.
• Comment Count Display: All entities now show comment counts in APIs and MCP tools.
• Boolean Field Conversion: Proper boolean handling for archived fields (true/false).
• Epic Dependencies: Full dependency support for epics (similar to user stories).
• HTTP API: REST endpoints for database initialization and entity access.
• Web UI Enhancements: Epic dependency visualization in dashboard.
• Enhanced Error Handling: Comprehensive validation with clear error messages.
• Foreign Key Validation: All entity references are validated before database operations.
• Consistent API Responses: All list tools now use standardized response format.
• Improved Data Integrity: Better constraint checking and error reporting.
• Dependencies Resolved Status: Dynamic calculation and filtering for epic, user story, and task dependencies.
• Bug Status Enhancement: Added 'Review' status with strict transition validation (In Progress → Review → Fixed).
• Advanced Workflow Intelligence: Task dependency suggestions, bug status intelligence, and user story validation.
• Enhanced Filtering: dependencies_resolved filter parameter across all list operations.

📄 License

ISC