Contributing to AIDEFEND MCP Service

Thank you for your interest in contributing to the AIDEFEND MCP Service! This guide will help you get started with development.

Development Setup

Prerequisites

Python 3.10 - 3.14
Node.js 18+ (for JavaScript parsing)
Git

Setup Development Environment

Clone the repository:

git clone https://github.com/edward-playground/aidefend-mcp.git
cd aidefend-mcp

Install dependencies:
```
# Install production dependencies
pip install -r requirements.txt

# Install development dependencies
pip install -r requirements-dev.txt
```
Acorn is vendored for runtime use, so contributors do not need to run npm during ordinary setup. Run npm ci only when intentionally refreshing or verifying the vendored parser dependency.

Configure environment:

cp .env.example .env
# Edit .env as needed for development

Run initial sync:
```
python __main__.py
```

Development Workflow

Running Tests

# Run all tests
pytest

# Run specific test file
pytest tests/test_parser.py

# Run with coverage
pytest --cov=app --cov-report=html

# Run only unit tests
pytest -m unit

# Run only integration tests
pytest -m integration

# Skip slow tests
pytest -m "not slow"

Code Quality

Format the files you change:

black path/to/changed_file.py
isort path/to/changed_file.py

Fatal Python static checks used by the release audit:

python -m flake8 app mcp_server.py __main__.py scripts tests --select=E9,F63,F7,F82

The repository does not currently use mypy as a release gate. Add and maintain accurate type annotations in changed code, but do not treat a clean whole-repository mypy app/ run as an existing project guarantee.

Security scanning:

# Static security analysis for production code
python -m bandit -q -r app mcp_server.py __main__.py

# Dependency vulnerability scanning
python -m pip_audit -r requirements-dev.txt

Running the Service Locally

REST API mode:

python __main__.py
# Access at: http://localhost:8000
# API docs: http://localhost:8000/docs

MCP mode:

python __main__.py --mcp

Force resync:

python __main__.py --resync

Project Structure

aidefend-mcp/
├── __main__.py              # Source-checkout CLI compatibility shim
├── mcp_server.py            # MCP protocol server
├── parse_js_module.mjs      # JavaScript parser (Node.js)
├── app/
│   ├── __init__.py          # Canonical Python package and version
│   ├── cli.py               # Installed console-script implementation
│   ├── main.py              # FastAPI REST API
│   ├── core.py              # QueryEngine (shared by both modes)
│   ├── sync.py              # Background sync service
│   ├── framework_manifest.py    # Source and index manifest validation
│   ├── framework_migrations.py  # Framework edition migration registry
│   ├── framework_utils.py       # Framework normalization helpers
│   ├── generation_identity.py   # Physical index-generation identity
│   ├── instance_lock.py         # Cross-process DATA_PATH ownership
│   ├── config.py            # Configuration management
│   ├── schemas.py           # REST and tool response contracts
│   ├── security.py          # Input validation and security
│   ├── audit.py             # Audit logging
│   ├── logger.py            # Structured logging
│   ├── chunking.py          # Smart text chunking
│   ├── embedding_cache.py   # Embedding cache system
│   ├── threat_keywords.py   # Static threat-classification vocabulary
│   ├── utils.py             # Parser and durable filesystem utilities
│   └── tools/               # P0 specialized tools
│       ├── statistics.py
│       ├── validation.py
│       ├── technique_detail.py
│       ├── defenses_for_threat.py
│       ├── code_snippets.py
│       ├── coverage_analysis.py
│       ├── compliance_mapping.py
│       ├── quick_reference.py
│       ├── threat_coverage.py
│       ├── implementation_plan.py
│       ├── classify_threat.py
│       ├── comprehensive_search.py
│       ├── security_posture.py
│       ├── technique_comparison.py
│       └── incident_response.py
├── tests/                   # Test suite
├── scripts/                 # Utility scripts
├── docs/                    # Additional documentation
└── data/                    # Runtime data (logs, database)

Adding New Features

