policygate 0.1.0__tar.gz

policygate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sergei Konovalov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

policygate-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.3
+Name: policygate
+Version: 0.1.0
+Summary: MCP server gateway for task-specific AI rules and scripts stored in GitHub
+Keywords: mcp,policy,gateway,ai,github,automation
+Author: Sergei Konovalov
+License: MIT License
+         
+         Copyright (c) 2025 Sergei Konovalov
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: structlog>=25.1.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyyaml>=6.0.0
+Maintainer: Sergei Konovalov
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/l0kifs/policygate
+Project-URL: Repository, https://github.com/l0kifs/policygate
+Project-URL: Issues, https://github.com/l0kifs/policygate/issues
+Description-Content-Type: text/markdown
+
+<p align="center">
+	<img src="https://capsule-render.vercel.app/api?type=waving&color=0:4F46E5,100:06B6D4&height=200&section=header&text=policygate&fontSize=56&fontColor=ffffff&animation=fadeIn&fontAlignY=38&desc=MCP%20server%20gateway%20for%20task-specific%20AI%20rules%20and%20scripts&descAlignY=58&descSize=16" alt="policygate banner" />
+</p>
+
+<p align="center">
+	<a href="https://github.com/l0kifs/policygate/actions/workflows/publish-to-pypi.yml"><img src="https://img.shields.io/github/actions/workflow/status/l0kifs/policygate/publish-to-pypi.yml?branch=main&label=publish" alt="Publish workflow" /></a>
+	<a href="https://pypi.org/project/policygate/"><img src="https://img.shields.io/pypi/v/policygate" alt="PyPI version" /></a>
+	<a href="https://pypi.org/project/policygate/"><img src="https://img.shields.io/pypi/pyversions/policygate" alt="Python versions" /></a>
+	<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license" /></a>
+</p>
+
+# 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](docs/REFERENCE.md)
+
+## Required repository structure
+
+```text
+rules/
+scripts/
+router.yaml
+```
+
+`router.yaml` structure:
+
+```yaml
+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 `60`)
+
+## Run MCP server
+
+Run with:
+
+```bash
+uv run policygate-mcp
+```
+
+VS Code workspace MCP config example (`.vscode/mcp.json`):
+
+```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`):
+
+```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-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:
+
+```bash
+uv run pytest --maxfail=1 --tb=short
+```

policygate-0.1.0/README.md

@@ -0,0 +1,146 @@
+<p align="center">
+	<img src="https://capsule-render.vercel.app/api?type=waving&color=0:4F46E5,100:06B6D4&height=200&section=header&text=policygate&fontSize=56&fontColor=ffffff&animation=fadeIn&fontAlignY=38&desc=MCP%20server%20gateway%20for%20task-specific%20AI%20rules%20and%20scripts&descAlignY=58&descSize=16" alt="policygate banner" />
+</p>
+
+<p align="center">
+	<a href="https://github.com/l0kifs/policygate/actions/workflows/publish-to-pypi.yml"><img src="https://img.shields.io/github/actions/workflow/status/l0kifs/policygate/publish-to-pypi.yml?branch=main&label=publish" alt="Publish workflow" /></a>
+	<a href="https://pypi.org/project/policygate/"><img src="https://img.shields.io/pypi/v/policygate" alt="PyPI version" /></a>
+	<a href="https://pypi.org/project/policygate/"><img src="https://img.shields.io/pypi/pyversions/policygate" alt="Python versions" /></a>
+	<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license" /></a>
+</p>
+
+# 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](docs/REFERENCE.md)
+
+## Required repository structure
+
+```text
+rules/
+scripts/
+router.yaml
+```
+
+`router.yaml` structure:
+
+```yaml
+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 `60`)
+
+## Run MCP server
+
+Run with:
+
+```bash
+uv run policygate-mcp
+```
+
+VS Code workspace MCP config example (`.vscode/mcp.json`):
+
+```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`):
+
+```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-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:
+
+```bash
+uv run pytest --maxfail=1 --tb=short
+```

