mcp-ai-act by michaelwybraniec - MCP Server

EU AI Act MCP Server v0.2.1

MCP server for EU AI Act compliance checking and analysis with enhanced LLM integration and bug fixes.

Note: This project was initiated using the AWP - Agentic Workflow Protocol, a HUMAN-AI Precision Strike for Controlled Vibe Coding & Context Engineering.

🐛 Recent Bug Fixes (v0.2.1)

Critical Fix: LLM Compliance Report Generation

Issue: LLMs were generating incorrect compliance assessments, claiming systems were "FULLY COMPLIANT" when actual data showed "HIGH RISK"
Root Cause: LLMs were ignoring MCP server data and generating their own assessments
Solution: Enhanced response format with explicit compliance data, structured JSON blocks, and multiple warnings
Result: LLMs now correctly use actual compliance data instead of generating incorrect reports

Enhanced Response Format

Added structured JSON compliance data at the top of responses
Multiple explicit warnings to prevent LLM confusion
Clear compliance status indicators (NON-COMPLIANT, PARTIALLY COMPLIANT, COMPLIANT)
Improved error handling and syntax fixes

🚀 Quick Start

Installation

# Clone the repository
git clone <repository-url>
cd mcp-ai-act

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Running the Server

Option 1: Web Interface (Recommended)

# Start the web client (includes MCP server)
cd client
python start_web_client.py
# Then open: http://localhost:8080

Option 2: MCP Server Only

# Start the MCP server directly
python src/mcp_server.py

📋 Features

🌐 Web Interface

Dashboard: System status and data overview
Quick Compliance Check: Instant AI Act compliance analysis
Data Management: Update and regenerate AI Act data
Resource Browser: Explore AI Act articles and chapters
Tool Interface: Execute MCP tools with custom parameters

MCP Tools (6 available)

check_compliance - Check AI Act compliance for a project or system (generates detailed reports with AWP integration) - Enhanced with explicit compliance data format
detailed_assessment - Comprehensive AI Act compliance assessment with full parameter specification
get_article - Get specific AI Act article by number
search_requirements - Search for specific compliance requirements
assess_risk - Assess risk level of an AI system
prepare_migration_backlog - Generate AWP-compatible migration backlog from compliance reports

MCP Resources (7 available)

Core AI Act Data:

ai-act://articles - All AI Act articles (167 articles) - Access complete article data
ai-act://chapters - All AI Act chapters (5 chapters) - Browse chapter structure
ai-act://compliance-requirements - AI Act compliance requirements - Get compliance matrix

Project Resources:

ai-act://test-cases - Compliance test cases - Validation scenarios
ai-act://compliance-template - Report template - Generate consistent reports
ai-act://quick-reference - AI Act quick reference - Compliance guide
ai-act://benchmarks - Performance benchmarks - Test scenarios

MCP Prompts (4 available)

compliance_check - Check AI system compliance
risk_assessment - Assess risk level
requirements_analysis - Analyze requirements
article_lookup - Find relevant articles

📊 AI Act Data

Files Included

data/ai-act/ai-act-raw.html - Raw HTML from EU source (420KB)
data/ai-act/ai-act-text.html - Clean HTML version for parsing (1.2MB)
data/ai-act/ai-act-clean.txt - Clean text version for easy reading (583KB)
data/ai-act/metadata.json - Comprehensive metadata about the AI Act
data/ai-act/version.json - Version tracking and file hashes

AI Act Details

Official Name: Regulation (EU) 2024/1689
Publication Date: July 12, 2024
Effective Date: August 2, 2026
Source: Official Journal of the European Union
CELEX Number: 32024R1689

Key Features

Dynamic Configuration System - All models adapt automatically to AI Act changes
Future-proof Design - No code updates needed for new terminology or requirements
Automatic Report Generation - Creates detailed compliance reports in Markdown format
Risk-based approach to AI regulation
Prohibited AI practices detection and analysis
High-risk AI system requirements and compliance checking
Transparency obligations monitoring
Market surveillance and enforcement tracking
Penalties for non-compliance analysis
Timestamped Reports - Track compliance progress over time

