policygate

Policygate is an MCP server gateway for task-specific AI rules and scripts stored in a GitHub repository.

Features

• Syncs repository content into a local cache at ~/.policygate/repo_data
• Parses and validates router.yaml
• Exposes MCP tools:
  • sync_repository
  • outline_router
  • read_rules
  • copy_scripts

Detailed usage reference: docs/REFERENCE.md

Required repository structure

rules/
scripts/
router.yaml

router.yaml structure:

tasks:
    task1:
        description: "Short description of task 1"
        rules:
            - rule1
        scripts:
            - script1

rules:
    rule1:
        path: rules/rule1.md
        description: "Short description of rule 1"

scripts:
    script1:
        path: scripts/script1.py
        description: "Short description of script 1"

Configuration

Set environment variables:

• POLICYGATE__GITHUB_REPOSITORY_URL
• POLICYGATE__GITHUB_ACCESS_TOKEN
• POLICYGATE__LOCAL_REPO_DATA_DIR (optional, default ~/.policygate/repo_data)
• POLICYGATE__REPOSITORY_REFRESH_INTERVAL_SECONDS (optional, default 1800)
• POLICYGATE__LOG_LEVEL (optional, default INFO)
• POLICYGATE__LOG_FILE_PATH (optional, default ~/.policygate/policygate.log)

Run MCP server

Run with:

uv run policygate-mcp

VS Code workspace MCP config example (.vscode/mcp.json):

{
    "inputs": [
        {
            "id": "POLICYGATE__GITHUB_REPOSITORY_URL",
            "type": "promptString",
            "description": "GitHub repository URL",
            "password": false
        },
        {
            "id": "POLICYGATE__GITHUB_ACCESS_TOKEN",
            "type": "promptString",
            "description": "GitHub access token",
            "password": true
        }
    ],
    "servers": {
        "policygate": {
            "type": "stdio",
            "command": "uvx",
            "args": ["--from", "policygate@latest", "policygate-mcp"],
            "env": {
                "POLICYGATE__GITHUB_REPOSITORY_URL": "${input:POLICYGATE__GITHUB_REPOSITORY_URL}",
                "POLICYGATE__GITHUB_ACCESS_TOKEN": "${input:POLICYGATE__GITHUB_ACCESS_TOKEN}"
            },
        }
    }
}

For local testing from the current workspace (after uv sync --all-groups):

{
    "inputs": [
        {
            "id": "POLICYGATE__GITHUB_REPOSITORY_URL",
            "type": "promptString",
            "description": "GitHub repository URL",
            "password": false
        },
        {
            "id": "POLICYGATE__GITHUB_ACCESS_TOKEN",
            "type": "promptString",
            "description": "GitHub access token",
            "password": true
        }
    ],
    "servers": {
        "policygate-local": {
            "type": "stdio",
            "command": "uv",
            "args": ["run", "policygate-mcp"],
            "env": {
                "POLICYGATE__GITHUB_REPOSITORY_URL": "${input:POLICYGATE__GITHUB_REPOSITORY_URL}",
                "POLICYGATE__GITHUB_ACCESS_TOKEN": "${input:POLICYGATE__GITHUB_ACCESS_TOKEN}"
            },
            "cwd": "${workspaceFolder}"
        }
    }
}

Testing

Run feature-organized end-to-end suites:

uv run pytest --maxfail=1 --tb=short