policygate-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["uv_build>=0.9.30"]
+build-backend = "uv_build"
+
+[project]
+name = "policygate"
+version = "0.1.0"
+description = "MCP server gateway for task-specific AI rules and scripts stored in GitHub"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+authors = [
+    { name = "Sergei Konovalov" },
+]
+maintainers = [
+    { name = "Sergei Konovalov" },
+]
+keywords = [
+    "mcp",
+    "policy",
+    "gateway",
+    "ai",
+    "github",
+    "automation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    # Configuration and logging
+    "pydantic-settings>=2.0.0",
+    "structlog>=25.1.0",
+
+    # Data validation
+    "pydantic>=2.0.0",
+
+    # MCP and integration
+    "fastmcp>=2.0.0",
+    "httpx>=0.27.0",
+    "pyyaml>=6.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/l0kifs/policygate"
+Repository = "https://github.com/l0kifs/policygate"
+Issues = "https://github.com/l0kifs/policygate/issues"
+
+[project.scripts]
+policygate-mcp = "policygate.entry_points.mcp_server:run"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.0",
+    "pytest-xdist>=3.0.0",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.14.5",
+    "ty>=0.0.11",
+]
+
+[tool.uv]
+package = true

policygate-0.1.0/src/policygate/__init__.py

@@ -0,0 +1,3 @@
+"""
+Project package root.
+"""

policygate-0.1.0/src/policygate/config/__init__.py

@@ -0,0 +1,9 @@
+"""
+Project configuration package.
+
+Rules:
+- Contains application settings, constants, and logging configuration.
+- No technical implementation details (database engines, clients, etc.).
+- No business logic.
+- Should not import from domains, infrastructure or entry_points.
+"""

policygate-0.1.0/src/policygate/config/settings.py

