aidlc-mcp-tools 1.0.2

AIDLC Dashboard MCP Tools for Amazon Q integration

AIDLC MCP Tools

A Model Context Protocol (MCP) server implementation that provides AI agents with tools to interact with the AIDLC Dashboard service. This enables seamless integration between AI tools and project management workflows.

🚀 Features

• Project Management: Create and manage projects through MCP
• Artifact Upload: Upload AI-generated artifacts (epics, user stories, domain models, etc.)
• Progress Tracking: Update project status and track completion
• Health Monitoring: Check service availability and performance
• Batch Operations: Handle multiple artifacts efficiently
• Amazon Q Integration: Optimized for Amazon Q Developer workflows

📋 Requirements

• Python 3.11+
• requests library
• AIDLC Dashboard service running (for integration)

🛠️ Installation

Option 1: Using uv (Recommended)

# Install with uv
uv pip install -e .

# Or install from PyPI (when published)
uv pip install mcp-tools

Option 2: Using pip

# Install in development mode
pip install -e .

# Or install dependencies manually
pip install -r requirements.txt

Option 3: Quick Setup Script

./setup.sh

🌐 Usage

As MCP Server (Amazon Q Integration)

1. Configure Amazon Q MCP settings:

{
  "mcpServers": {
    "aidlc-dashboard": {
      "command": "aidlc-mcp-server",
      "env": {
        "AIDLC_DASHBOARD_URL": "http://localhost:8000/api"
      }
    }
  }
}

2. Start the MCP server:

aidlc-mcp-server

3. Use in Amazon Q:

Create a new project called "E-commerce Platform" and upload the epics artifact with user authentication features.

As Python Library

from aidlc_mcp_tools import AIDLCDashboardMCPTools

# Initialize tools
tools = AIDLCDashboardMCPTools("http://localhost:8000/api")

# Create a project
result = tools.create_project("My New Project")
if result.success:
    project_id = result.data['project']['id']
    print(f"Created project: {project_id}")

# Upload an artifact
artifact_content = {
    "title": "User Authentication",
    "description": "Implement user login and registration",
    "priority": "high"
}

result = tools.upload_artifact(project_id, "epics", artifact_content)
if result.success:
    print("Artifact uploaded successfully")

Standalone Script

# Create a project
python -m aidlc_mcp_tools.cli create-project "My Project"

# Upload artifact
python -m aidlc_mcp_tools.cli upload-artifact PROJECT_ID epics '{"title": "Epic Title"}'

# Check health
python -m aidlc_mcp_tools.cli health-check

🔧 Configuration

Environment Variables

Variable	Description	Default
AIDLC_DASHBOARD_URL	Dashboard API base URL	http://localhost:8000/api
AIDLC_TIMEOUT	Request timeout (seconds)	30
AIDLC_RETRY_ATTEMPTS	Number of retry attempts	3
AIDLC_LOG_LEVEL	Logging level	INFO

Configuration File

Create config.json:

{
  "dashboard_url": "http://localhost:8000/api",
  "timeout": 30,
  "retry_attempts": 3,
  "log_level": "INFO"
}

📖 Available MCP Tools

1. aidlc_create_project

Create a new project in the AIDLC Dashboard.

Parameters:

• name (string): Project name

Example:

{
  "name": "create_project",
  "arguments": {
    "name": "E-commerce Platform"
  }
}

2. aidlc_upload_artifact

Upload an artifact to a project.

Parameters:

• project_id (string): Project identifier
• artifact_type (string): Type of artifact (epics, user_stories, domain_model, model_code_plan, ui_code_plan)
• content (object): Artifact content

Example:

{
  "name": "upload_artifact",
  "arguments": {
    "project_id": "project-123",
    "artifact_type": "epics",
    "content": {
      "title": "User Management",
      "description": "Complete user management system",
      "priority": "high"
    }
  }
}

3. aidlc_update_status

Update the status of an artifact.

Parameters:

• project_id (string): Project identifier
• artifact_type (string): Type of artifact
• status (string): New status (not-started, in-progress, completed)

4. aidlc_get_project

Get project details and current status.

Parameters:

• project_id (string): Project identifier

5. aidlc_list_projects

List all projects in the dashboard.

Parameters: None

6. aidlc_health_check

Check if the dashboard service is healthy and accessible.

Parameters: None

🎯 Artifact Types and Schemas

Epics

{
  "title": "Epic Title",
  "description": "Epic description",
  "user_stories": ["US-001", "US-002"],
  "priority": "high|medium|low",
  "acceptance_criteria": ["Criteria 1", "Criteria 2"]
}

User Stories

{
  "stories": [
    {
      "id": "US-001",
      "title": "Story Title",
      "description": "As a user, I want...",
      "acceptance_criteria": ["Criteria 1"],
      "priority": "high",
      "story_points": 5
    }
  ],
  "total_count": 1,
  "epics": ["Epic-001"]
}

Domain Model

{
  "entities": [
    {
      "name": "User",
      "attributes": ["id", "username", "email"],
      "description": "System user entity"
    }
  ],
  "relationships": [
    {
      "from": "User",
      "to": "Order",
      "type": "one-to-many"
    }
  ]
}

Model Code Plan

{
  "components": [
    {
      "name": "UserService",
      "type": "service",
      "dependencies": ["UserRepository"]
    }
  ],
  "implementation_steps": [
    "Create entities",
    "Implement repositories"
  ]
}

UI Code Plan

{
  "pages": [
    {
      "name": "LoginPage",
      "route": "/login",
      "components": ["LoginForm", "Header"]
    }
  ],
  "navigation": {
    "type": "SPA",
    "router": "React Router"
  }
}

🧪 Testing

Unit Tests

# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov=aidlc_mcp_tools

Integration Tests

# Start dashboard service first
cd ../dashboard-service
python run.py --generate-demo &

# Run integration tests
python -m pytest tests/integration/

Manual Testing

# Test MCP server
python test_mcp_server.py

# Test individual tools
python examples/test_tools.py

📁 Project Structure

aidlc-mcp-tools/
├── README.md                    # This file
├── pyproject.toml              # Project configuration
├── requirements.txt            # Python dependencies
├── setup.sh                   # Quick setup script
├── aidlc_mcp_tools/           # Main package
│   ├── __init__.py            # Package initialization
│   ├── server.py              # MCP server implementation
│   ├── tools.py               # MCP tools implementation
│   ├── cli.py                 # Command-line interface
│   └── config.py              # Configuration management
├── tests/                     # Test suite
│   ├── unit/                  # Unit tests
│   ├── integration/           # Integration tests
│   └── fixtures/              # Test fixtures
├── examples/                  # Usage examples
│   ├── basic_usage.py         # Basic usage examples
│   ├── amazon_q_workflow.py   # Amazon Q integration examples
│   └── batch_operations.py    # Batch processing examples
├── docs/                      # Documentation
│   ├── API.md                 # API documentation
│   ├── INTEGRATION.md         # Integration guide
│   └── TROUBLESHOOTING.md     # Troubleshooting guide
└── scripts/                   # Utility scripts
    ├── test_connection.py     # Test dashboard connection
    └── generate_config.py     # Generate configuration files

🔗 Integration Examples

Amazon Q Workflow

# In Amazon Q, you can use natural language:
# "Create a project for an e-commerce platform and add user authentication epics"

# This translates to MCP tool calls:
tools.create_project("E-commerce Platform")
tools.upload_artifact(project_id, "epics", {
    "title": "User Authentication",
    "description": "Implement secure user login and registration",
    "priority": "high"
})

Batch Processing

# Upload multiple artifacts at once
artifacts = [
    ("epics", {"title": "User Management", "priority": "high"}),
    ("user_stories", {"stories": [...], "total_count": 5}),
    ("domain_model", {"entities": [...], "relationships": [...]})
]

for artifact_type, content in artifacts:
    tools.upload_artifact(project_id, artifact_type, content)

🐛 Troubleshooting

Common Issues

Connection refused:

# Check if dashboard service is running
curl http://localhost:8000/api/health

# Start dashboard service
cd ../dashboard-service
python run.py

Import errors:

# Install in development mode
pip install -e .

# Or install dependencies
pip install -r requirements.txt

MCP server not responding:

# Check MCP server logs
aidlc-mcp-server --debug

# Test MCP server directly
python -m aidlc_mcp_tools.server --test

Debug Mode

# Enable debug logging
export AIDLC_LOG_LEVEL=DEBUG
aidlc-mcp-server

# Or use debug flag
aidlc-mcp-server --debug

📚 Documentation

• API Documentation - Detailed API reference
• Integration Guide - Integration with various tools
• Troubleshooting Guide - Common issues and solutions

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built for Amazon Q Developer integration
• Follows MCP (Model Context Protocol) standards
• Designed for AIDLC methodology workflows
• Optimized for AI-assisted development

---

Happy coding with AI! 🤖✨

For questions or support, please check the documentation or create an issue in the repository.