⚙️ Configuration

Server Configuration

The server uses mcp_server_config.json for configuration:

{
  "server": {
    "name": "ai-act-compliance",
    "version": "v0.2"
  },
  "logging": {
    "level": "INFO",
    "file": "logs/mcp_server.log"
  },
  "mcp": {
    "protocol_version": "2024-11-05"
  },
  "compliance": {
    "default_risk_level": "minimal-risk",
    "strict_mode": false
  }
}

Environment Variables

Copy env.example to .env and customize:

cp env.example .env

🔄 Keeping Up to Date

Automatic Updates

Startup Check: Server automatically checks data freshness on startup (7-day threshold)
Smart Caching: Only updates when content actually changes (hash-based detection)
Background Updates: Optional cron job for weekly automated updates
Content Hashing: Detects changes by comparing file hashes

Manual Updates

# Check and update manually
python scripts/update-ai-act.py

# Or use the bash wrapper
./scripts/check-updates.sh

# Set up automation (optional)
./scripts/setup-automation.sh

MCP Tool Updates

You can also update data directly through the MCP interface:

# Via MCP client
update_ai_act_data

Update Monitoring

Version tracking in data/ai-act/version.json
Automatic freshness checking on server startup
Detailed update logs and file size tracking
Manual update tool for on-demand refreshes

🏗️ Architecture

MCP Server Architecture Diagram