@@ -0,0 +1,48 @@
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """
+    Configuration settings.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="POLICYGATE__",
+        env_nested_delimiter="__",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # Application settings
+    app_name: str = Field(default="policygate", description="Application name")
+    app_version: str = Field(default="0.1.0", description="Application version")
+
+    # GitHub repository integration
+    github_repository_url: str = Field(
+        default="",
+        description="GitHub repository URL containing router.yaml, rules/, and scripts/",
+    )
+    github_access_token: str = Field(
+        default="",
+        description="GitHub access token for repository access",
+    )
+
+    # Local repository cache
+    local_repo_data_dir: str = Field(
+        default="~/.policygate/repo_data",
+        description="Local repository cache path",
+    )
+    repository_refresh_interval_seconds: int = Field(
+        default=1800,
+        description="Minimal interval between remote refresh checks",
+    )
+
+
+def get_settings() -> Settings:
+    """
+    Get configuration settings.
+    """
+    return Settings()

policygate-0.1.0/src/policygate/domains/__init__.py

@@ -0,0 +1,10 @@
+"""
+Domain layer containing business logic.
+
+Rules:
+- Pure Python code (no framework dependencies).
+- Contains entities, value objects, and domain services.
+- Models may use Pydantic for validation.
+- Logging via available logging libraries is allowed.
+- No imports from infrastructure or entry_points.
+"""

policygate-0.1.0/src/policygate/domains/gateway/__init__.py

@@ -0,0 +1 @@
+"""Gateway domain package."""

policygate-0.1.0/src/policygate/domains/gateway/exceptions.py

@@ -0,0 +1,17 @@
+"""Domain exceptions for policy gateway flows."""
+
+
+class PolicyGateError(Exception):
+    """Base exception for gateway operations."""
+
+
+class RouterValidationError(PolicyGateError):
+    """Raised when router.yaml content is invalid."""
+
+
+class RouterReferenceError(PolicyGateError):
+    """Raised when requested aliases are missing in router.yaml."""
+
+
+class RepositorySyncError(PolicyGateError):
+    """Raised when repository sync cannot complete."""

policygate-0.1.0/src/policygate/domains/gateway/models.py

@@ -0,0 +1,40 @@
+"""Domain models for repository routing configuration."""
+
+from pydantic import BaseModel, Field
+
+
+class TaskConfig(BaseModel):
+    """Task mapping in router configuration."""
+
+    description: str = Field(description="Task description")
+    rules: list[str] = Field(default_factory=list, description="Rule aliases")
+    scripts: list[str] = Field(default_factory=list, description="Script aliases")
+
+
+class RuleConfig(BaseModel):
+    """Rule descriptor from router configuration."""
+
+    path: str = Field(description="Relative path to markdown rule file")
+    description: str = Field(description="Rule description")
+
+
+class ScriptConfig(BaseModel):
+    """Script descriptor from router configuration."""
+
+    path: str = Field(description="Relative path to script file")
+    description: str = Field(description="Script description")
+
+
+class RouterConfig(BaseModel):
+    """Top-level router.yaml document."""
+
+    tasks: dict[str, TaskConfig] = Field(default_factory=dict)
+    rules: dict[str, RuleConfig] = Field(default_factory=dict)
+    scripts: dict[str, ScriptConfig] = Field(default_factory=dict)
+
+
+class CopiedScriptsResult(BaseModel):
+    """Result payload for copied scripts."""
+
+    destination_directory: str
+    copied_files: list[str] = Field(default_factory=list)

policygate-0.1.0/src/policygate/domains/gateway/services.py

@@ -0,0 +1,149 @@
+"""Application service for policy gateway use-cases."""
+
+from __future__ import annotations
+
+import tempfile
+from typing import Protocol
+
+import yaml
+from pydantic import ValidationError
+
+from policygate.domains.gateway.exceptions import (
+    RepositorySyncError,
+    RouterReferenceError,
+    RouterValidationError,
+)
+from policygate.domains.gateway.models import CopiedScriptsResult, RouterConfig
+
+
+class RepositoryGateway(Protocol):
+    """Port for repository synchronization and file access."""
+
+    def refresh_if_needed(self) -> None: ...
+
+    def force_refresh(self) -> None: ...
+
+    def read_text(self, relative_path: str) -> str: ...
+
+    def read_many_texts(self, relative_paths: list[str]) -> dict[str, str]: ...
+
+    def copy_many_files(
+        self,
+        relative_paths: list[str],
+        destination_directory: str,
+    ) -> list[str]: ...
+
+
+class PolicyGatewayService:
+    """Use-case service for router outline, rules reading, and scripts copying."""
+
+    def __init__(self, repository_gateway: RepositoryGateway) -> None:
+        self._repository_gateway = repository_gateway
+
+    def outline_router(self) -> str:
+        """Return parsed and validated router.yaml content as markdown text."""
+        router = self._load_router()
+        return self._router_to_markdown(router)
+
+    def sync_repository(self) -> dict[str, str]:
+        """Force synchronization of remote repository to local cache."""
+        self._repository_gateway.force_refresh()
+        return {"status": "synced"}
+
+    def read_rules(self, rule_names: list[str]) -> str:
+        """Return rule markdown content by aliases from router.yaml as markdown text."""
+        if not rule_names:
+            return ""
+
+        router = self._load_router()
+        missing = [name for name in rule_names if name not in router.rules]
+        if missing:
+            joined = ", ".join(missing)
+            raise RouterReferenceError(f"unknown rule aliases: {joined}")
+
+        names_to_paths = {name: router.rules[name].path for name in rule_names}
+        contents_by_path = self._repository_gateway.read_many_texts(
+            list(names_to_paths.values())
+        )
+        sections: list[str] = []
+        for name, path in names_to_paths.items():
+            if path not in contents_by_path:
+                continue
+            sections.append(f"<{name}>\n{contents_by_path[path].rstrip()}\n</{name}>")
+
+        return "\n\n".join(sections)
+
+    def copy_scripts(self, script_names: list[str]) -> CopiedScriptsResult:
+        """Copy script files by aliases to a temporary directory."""
+        if not script_names:
+            destination = tempfile.mkdtemp(prefix="policygate-scripts-")
+            return CopiedScriptsResult(
+                destination_directory=destination,
+                copied_files=[],
+            )
+
+        router = self._load_router()
+        missing = [name for name in script_names if name not in router.scripts]
+        if missing:
+            joined = ", ".join(missing)
+            raise RouterReferenceError(f"unknown script aliases: {joined}")
+
+        destination = tempfile.mkdtemp(prefix="policygate-scripts-")
+        paths = [router.scripts[name].path for name in script_names]
+        copied_files = self._repository_gateway.copy_many_files(
+            relative_paths=paths,
+            destination_directory=destination,
+        )
+
+        return CopiedScriptsResult(
+            destination_directory=destination,
+            copied_files=copied_files,
+        )
+
+    def _load_router(self) -> RouterConfig:
+        try:
+            self._repository_gateway.refresh_if_needed()
+            router_raw = self._repository_gateway.read_text("router.yaml")
+            parsed = yaml.safe_load(router_raw)
+            if not isinstance(parsed, dict):
+                raise RouterValidationError(
+                    "router.yaml must contain a top-level object"
+                )
+            return RouterConfig.model_validate(parsed)
+        except ValidationError as error:
+            raise RouterValidationError(str(error)) from error
+        except OSError as error:
+            raise RepositorySyncError(str(error)) from error
+
+    def _router_to_markdown(self, router: RouterConfig) -> str:
+        sections: list[str] = ["# Router"]
+
+        sections.append("## Tasks")
+        if not router.tasks:
+            sections.append("- _none_")
+        else:
+            for name, task in router.tasks.items():
+                sections.append(f"### {name}")
+                sections.append(f"- Description: {task.description}")
+                sections.append(
+                    f"- Rules: {', '.join(task.rules) if task.rules else '_none_'}"
+                )
+                sections.append(
+                    f"- Scripts: {', '.join(task.scripts) if task.scripts else '_none_'}"
+                )
+
+        sections.append("## Rules")
+        if not router.rules:
+            sections.append("- _none_")
+        else:
+            for name, rule in router.rules.items():
+                sections.append(f"- **{name}**: `{rule.path}` — {rule.description}")
+
+        sections.append("## Scripts")
+        if not router.scripts:
+            sections.append("- _none_")
+        else:
+            for name, script in router.scripts.items():
+                sections.append(f"- **{name}**: `{script.path}` — {script.description}")
+
+        return "\n".join(sections)

policygate-0.1.0/src/policygate/entry_points/__init__.py

@@ -0,0 +1,10 @@
+"""
+Application entry points (CLI, API, workers).
+
+Rules:
+- Handles application bootstrapping and dependency injection.
+- Contains controllers/handlers for external interfaces.
+- Orchestrates interaction between outer world and domain layer.
+- Can import from domains and infrastructure.
+- No business logic.
+"""

policygate-0.1.0/src/policygate/entry_points/mcp_server.py

@@ -0,0 +1,120 @@
+"""MCP server entry point for policy routing gateway."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, is_dataclass
+from typing import Annotated, Any
+
+from fastmcp import FastMCP
+from pydantic import Field
+
+from policygate.config.settings import get_settings
+from policygate.domains.gateway.services import PolicyGatewayService
+from policygate.infrastructure.repository.github_repository_gateway import (
+    GitHubRepositoryGateway,
+)
+
+
+def _to_serializable(value: Any) -> Any:
+    if isinstance(value, list):
+        return [_to_serializable(item) for item in value]
+    if isinstance(value, dict):
+        return {key: _to_serializable(item) for key, item in value.items()}
+    if is_dataclass(value):
+        return _to_serializable(asdict(value))
+    if hasattr(value, "model_dump"):
+        return value.model_dump(mode="json")
+    return value
+
+
+mcp = FastMCP(
+    name="policygate",
+    instructions=(
+        "Policy gateway for task routing. Use router outline first, then read rules, "
+        "and copy scripts only for scripts explicitly mapped in router.yaml."
+    ),
+    version=get_settings().app_version,
+    on_duplicate="error",
+    mask_error_details=False,
+)
+
+
+def build_service() -> PolicyGatewayService:
+    """Build service graph with GitHub-backed repository gateway."""
+    settings = get_settings()
+    return PolicyGatewayService(
+        repository_gateway=GitHubRepositoryGateway(
+            repository_url=settings.github_repository_url,
+            access_token=settings.github_access_token,
+            local_repo_data_dir=settings.local_repo_data_dir,
+            refresh_interval_seconds=settings.repository_refresh_interval_seconds,
+        )
+    )
+
+
+@mcp.tool(
+    annotations={
+        "readOnlyHint": True,
+        "idempotentHint": True,
+        "openWorldHint": False,
+    }
+)
+def outline_router() -> str:
+    """Parse and return router.yaml contents as markdown text."""
+    return build_service().outline_router()
+
+
+@mcp.tool(
+    annotations={
+        "readOnlyHint": False,
+        "idempotentHint": True,
+        "openWorldHint": False,
+    }
+)
+def sync_repository() -> dict[str, str]:
+    """Force repository synchronization to refresh local cache now."""
+    return build_service().sync_repository()
+
+
+@mcp.tool(
+    annotations={
+        "readOnlyHint": True,
+        "idempotentHint": True,
+        "openWorldHint": False,
+    }
+)
+def read_rules(
+    rule_names: Annotated[
+        list[str],
+        Field(
+            description=(
+                "Rule aliases from router.yaml rules section. "
+                "Example: [\"rule1\", \"rule_security\"]"
+            )
+        ),
+    ],
+) -> str:
+    """Read selected rules and return a combined markdown document."""
+    return build_service().read_rules(rule_names=rule_names)
+
+
+@mcp.tool(
+    annotations={
+        "readOnlyHint": False,
+        "destructiveHint": False,
+        "openWorldHint": False,
+    }
+)
+def copy_scripts(
+    script_names: Annotated[
+        list[str],
+        Field(description="Script aliases from router.yaml scripts section."),
+    ],
+) -> dict[str, Any]:
+    """Copy selected scripts to a temporary directory for execution."""
+    return _to_serializable(build_service().copy_scripts(script_names=script_names))
+
+
+def run() -> None:
+    """Run MCP server."""
+    mcp.run()