Adding a New P0 Tool

Create tool function in app/tools/your_tool.py:

async def your_new_tool(param1: str, param2: int = 5) -> Dict[str, Any]:
    """Tool logic here."""
    from app.core import query_engine
    await query_engine.initialize()

    # Perform operations
    results = await query_engine.search(...)

    return {"results": results, "total": len(results)}

Add REST API endpoint in app/main.py:

@app.post("/api/v1/your-tool")
async def your_tool_endpoint(param1: str, param2: int = 5):
    result = await your_new_tool(param1, param2)
    return result

Add MCP tool handler in mcp_server.py:
- Add tool definition in list_tools()
- Add handler in call_tool()
- Create handle_your_new_tool() async function
Add tests in tests/test_your_tool.py
Update documentation in docs/TOOLS.md

Testing Guidelines

Writing Tests

Use pytest for all tests
Place tests in tests/ directory
Name test files as test_*.py
Use descriptive test names: test_feature_behavior_expected_outcome

Test Markers

import pytest

@pytest.mark.unit
def test_validation_logic():
    ...

@pytest.mark.integration
async def test_full_query_flow():
    ...

@pytest.mark.slow
def test_large_dataset():
    ...

Test Coverage

Aim for 80%+ code coverage
Focus on critical paths and edge cases
Test error handling and validation

Security

Security Scanning

This repository includes automated security scanning via GitHub Actions:

Automated scans run on:

Every push to main or develop branches
All pull requests
Weekly schedule (Mondays at 00:00 UTC)

Security tools:

Bandit: Static security analysis for Python code
Safety: Dependency vulnerability scanning
CodeQL: Advanced semantic code analysis

Reporting Security Issues

Please see SECURITY.md for vulnerability reporting procedures.

Security Best Practices

Input validation: Always validate and sanitize user inputs
No external APIs: Keep all processing local and private
Path traversal prevention: Validate file paths
Rate limiting: Implement rate limits on new endpoints
Audit logging: Log all sensitive operations

Code Style

Python Style

Follow PEP 8 with the following specifics:

Line length: 100 characters max
Indentation: 4 spaces
String quotes: Double quotes preferred
Type hints: Use type hints for all function signatures
Docstrings: Google-style docstrings

Example:

async def search_techniques(
    query: str,
    top_k: int = 5,
    filters: Optional[Dict[str, Any]] = None
) -> Dict[str, Any]:
    """
    Search AIDEFEND techniques using semantic search.

    Args:
        query: Natural language search query
        top_k: Number of results to return
        filters: Optional filtering criteria

    Returns:
        Dictionary with search results and metadata

    Raises:
        ValidationError: If query is invalid
    """
    ...

Formatting

Use automated formatters:

black app/      # Auto-format code
isort app/      # Sort imports

Commit Messages

Follow Conventional Commits:

feat: New feature
fix: Bug fix
docs: Documentation changes
test: Test additions or changes
refactor: Code refactoring
perf: Performance improvements
chore: Maintenance tasks

Examples:

feat: add incident response playbook generator
fix: resolve sync lock conflicts
docs: update configuration guide
test: add coverage for chunked search

Pull Request Process

Fork the repository and create a feature branch
Make your changes following code style guidelines
Add tests for new functionality
Run tests and ensure they pass
Update documentation as needed
Submit pull request with clear description

PR Checklist

Tests added/updated and passing
Documentation updated
Changed Python files formatted with black and isort
Fatal Python static checks pass (flake8 --select=E9,F63,F7,F82)
Type annotations updated where the changed interfaces require them
Production-code security scan passes (bandit)
Commit messages follow convention

Community

Getting Help

Issues: GitHub Issues
Discussions: GitHub Discussions (if enabled)
Security: SECURITY.md for vulnerability reporting

Code of Conduct

Be respectful and inclusive
Welcome newcomers
Focus on constructive feedback
Maintain a harassment-free environment

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to AIDEFEND MCP Service! 🚀

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History