graph TB
    %% External Sources
    EU[🇪🇺 EU Official Sources<br/>EUR-Lex & Publications Office]
    
    %% Data Layer
    subgraph "📁 Data Layer"
        RAW[Raw AI Act Files<br/>HTML, PDF, Text]
        STRUCT[Structured Data<br/>JSON Files]
        VERSION[Version Tracking<br/>Hashes & Metadata]
    end
    
    %% Update System
    subgraph "🔄 Update System"
        UPDATE[Update Script<br/>update-ai-act.py]
        AUTO[Automation<br/>Cron Jobs]
        CHECK[Freshness Check<br/>7-day threshold]
    end
    
    %% Core Processing
    subgraph "⚙️ Core Processing"
        PARSER[AI Act Parser<br/>ai_act_parser.py]
        COMPLIANCE[Compliance Engine<br/>compliance_engine.py]
        REPORTING[Reporting System<br/>reporting_system.py]
    end
    
    %% MCP Server
    subgraph "🚀 MCP Server"
        SERVER[MCP Server<br/>mcp_server.py]
        
        subgraph "🛠️ MCP Tools"
            TOOL1[check_compliance]
            TOOL2[get_article]
            TOOL3[search_requirements]
            TOOL4[get_risk_assessment]
            TOOL5[update_ai_act_data]
        end
        
        subgraph "📚 MCP Resources"
            RES1[ai-act://articles]
            RES2[ai-act://chapters]
            RES3[ai-act://compliance-requirements]
        end
        
        subgraph "💬 MCP Prompts"
            PROMPT1[compliance_check]
            PROMPT2[risk_assessment]
            PROMPT3[requirements_analysis]
            PROMPT4[article_lookup]
        end
    end
    
    %% Client Layer
    subgraph "👥 Client Layer"
        CURSOR[🎯 Cursor IDE]
        VSCODE[🎯 VS Code]
        CLAUDE[🎯 Claude Desktop]
        OTHER[Other MCP Clients]
    end
    
    %% Data Flow Connections
    EU -->|Download| UPDATE
    UPDATE -->|Fetch & Parse| RAW
    UPDATE -->|Generate| VERSION
    RAW -->|Parse| PARSER
    PARSER -->|Structure| STRUCT
    
    %% Startup Flow
    SERVER -->|Startup Check| CHECK
    CHECK -->|If Stale| UPDATE
    CHECK -->|If Fresh| STRUCT
    
    %% Processing Flow
    STRUCT -->|Load| COMPLIANCE
    STRUCT -->|Load| REPORTING
    COMPLIANCE -->|Analysis| SERVER
    REPORTING -->|Reports| SERVER
    
    %% MCP Interface
    SERVER --> TOOL1
    SERVER --> TOOL2
    SERVER --> TOOL3
    SERVER --> TOOL4
    SERVER --> TOOL5
    SERVER --> RES1
    SERVER --> RES2
    SERVER --> RES3
    SERVER --> PROMPT1
    SERVER --> PROMPT2
    SERVER --> PROMPT3
    SERVER --> PROMPT4
    
    %% Client Connections
    TOOL1 --> CURSOR
    TOOL2 --> VSCODE
    TOOL3 --> CLAUDE
    TOOL4 --> OTHER
    TOOL5 --> CURSOR
    RES1 --> VSCODE
    RES2 --> CLAUDE
    RES3 --> OTHER
    PROMPT1 --> CURSOR
    PROMPT2 --> VSCODE
    PROMPT3 --> CLAUDE
    PROMPT4 --> OTHER
    
    %% Automation
    AUTO -->|Weekly| UPDATE
    
    %% Styling
    classDef external fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef data fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef update fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef core fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
    classDef mcp fill:#fff8e1,stroke:#f57f17,stroke-width:2px
    classDef client fill:#fce4ec,stroke:#880e4f,stroke-width:2px
    
    class EU external
    class RAW,STRUCT,VERSION data
    class UPDATE,AUTO,CHECK update
    class PARSER,COMPLIANCE,REPORTING core
    class SERVER,TOOL1,TOOL2,TOOL3,TOOL4,TOOL5,RES1,RES2,RES3,PROMPT1,PROMPT2,PROMPT3,PROMPT4 mcp
    class CURSOR,VSCODE,CLAUDE,OTHER client

Core Components

MCP Server (src/mcp_server.py) - Main server implementation
Compliance Engine (src/compliance_engine.py) - Compliance analysis logic
AI Act Parser (src/ai_act_parser.py) - Data parsing and structuring
Reporting System (src/reporting_system.py) - Report generation

Data Flow

Data Ingestion: EU sources → Update script → Raw files
Data Processing: Raw files → Parser → Structured data
Startup Check: Server checks data freshness (7-day threshold)
Compliance Analysis: Structured data → Compliance engine → Analysis
MCP Interface: Server exposes tools, resources, and prompts
Client Interaction: IDE clients query compliance status and get reports

📁 Source Code Structure

src/
├── models/           # Data models and classes
│   ├── __init__.py
│   ├── article.py    # AIActArticle dataclass
│   ├── chapter.py    # AIActChapter dataclass
│   ├── section.py    # AIActSection dataclass
│   ├── annex.py      # AIActAnnex dataclass
│   └── definition.py # AIActDefinition dataclass
├── parsers/          # Specialized parsers
│   ├── __init__.py
│   ├── article_parser.py      # Article parsing logic
│   ├── chapter_parser.py      # Chapter parsing logic
│   ├── annex_parser.py        # Annex parsing logic
│   ├── definition_parser.py   # Definition parsing logic
│   └── cross_reference_parser.py # Cross-reference parsing
├── utils/            # Utility classes and functions
│   ├── __init__.py
│   ├── risk_classifier.py     # Risk level classification
│   ├── text_processor.py      # Text processing utilities
│   └── compliance_matrix.py   # Compliance matrix management
├── data_preparation/ # Data preparation and analysis modules
│   ├── __init__.py
│   ├── data_fetchers/         # Data loading modules
│   │   ├── __init__.py
│   │   └── ai_act_data_fetcher.py
│   ├── parameter_generators/  # Dynamic parameter generation
│   │   ├── __init__.py
│   │   ├── compliance_parameter_generator.py
│   │   └── intelligent_parameter_resolver.py
│   └── compliance_analyzers/  # Compliance analysis engines
│       ├── __init__.py
│       ├── comprehensive_compliance_analyzer.py
│       └── smart_compliance_analyzer.py
├── ai_act_parser.py  # Main parser (orchestrates all modules)
├── compliance_engine.py # Compliance analysis engine
├── reporting_system.py # Report generation system
├── compliance_utils.py # Compliance utility functions
├── data_models.py    # Data model definitions
└── mcp_server.py     # MCP server implementation

🏗️ Architecture Benefits

Modularity

Single Responsibility: Each module has a clear, focused purpose
Easy Testing: Individual components can be tested in isolation
Maintainability: Changes to one component don't affect others

Extensibility

New Parsers: Easy to add new parsing logic (e.g., for different document types)
New Models: Simple to add new data structures
New Utilities: Straightforward to add helper functions

AWP Integration

Migration Strategy: Automatic generation of AWP-compatible migration backlogs
Project Directory Detection: Smart detection of user project directories
Environment Variable Support: Configurable project directory targeting
Fallback Support: Works with or without MCP-Agentic-SDLC

Open Source Friendly

Clear Structure: New contributors can quickly understand the codebase
Documentation: Each module is well-documented
Type Hints: Full type annotations for better IDE support

📊 Data Models

`AIActArticle`

Represents an individual article from the AI Act with:

Basic properties (number, title, content)
Risk classification and keywords
Cross-references to related articles
Utility methods (word count, validation)

`AIActChapter`

Represents a chapter containing multiple articles with:

Chapter metadata
List of contained articles
Statistics and analysis methods

`AIActAnnex`

Represents an annex with:

Dynamic categorization (prohibited_practices, high_risk_systems, transparency_requirements, etc.)
Configuration-driven importance classification using annex_config.json
Content-based analysis with keyword and pattern matching
Future-proof design that adapts to new annex types automatically
Content analysis methods

`AIActDefinition`

Represents a definition with:

Dynamic categorization (ai_system, stakeholder, risk_classification, compliance, technical, data)
Configuration-driven classification using definition_config.json
Content-based analysis with keyword and pattern matching
Future-proof design that adapts to new terminology automatically
Article attribution and content analysis methods

🔧 Specialized Parsers

`ArticleParser`

Parses articles from raw text
Validates article structure
Provides statistics and filtering methods

`ChapterParser`

Parses chapters and associates articles
Handles chapter-article relationships
Provides chapter-level statistics

`AnnexParser`

Extracts annexes from text
Handles non-breaking spaces and formatting
Categorizes annexes by content

`DefinitionParser`

Extracts definitions using pattern matching
Filters and cleans definition data
Categorizes definitions automatically

`CrossReferenceParser`

Finds references between articles
Builds reference networks
Validates cross-reference integrity

🛠️ Utility Classes

`RiskClassifier`

Classifies content by risk level (prohibited, high_risk, limited_risk, minimal_risk)
Uses keyword matching and pattern recognition
Provides context-based classification rules

`TextProcessor`

Handles text cleaning and normalization
Extracts structured data using regex patterns
Provides content analysis utilities

`ComplianceMatrix`

Dynamic configuration using article_mappings.json
Manages AI system categorization
Maps system types to requirements
Provides classification and lookup methods

🔧 Dynamic Configuration System

All models use configuration-driven classification instead of hardcoded values:

Configuration Files

data/structured/article_mappings.json - Article risk levels and compliance mappings
data/structured/annex_config.json - Annex categories and importance levels
data/structured/definition_config.json - Definition categories and classification rules
data/structured/section_config.json - Section types and risk keyword detection

Benefits

Future-proof: Automatically adapts to AI Act changes
No code updates needed: Just update JSON configuration files
Content-based: Uses keywords and patterns for intelligent classification
Fallback systems: Works even if configuration files are missing
Easy maintenance: Non-technical users can update classifications

Example: Adding New Terminology

// In definition_config.json
{
  "category_mapping": {
    "quantum_ai": {
      "keywords": ["quantum", "quantum computing", "quantum algorithm"],
      "patterns": ["quantum.*ai", "quantum.*system"]
    }
  }
}

The system automatically recognizes new terminology without code changes!

📁 Project Structure

mcp-ai-act/
├── src/                    # Source code
│   ├── mcp_server.py      # Main MCP server
│   ├── compliance_engine.py
│   ├── ai_act_parser.py
│   ├── reporting_system.py
│   ├── compliance_utils.py
│   ├── data_models.py
│   ├── models/            # Data models
│   ├── parsers/           # Specialized parsers
│   ├── utils/             # Utility classes
│   └── data_preparation/  # Data preparation modules
├── data/                   # AI Act data
│   ├── ai-act/            # Raw AI Act files
│   └── structured/        # Parsed structured data
│       ├── articles.json  # Parsed articles
│       ├── chapters.json  # Parsed chapters
│       ├── compliance_requirements.json
│       ├── article_mappings.json  # Dynamic article mappings
│       ├── annex_config.json      # Dynamic annex configuration
│       ├── definition_config.json # Dynamic definition configuration
│       └── section_config.json    # Dynamic section configuration
├── client/                # Web client interface
│   ├── web_client.py     # Web server
│   ├── static/           # CSS, JS, images
│   ├── templates/        # HTML templates
│   └── config/           # Client configuration
├── resources/             # Project resources
│   ├── templates/         # Report templates
│   ├── test_cases/        # Compliance test cases
│   └── benchmarks/        # Performance benchmarks
├── scripts/               # Update scripts
├── logs/                 # Server logs
├── mcp_server_config.json # Server configuration
├── env.example           # Environment variables template
└── requirements.txt      # Python dependencies

🎯 IDE Integration

🚀 Quick Setup (3 steps)

Test the Server:

cd /Users/michaelwybraniec/Documents/GitHub/mcp-ai-act
source venv/bin/activate
python test_server.py

Add MCP Configuration to your IDE (see below)
Restart IDE and Start Using!

🎯 Cursor Setup

Add this to your Cursor MCP settings:

{
  "mcpServers": {
    "ai-act-compliance": {
      "command": "/<path-to-your>/mcp-ai-act/venv/bin/python",
      "args": [
        "/<path-to-your>/mcp-ai-act/src/mcp_server.py"
      ],
      "env": {
        "PYTHONPATH": "/<path-to-your>/mcp-ai-act/src"
      }
    }
  }
}

Replace /<path-to-your>/mcp-ai-act/ with your actual project path.

🎯 VS Code Setup

Add this to your VS Code settings (settings.json):

{
  "mcp.servers": {
    "ai-act-compliance": {
      "command": "/<path-to-your>/mcp-ai-act/venv/bin/python",
      "args": [
        "/<path-to-your>/mcp-ai-act/src/mcp_server.py"
      ],
      "env": {
        "PYTHONPATH": "/<path-to-your>/mcp-ai-act/src"
      }
    }
  }
}

Replace /<path-to-your>/mcp-ai-act/ with your actual project path.

Or use the included workspace settings (.vscode/settings.json)

🎯 Claude Desktop Setup

Add this to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "ai-act-compliance": {
      "command": "/<path-to-your>/mcp-ai-act/venv/bin/python",
      "args": [
        "/<path-to-your>/mcp-ai-act/src/mcp_server.py"
      ],
      "env": {
        "PYTHONPATH": "/<path-to-your>/mcp-ai-act/src"
      }
    }
  }
}

Replace /<path-to-your>/mcp-ai-act/ with your actual project path.

🎯 Usage Examples

What You Can Ask

Compliance Analysis:

"Check if my AI system is compliant with the EU AI Act" → Generates detailed compliance report with AWP integration
"Is my chatbot compliant with EU AI Act?" → Creates session-specific report directory
"Check compliance for my credit scoring AI" → Saves comprehensive analysis report
"Prepare migration backlog for my AI system" → Generates AWP-compatible migration strategy

Direct Data Access:

"Show me all AI Act articles" → Access ai-act://articles resource
"Browse the AI Act chapters" → Access ai-act://chapters resource
"Get the compliance requirements matrix" → Access ai-act://compliance-requirements resource

Specific Information:

"What are the requirements for high-risk AI systems?"
"Get me Article 5 of the AI Act"
"Assess the risk level of my facial recognition system"
"Search for transparency requirements in the AI Act"

Migration Management:

"Generate migration backlog from my compliance report"
"Create AWP-compatible project structure"
"Prepare compliance migration strategy"

Example Results

Chatbot → LIMITED_RISK (58.0/10 compliance score) + Detailed report saved
Facial Recognition → HIGH_RISK (6.0/10 compliance score) + Comprehensive analysis report
Credit Scoring → HIGH_RISK (6.0/10 compliance score) + Full compliance report

For AI Developers

"Is my chatbot compliant with EU AI Act?"
"What compliance requirements apply to my credit scoring AI?"
"Check compliance for my facial recognition system"

For Legal Teams

"Get Article 13 about high-risk AI systems"
"What are the transparency requirements for AI systems?"
"Search for requirements about automated decision making"

For Compliance Teams

"Assess risk level of my AI system"
"What documentation do I need for high-risk AI?"
"Find all articles related to biometric identification"

📚 Accessing MCP Resources

Direct Data Access

Your MCP server exposes the complete AI Act data as resources that you can access directly:

Available Resources:

Core AI Act Data:

ai-act://articles - Complete article database
- All 167 AI Act articles
- Full text, metadata, and classifications
- Risk levels and compliance requirements
ai-act://chapters - Chapter structure
- All 5 AI Act chapters
- Article organization and hierarchy
- Chapter-level summaries
ai-act://compliance-requirements - Compliance matrix
- Risk-based requirements mapping
- Applicable articles by system type
- Compliance checklists

Project Resources:

ai-act://test-cases - Compliance test cases
- Validation scenarios for testing
- Edge cases and error handling
- Automated test data
ai-act://compliance-template - Report template
- Standardized report format
- Consistent compliance documentation
- Professional report structure
ai-act://quick-reference - AI Act quick reference
- Compliance guide and overview
- Key requirements summary
- Quick lookup information
ai-act://benchmarks - Performance benchmarks
- Test scenarios and criteria
- Performance expectations
- Validation standards

How to Access Resources:

In Cursor IDE:

MCP Panel: Look for "MCP" or "Resources" in the sidebar
Command Palette: Cmd+Shift+P → Search "MCP" → "List Resources"
AI Chat: Ask "Show me the available MCP resources" or "Browse ai-act://articles"

In VS Code:

MCP Extension: Install MCP extension and check Explorer panel
Command Palette: Ctrl+Shift+P → Search "MCP" → "List Resources"

Via AI Assistant:

Simply ask the AI to show you the resources:

"Show me all AI Act articles" → Accesses ai-act://articles
"Browse the AI Act chapters" → Accesses ai-act://chapters
"Get the compliance requirements matrix" → Accesses ai-act://compliance-requirements
"Show me the test cases" → Accesses ai-act://test-cases
"Get the compliance report template" → Accesses ai-act://compliance-template
"Show me the AI Act quick reference" → Accesses ai-act://quick-reference
"Get the performance benchmarks" → Accesses ai-act://benchmarks

Via MCP Client (Advanced):

# List available resources
mcp list-resources

# Read specific resource
mcp read-resource ai-act://articles
mcp read-resource ai-act://chapters
mcp read-resource ai-act://compliance-requirements
mcp read-resource ai-act://test-cases
mcp read-resource ai-act://compliance-template
mcp read-resource ai-act://quick-reference
mcp read-resource ai-act://benchmarks

Resource Benefits:

📊 Complete Data Access - Full AI Act database at your fingertips
🔍 Direct Browsing - No need to use tools for data exploration
📋 Structured Format - JSON format for easy parsing and analysis
🔄 Always Current - Automatically updated with latest AI Act data
💾 Offline Access - Works without internet connection

📊 Compliance Report Generation

Automatic Report Creation

When you use the check_compliance tool, the MCP server automatically

Analyzes your project using the AI Act compliance engine
Generates a detailed report in Markdown format
Creates a new session directory for each app consumption
Saves the report to the session-specific directory
Returns analysis results with report path
Creates AWP-compatible migration files for project management

AWP Integration

The server now includes Agentic Workflow Protocol (AWP) integration for seamless project management:

Migration Strategy Generation

Automatic AWP Files: Creates base.md and README.md files compatible with MCP-Agentic-SDLC
Project Directory Detection: Smart detection of user project directories using environment variables
Migration Backlog: Generates structured migration backlogs from compliance analysis
Fallback Support: Works with or without MCP-Agentic-SDLC installed

Directory Structure

When you run compliance analysis, the server creates:

your-project/
└── mcp-ai-act/
    ├── session-<timestamp>/
    │   └── report-analysis/
    │       ├── report_<timestamp>.json
    │       └── report_<timestamp>.md
    ├── migration-strategy/
    │   └── awp/
    │       ├── base.md          # AWP-compatible project questions
    │       └── README.md        # Installation and usage instructions
    └── feedback-data/
        ├── feedback_<session>.json
        └── README.md

AWP Workflow

Run Compliance Check: Use check_compliance tool
Generate Migration Backlog: Use prepare_migration_backlog tool
Install MCP-Agentic-SDLC: Follow instructions in generated README.md
Use AWP Tools: Use base and init tools for structured project management

📖 For detailed AWP integration instructions, see

Report Structure

Each compliance report includes:

📋 Executive Summary - High-level compliance assessment
🎯 Risk Assessment - Detailed risk level analysis
📊 Compliance Score - Numerical compliance rating (0-10)
📝 Applicable Articles - Relevant AI Act provisions
✅ Requirements - Specific compliance requirements
💡 Recommendations - Actionable next steps
🔍 Detailed Analysis - Comprehensive project analysis
📄 Project Information - Complete project details

Report Location

Reports are saved in session-specific directories to avoid conflicts:

mcp-ai-act/
└── compliance_reports/
    ├── session_a1b2c3d4_20240928_145103/
    │   ├── report_20240928_145103.json
    │   └── report_20240928_145103.md
    ├── session_e5f6g7h8_20240928_150230/
    │   ├── report_20240928_150230.json
    │   └── report_20240928_150230.md
    └── session_i9j0k1l2_20240928_151545/
        ├── report_20240928_151545.json
        └── report_20240928_151545.md

Report Benefits

📈 Track Progress - Compare compliance over time
📋 Documentation - Maintain compliance records
🔄 Version Control - Timestamped reports for audit trails
📊 Analysis - Detailed compliance insights
💼 Professional - Ready for legal and compliance teams

🔧 Troubleshooting

Common Issues

Server won't start:
- Make sure virtual environment is activated: source venv/bin/activate
- Check Python path is correct in the MCP configuration
- Verify all dependencies are installed: pip install -r requirements.txt
MCP not connecting:
- Use full Python path: Use /<path-to-your>/mcp-ai-act/venv/bin/python instead of just python
- Point to mcp_server.py: Use /<path-to-your>/mcp-ai-act/src/mcp_server.py not start_server.py
- Restart IDE completely: Quit and reopen Cursor/VS Code after configuration changes
- Check MCP logs: Open Developer Tools in Cursor to see connection errors
LLM generating incorrect compliance reports:
- Fixed in v0.2.1: This issue has been resolved with enhanced response format
- Verify server version: Make sure you're running v0.2.1 or later
- Check response format: LLM should now see structured compliance data at the top of responses
- Restart MCP server: Restart the server to load the latest fixes

Test the server:

# Test server functionality
python test_server.py

# Test compliance analysis
python -c "
import sys; sys.path.append('src')
from compliance_engine import ComplianceEngine
from pathlib import Path
engine = ComplianceEngine(Path('data/structured'))
print('✅ Server working!')
"

Compliance reports not generating:
- Check permissions: Ensure the MCP server can write to the project directory
- Verify directory creation: Session-specific directories under mcp-ai-act/ should be created automatically
- Check server logs: Look for report generation messages in logs/mcp_server.log
- Test manually: Use the compliance check tool and verify the report path is returned
- Project directory detection: Check if the server is detecting your project directory correctly
MCP resources not visible:
- Check MCP connection: Ensure the MCP server is properly connected in your IDE
- Restart IDE: Sometimes MCP resources need a restart to appear
- Use AI chat: Ask "Show me available MCP resources" or "List AI Act resources"
- Check command palette: Look for MCP-related commands in your IDE
- Verify server status: Make sure the MCP server is running and connected
AWP integration issues:
- Check project directory: Ensure the server is detecting your project directory correctly
- Environment variables: Set MCP_USER_PROJECT_DIR to your project directory if auto-detection fails
- Directory permissions: Ensure the MCP server can create directories in your project
- AWP files not created: Check if migration-strategy/awp/ directory is created with base.md and README.md
- MCP-Agentic-SDLC not found: The system will create fallback files if AWP is not available

🚀 Development Usage

Basic Usage

from src.ai_act_parser import AIActParser
from pathlib import Path

# Initialize parser
data_dir = Path("data/ai-act")
parser = AIActParser(data_dir)

# Parse AI Act
compliance_data = parser.parse_ai_act()

# Get summary
summary = parser.get_summary()
print(f"Parsed {summary['articles']['total']} articles")

Using Individual Components

from src.models import AIActArticle
from src.parsers import ArticleParser
from src.utils import RiskClassifier

# Use individual components
classifier = RiskClassifier()
risk_level = classifier.classify_risk_level("AI system content...")

parser = ArticleParser()
articles = parser.parse_articles(content)

🧪 Testing

Each module can be tested independently:

# Test individual parser
from src.parsers.article_parser import ArticleParser
parser = ArticleParser()
articles = parser.parse_articles(content)
assert parser.validate_articles(articles)

# Test utility
from src.utils.risk_classifier import RiskClassifier
classifier = RiskClassifier()
risk = classifier.classify_risk_level("high-risk AI system")
assert risk == "high_risk"

📈 Performance

The modular structure provides:

Better Memory Usage: Only load needed components
Faster Development: Work on individual modules
Easier Debugging: Isolate issues to specific modules
Parallel Development: Multiple developers can work on different modules

🔄 Migration from Monolithic Parser

The old monolithic ai_act_parser.py (1000+ lines) has been replaced with:

8 focused modules (50-200 lines each)
Clear separation of concerns
Better testability
Improved maintainability

🔧 Development

Running Tests

# Test the server
python test_server.py

# Test individual components
python -c "from src.mcp_server import AIActComplianceServer; print('Server loads successfully')"

Adding New Features

Update the MCP server with new tools/resources
Add corresponding handlers
Update configuration if needed
Test with MCP clients

🤝 Contributing

When contributing to this codebase:

Follow the modular structure - don't add everything to one file
Add type hints - all functions should have proper type annotations
Write tests - each module should have corresponding tests
Update documentation - keep this README and module docstrings current
Use the existing patterns - follow the established conventions

📝 Future Enhancements

Potential areas for extension:

New Document Types: Add parsers for other legal documents
Advanced NLP: Integrate more sophisticated text analysis
Caching: Add caching for expensive parsing operations
API: Create REST API for the parsing functionality
Visualization: Add tools for visualizing the parsed data

📚 Sources

📄 License

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

📞 Support

For issues and questions:

Check the Issues page
Review the server logs in logs/mcp_server.log
Check the update logs in logs/update.log (if automation is set up)
Test the server functionality with python test_server.py
Verify MCP configuration in your IDE settings