policygate-0.1.0/src/policygate/infrastructure/__init__.py

@@ -0,0 +1,10 @@
+"""
+Infrastructure layer containing technical implementation details.
+
+Rules:
+- Implements interfaces defined in the domain or supports domain logic.
+- Contains database repositories, API clients, file storage, etc.
+- Handles interactions with external systems (SQLAlchemy, httpx, etc.).
+- Can import from domains.
+- No business logic.
+"""

policygate-0.1.0/src/policygate/infrastructure/repository/__init__.py

@@ -0,0 +1 @@
+"""Repository infrastructure adapters."""

policygate-0.1.0/src/policygate/infrastructure/repository/github_repository_gateway.py

@@ -0,0 +1,257 @@
+"""GitHub repository gateway with local caching for policy assets."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import tarfile
+import tempfile
+import threading
+import time
+from io import BytesIO
+from pathlib import Path
+from urllib.parse import urlparse
+
+import httpx
+
+from policygate.domains.gateway.exceptions import RepositorySyncError
+
+
+class GitHubRepositoryGateway:
+    """Synchronize a GitHub repository and expose files from local cache."""
+
+    def __init__(
+        self,
+        repository_url: str,
+        access_token: str,
+        local_repo_data_dir: str,
+        refresh_interval_seconds: int = 60,
+    ) -> None:
+        if not repository_url:
+            raise RepositorySyncError("github_repository_url is not configured")
+        if not access_token:
+            raise RepositorySyncError("github_access_token is not configured")
+
+        self._repository_url = repository_url
+        self._access_token = access_token
+        self._local_repo_data_dir = Path(local_repo_data_dir).expanduser().resolve()
+        self._refresh_interval_seconds = max(refresh_interval_seconds, 1)
+        self._last_refresh_check_at = 0.0
+        self._refresh_lock = threading.Lock()
+
+        self._owner, self._repo = self._parse_owner_repo(repository_url)
+        self._metadata_file = self._local_repo_data_dir / ".policygate_sync.json"
+
+    def refresh_if_needed(self) -> None:
+        """Refresh local cache if check interval elapsed and commit changed."""
+        with self._refresh_lock:
+            now = time.time()
+            if (
+                now - self._last_refresh_check_at < self._refresh_interval_seconds
+                and self._local_repo_data_dir.exists()
+            ):
+                return
+
+            self._last_refresh_check_at = now
+            self._refresh(force=not self._local_repo_data_dir.exists())
+
+    def force_refresh(self) -> None:
+        """Force synchronization regardless of refresh interval and cached SHA."""
+        with self._refresh_lock:
+            self._refresh(force=True)
+            self._last_refresh_check_at = time.time()
+
+    def read_text(self, relative_path: str) -> str:
+        """Read text file from synchronized local repository cache."""
+        target = self._resolve_relative_path(relative_path)
+        return target.read_text(encoding="utf-8")
+
+    def read_many_texts(self, relative_paths: list[str]) -> dict[str, str]:
+        """Read multiple files from local repository cache."""
+        content_by_path: dict[str, str] = {}
+        for relative_path in relative_paths:
+            target = self._resolve_relative_path(relative_path)
+            content_by_path[relative_path] = target.read_text(encoding="utf-8")
+        return content_by_path
+
+    def copy_many_files(
+        self,
+        relative_paths: list[str],
+        destination_directory: str,
+    ) -> list[str]:
+        """Copy files from local cache to destination directory."""
+        destination = Path(destination_directory).resolve()
+        destination.mkdir(parents=True, exist_ok=True)
+
+        copied: list[str] = []
+        for relative_path in relative_paths:
+            source = self._resolve_relative_path(relative_path)
+            target = destination / Path(relative_path).name
+            shutil.copy2(source, target)
+            copied.append(str(target))
+        return copied
+
+    def _refresh(self, force: bool = False) -> None:
+        default_branch, latest_sha, tarball_url = self._get_repository_state()
+        cached_sha = self._read_cached_sha()
+
+        if not force and cached_sha == latest_sha:
+            return
+
+        self._download_and_extract(tarball_url=tarball_url)
+        self._write_metadata(
+            {
+                "repository": f"{self._owner}/{self._repo}",
+                "default_branch": default_branch,
+                "sha": latest_sha,
+                "synced_at": int(time.time()),
+            }
+        )
+
+    def _get_repository_state(self) -> tuple[str, str, str]:
+        headers = self._build_headers()
+
+        with httpx.Client(timeout=30.0, headers=headers) as client:
+            repository_response = client.get(
+                f"https://api.github.com/repos/{self._owner}/{self._repo}"
+            )
+            repository_response.raise_for_status()
+            repository_payload = repository_response.json()
+
+            default_branch = repository_payload["default_branch"]
+            tarball_url = self._resolve_tarball_url(
+                repository_payload=repository_payload,
+                default_branch=default_branch,
+            )
+
+            commit_response = client.get(
+                f"https://api.github.com/repos/{self._owner}/{self._repo}/commits/{default_branch}"
+            )
+            commit_response.raise_for_status()
+            latest_sha = commit_response.json()["sha"]
+
+        return default_branch, latest_sha, tarball_url
+
+    def _resolve_tarball_url(
+        self,
+        repository_payload: dict,
+        default_branch: str,
+    ) -> str:
+        tarball_url = repository_payload.get("tarball_url")
+        if isinstance(tarball_url, str) and tarball_url:
+            if "{/ref}" in tarball_url:
+                return tarball_url.replace("{/ref}", f"/{default_branch}")
+            return tarball_url
+
+        archive_url = repository_payload.get("archive_url")
+        if isinstance(archive_url, str) and archive_url:
+            url = archive_url.replace("{/archive_format}", "/tarball")
+            url = url.replace("{archive_format}", "tarball")
+            if "{/ref}" in url:
+                return url.replace("{/ref}", f"/{default_branch}")
+            return url.rstrip("/") + f"/{default_branch}"
+
+        return f"https://api.github.com/repos/{self._owner}/{self._repo}/tarball/{default_branch}"
+
+    def _download_and_extract(self, tarball_url: str) -> None:
+        headers = self._build_headers()
+        with httpx.Client(
+            timeout=60.0, headers=headers, follow_redirects=True
+        ) as client:
+            archive_response = client.get(tarball_url)
+            archive_response.raise_for_status()
+            archive_bytes = archive_response.content
+
+        with tempfile.TemporaryDirectory(prefix="policygate-sync-") as temp_dir:
+            temp_path = Path(temp_dir)
+            with tarfile.open(fileobj=BytesIO(archive_bytes), mode="r:gz") as archive:
+                archive.extractall(path=temp_path)
+
+            extracted_roots = [child for child in temp_path.iterdir() if child.is_dir()]
+            if not extracted_roots:
+                raise RepositorySyncError("unable to extract repository archive")
+
+            source_root = extracted_roots[0]
+            self._copy_repository_entries(source_root)
+
+    def _copy_repository_entries(self, source_root: Path) -> None:
+        required_entries = ["router.yaml", "rules"]
+        optional_entries = ["scripts"]
+
+        self._local_repo_data_dir.mkdir(parents=True, exist_ok=True)
+        for child in list(self._local_repo_data_dir.iterdir()):
+            if child.name == self._metadata_file.name:
+                continue
+            if child.is_dir():
+                shutil.rmtree(child)
+            else:
+                child.unlink()
+
+        for entry in required_entries:
+            source_path = source_root / entry
+            if not source_path.exists():
+                raise RepositorySyncError(
+                    f"repository is missing required entry: {entry}"
+                )
+            self._copy_entry(source_path=source_path, target_name=entry)
+
+        for entry in optional_entries:
+            source_path = source_root / entry
+            if not source_path.exists():
+                continue
+            self._copy_entry(source_path=source_path, target_name=entry)
+
+    def _copy_entry(self, source_path: Path, target_name: str) -> None:
+        target_path = self._local_repo_data_dir / target_name
+        if source_path.is_dir():
+            shutil.copytree(source_path, target_path, dirs_exist_ok=True)
+        else:
+            shutil.copy2(source_path, target_path)
+
+    def _resolve_relative_path(self, relative_path: str) -> Path:
+        if not relative_path:
+            raise RepositorySyncError("relative path cannot be empty")
+
+        candidate = (self._local_repo_data_dir / relative_path).resolve()
+        base = self._local_repo_data_dir.resolve()
+        if base not in candidate.parents and candidate != base:
+            raise RepositorySyncError("path traversal is not allowed")
+        if not candidate.exists() or not candidate.is_file():
+            raise RepositorySyncError(f"file not found: {relative_path}")
+        return candidate
+
+    def _read_cached_sha(self) -> str | None:
+        if not self._metadata_file.exists():
+            return None
+        try:
+            payload = json.loads(self._metadata_file.read_text(encoding="utf-8"))
+            return payload.get("sha")
+        except (json.JSONDecodeError, OSError):
+            return None
+
+    def _write_metadata(self, payload: dict[str, str | int]) -> None:
+        self._metadata_file.parent.mkdir(parents=True, exist_ok=True)
+        self._metadata_file.write_text(
+            json.dumps(payload, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+
+    def _parse_owner_repo(self, repository_url: str) -> tuple[str, str]:
+        parsed = urlparse(repository_url)
+        path = parsed.path.strip("/")
+        if path.endswith(".git"):
+            path = path[:-4]
+
+        segments = path.split("/")
+        if len(segments) < 2:
+            raise RepositorySyncError(
+                "github_repository_url must include owner and repository name"
+            )
+        return segments[0], segments[1]
+
+    def _build_headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._access_token}",
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }