astro-airflow-mcp 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. astro_airflow_mcp-0.3.0/.claude/commands/add-adapter-method.md +40 -0
  2. astro_airflow_mcp-0.3.0/.claude/commands/add-tool.md +45 -0
  3. astro_airflow_mcp-0.3.0/.claude/commands/check-airflow-compat.md +31 -0
  4. astro_airflow_mcp-0.3.0/.claude/skills/airflow-adapter/SKILL.md +37 -0
  5. astro_airflow_mcp-0.3.0/.claude/skills/airflow-adapter/api-differences.md +51 -0
  6. astro_airflow_mcp-0.3.0/.claude/skills/airflow-adapter/patterns.md +86 -0
  7. astro_airflow_mcp-0.3.0/.gitignore +46 -0
  8. astro_airflow_mcp-0.3.0/.pre-commit-config.yaml +51 -0
  9. astro_airflow_mcp-0.3.0/AGENTS.md +144 -0
  10. astro_airflow_mcp-0.3.0/CLAUDE.md +1 -0
  11. astro_airflow_mcp-0.3.0/Dockerfile +28 -0
  12. astro_airflow_mcp-0.3.0/LICENSE +201 -0
  13. astro_airflow_mcp-0.3.0/Makefile +118 -0
  14. astro_airflow_mcp-0.3.0/PKG-INFO +452 -0
  15. astro_airflow_mcp-0.3.0/README.md +434 -0
  16. astro_airflow_mcp-0.3.0/docker-compose.test.yml +99 -0
  17. astro_airflow_mcp-0.3.0/pyproject.toml +97 -0
  18. astro_airflow_mcp-0.3.0/scripts/run-integration-tests.sh +76 -0
  19. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/__init__.py +9 -0
  20. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/__main__.py +161 -0
  21. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/adapter_manager.py +130 -0
  22. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/adapters/__init__.py +128 -0
  23. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/adapters/airflow_v2.py +367 -0
  24. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/adapters/airflow_v3.py +435 -0
  25. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/adapters/base.py +450 -0
  26. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/auth.py +169 -0
  27. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/__init__.py +5 -0
  28. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/assets.py +122 -0
  29. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/config.py +223 -0
  30. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/context.py +153 -0
  31. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/dags.py +217 -0
  32. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/instances.py +155 -0
  33. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/main.py +194 -0
  34. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/output.py +32 -0
  35. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/runs.py +240 -0
  36. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/tasks.py +171 -0
  37. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/config/__init__.py +13 -0
  38. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/config/interpolation.py +44 -0
  39. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/config/loader.py +195 -0
  40. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/config/models.py +108 -0
  41. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/constants.py +14 -0
  42. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/logging.py +66 -0
  43. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/models.py +310 -0
  44. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/plugin.py +66 -0
  45. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/prompts.py +97 -0
  46. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/resources.py +39 -0
  47. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/server.py +135 -0
  48. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/tools/__init__.py +5 -0
  49. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/tools/admin.py +471 -0
  50. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/tools/asset.py +214 -0
  51. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/tools/dag.py +287 -0
  52. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/tools/dag_run.py +365 -0
  53. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/tools/diagnostic.py +311 -0
  54. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/tools/task.py +342 -0
  55. astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/utils.py +74 -0
  56. astro_airflow_mcp-0.3.0/tests/__init__.py +1 -0
  57. astro_airflow_mcp-0.3.0/tests/integration/__init__.py +5 -0
  58. astro_airflow_mcp-0.3.0/tests/integration/conftest.py +84 -0
  59. astro_airflow_mcp-0.3.0/tests/integration/dags/integration_dag.py +20 -0
  60. astro_airflow_mcp-0.3.0/tests/integration/passwords.json +1 -0
  61. astro_airflow_mcp-0.3.0/tests/integration/test_api_endpoints.py +518 -0
  62. astro_airflow_mcp-0.3.0/tests/test_adapters.py +985 -0
  63. astro_airflow_mcp-0.3.0/tests/test_config.py +539 -0
  64. astro_airflow_mcp-0.3.0/tests/test_consolidated_tools.py +221 -0
  65. astro_airflow_mcp-0.3.0/tests/test_models.py +290 -0
  66. astro_airflow_mcp-0.3.0/tests/test_plugin.py +56 -0
  67. astro_airflow_mcp-0.3.0/tests/test_server.py +554 -0
  68. astro_airflow_mcp-0.3.0/tests/test_utils.py +198 -0
  69. astro_airflow_mcp-0.3.0/tests/test_version.py +18 -0
  70. astro_airflow_mcp-0.3.0/uv.lock +3822 -0
@@ -0,0 +1,40 @@
1
+ ---
2
+ description: Add a new method to both Airflow adapters
3
+ argument-hint: [method-name]
4
+ ---
5
+
6
+ Add method `$ARGUMENTS` to both V2 and V3 adapters.
7
+
8
+ ## Steps
9
+
10
+ 1. Add abstract method to `adapters/base.py`:
11
+
12
+ ```python
13
+ @abstractmethod
14
+ def method_name(self, param: str) -> dict[str, Any]:
15
+ pass
16
+ ```
17
+
18
+ 2. Implement in `adapters/airflow_v2.py`:
19
+
20
+ ```python
21
+ def method_name(self, param: str) -> dict[str, Any]:
22
+ return self._call(f"endpoint/{param}")
23
+ ```
24
+
25
+ 3. Implement in `adapters/airflow_v3.py`:
26
+
27
+ ```python
28
+ def method_name(self, param: str) -> dict[str, Any]:
29
+ return self._call(f"endpoint/{param}")
30
+ ```
31
+
32
+ ## Version Differences
33
+
34
+ | Feature | Airflow 2.x | Airflow 3.x |
35
+ |---------|-------------|-------------|
36
+ | API path | `/api/v1` | `/api/v2` |
37
+ | Assets | `datasets` | `assets` |
38
+ | DAG runs | `execution_date` | `logical_date` |
39
+
40
+ Normalize V2 responses to match V3 field names when they differ.
@@ -0,0 +1,45 @@
1
+ ---
2
+ description: Add a new MCP tool to server.py
3
+ argument-hint: [tool-name]
4
+ ---
5
+
6
+ Add a new MCP tool named `$ARGUMENTS` to `src/astro_airflow_mcp/server.py`.
7
+
8
+ ## Steps
9
+
10
+ 1. If the tool needs a new adapter method, run `/add-adapter-method` first.
11
+
12
+ 2. Create internal `_impl` function that calls the adapter:
13
+
14
+ ```python
15
+ def _tool_name_impl(param: str) -> str:
16
+ """Internal implementation."""
17
+ try:
18
+ adapter = _get_adapter()
19
+ data = adapter.method_name(param)
20
+ return json.dumps(data, indent=2)
21
+ except Exception as e:
22
+ return str(e)
23
+ ```
24
+
25
+ 3. Create the MCP tool with descriptive docstring:
26
+
27
+ ```python
28
+ @mcp.tool()
29
+ def tool_name(param: str) -> str:
30
+ """One-line description.
31
+
32
+ Use this tool when the user asks about:
33
+ - "Example query 1"
34
+ - "Example query 2"
35
+
36
+ Args:
37
+ param: Description
38
+
39
+ Returns:
40
+ JSON with response data
41
+ """
42
+ return _tool_name_impl(param=param)
43
+ ```
44
+
45
+ 4. Add the tool to README.md tools table.
@@ -0,0 +1,31 @@
1
+ ---
2
+ description: Verify code works with both Airflow 2.x and 3.x
3
+ allowed-tools: Bash(grep:*), Bash(make test:*), Bash(make test-integration:*)
4
+ ---
5
+
6
+ Check if recent code changes are compatible with both Airflow versions.
7
+
8
+ ## Check for Issues
9
+
10
+ 1. Look for hardcoded API paths outside adapters:
11
+ !`grep -rn "api/v1\|api/v2" src/astro_airflow_mcp/*.py | grep -v adapters`
12
+
13
+ 2. Check field normalization in adapters:
14
+ !`grep -n "execution_date\|logical_date\|datasets\|assets" src/astro_airflow_mcp/adapters/*.py`
15
+
16
+ ## Key Differences
17
+
18
+ | Airflow 2.x | Airflow 3.x |
19
+ |-------------|-------------|
20
+ | `/api/v1` | `/api/v2` |
21
+ | `execution_date` | `logical_date` |
22
+ | `datasets` | `assets` |
23
+ | Basic auth | OAuth2/JWT |
24
+
25
+ ## Run Tests
26
+
27
+ ```bash
28
+ make test
29
+ make test-integration-v2
30
+ make test-integration-v3
31
+ ```
@@ -0,0 +1,37 @@
1
+ ---
2
+ description: Airflow adapter pattern for v2/v3 API compatibility
3
+ globs:
4
+ - src/astro_airflow_mcp/adapters/**
5
+ - src/astro_airflow_mcp/server.py
6
+ ---
7
+
8
+ # Airflow Adapter Pattern
9
+
10
+ Enables compatibility with both Airflow 2.x (`/api/v1`) and 3.x (`/api/v2`).
11
+
12
+ ## Architecture
13
+
14
+ ```
15
+ MCP Tool → _get_adapter() → AirflowV2Adapter or AirflowV3Adapter → Airflow API
16
+ ```
17
+
18
+ Version is auto-detected at startup.
19
+
20
+ ## Key Files
21
+
22
+ - `adapters/base.py` - Abstract interface
23
+ - `adapters/airflow_v2.py` - Airflow 2.x (`/api/v1`)
24
+ - `adapters/airflow_v3.py` - Airflow 3.x (`/api/v2`)
25
+
26
+ ## Related Files
27
+
28
+ - @api-differences.md - V2 vs V3 field/endpoint differences
29
+ - @patterns.md - Implementation patterns
30
+
31
+ ## Quick Reference
32
+
33
+ ```python
34
+ adapter = _get_adapter()
35
+ dags = adapter.list_dags(limit=100)
36
+ run = adapter.trigger_dag_run("my_dag", conf={"key": "value"})
37
+ ```
@@ -0,0 +1,51 @@
1
+ # Airflow API Differences (v2 vs v3)
2
+
3
+ ## Endpoint Paths
4
+
5
+ | Airflow 2.x | Airflow 3.x |
6
+ |-------------|-------------|
7
+ | `/api/v1/dags` | `/api/v2/dags` |
8
+ | `/api/v1/datasets` | `/api/v2/assets` |
9
+ | `/api/v1/dagRuns` | `/api/v2/dagRuns` |
10
+
11
+ ## Field Name Changes
12
+
13
+ | Airflow 2.x | Airflow 3.x | Notes |
14
+ |-------------|-------------|-------|
15
+ | `execution_date` | `logical_date` | DAG run timing |
16
+ | `datasets` | `assets` | Data-aware scheduling |
17
+ | `consuming_dags` | `scheduled_dags` | Asset consumers |
18
+
19
+ ## Authentication
20
+
21
+ | Airflow 2.x | Airflow 3.x |
22
+ |-------------|-------------|
23
+ | Basic auth | OAuth2/JWT |
24
+ | Username/password in header | Token from `/auth/token` |
25
+
26
+ ## Endpoints Only in Airflow 3.x
27
+
28
+ - `dagStats` without required `dag_ids` parameter
29
+ - Enhanced task instance filtering
30
+
31
+ ## Endpoints Changed in Airflow 3.x
32
+
33
+ - `dagSources/{dag_id}` - V3 uses dag_id directly, V2 needs file_token
34
+
35
+ ## Handling Differences in Code
36
+
37
+ ```python
38
+ # V2 adapter - normalize datasets to assets
39
+ def list_assets(self, ...) -> dict[str, Any]:
40
+ data = self._call("datasets", ...)
41
+ if "datasets" in data:
42
+ data["assets"] = data.pop("datasets")
43
+ for asset in data["assets"]:
44
+ if "consuming_dags" in asset:
45
+ asset["scheduled_dags"] = asset.pop("consuming_dags")
46
+ return data
47
+
48
+ # V3 adapter - use native assets endpoint
49
+ def list_assets(self, ...) -> dict[str, Any]:
50
+ return self._call("assets", ...)
51
+ ```
@@ -0,0 +1,86 @@
1
+ # Adapter Implementation Patterns
2
+
3
+ ## Basic Pattern
4
+
5
+ ```python
6
+ # In base.py
7
+ @abstractmethod
8
+ def get_thing(self, thing_id: str) -> dict[str, Any]:
9
+ """Get a thing by ID."""
10
+ pass
11
+
12
+ # In airflow_v2.py and airflow_v3.py
13
+ def get_thing(self, thing_id: str) -> dict[str, Any]:
14
+ return self._call(f"things/{thing_id}")
15
+ ```
16
+
17
+ ## Handling Missing Endpoints
18
+
19
+ ```python
20
+ def new_feature(self, param: str) -> dict[str, Any]:
21
+ try:
22
+ return self._call(f"newFeature/{param}")
23
+ except NotFoundError:
24
+ return self._handle_not_found(
25
+ "newFeature",
26
+ alternative="This feature requires Airflow 3.x"
27
+ )
28
+ ```
29
+
30
+ ## Field Normalization
31
+
32
+ When field names differ between versions, normalize in V2 to match V3:
33
+
34
+ ```python
35
+ # V2 adapter
36
+ def get_dag_run(self, dag_id: str, run_id: str) -> dict[str, Any]:
37
+ data = self._call(f"dags/{dag_id}/dagRuns/{run_id}")
38
+ # Normalize execution_date to logical_date
39
+ if "execution_date" in data and "logical_date" not in data:
40
+ data["logical_date"] = data["execution_date"]
41
+ return data
42
+ ```
43
+
44
+ ## POST/PATCH Operations
45
+
46
+ ```python
47
+ def trigger_dag_run(self, dag_id: str, conf: dict | None = None) -> dict[str, Any]:
48
+ json_body: dict[str, Any] = {}
49
+ if conf:
50
+ json_body["conf"] = conf
51
+ return self._post(f"dags/{dag_id}/dagRuns", json_data=json_body)
52
+
53
+ def pause_dag(self, dag_id: str) -> dict[str, Any]:
54
+ return self._patch(f"dags/{dag_id}", json_data={"is_paused": True})
55
+ ```
56
+
57
+ ## Password Filtering
58
+
59
+ Always filter passwords from connection data:
60
+
61
+ ```python
62
+ def list_connections(self, ...) -> dict[str, Any]:
63
+ data = self._call("connections", ...)
64
+ return self._filter_passwords(data) # Base class method
65
+ ```
66
+
67
+ ## Testing Adapters
68
+
69
+ ```python
70
+ def test_new_method(self, mocker):
71
+ adapter = AirflowV2Adapter("http://localhost:8080", "2.9.0")
72
+
73
+ mock_response = mocker.Mock()
74
+ mock_response.json.return_value = {"result": "data"}
75
+ mock_response.status_code = 200
76
+
77
+ mock_client = mocker.Mock()
78
+ mock_client.get.return_value = mock_response
79
+ mock_client.__enter__ = mocker.Mock(return_value=mock_client)
80
+ mock_client.__exit__ = mocker.Mock(return_value=False)
81
+
82
+ mocker.patch("httpx.Client", return_value=mock_client)
83
+
84
+ result = adapter.new_method("param")
85
+ assert result == {"result": "data"}
86
+ ```
@@ -0,0 +1,46 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+ *.so
6
+ .Python
7
+ build/
8
+ develop-eggs/
9
+ dist/
10
+ downloads/
11
+ eggs/
12
+ .eggs/
13
+ lib/
14
+ lib64/
15
+ parts/
16
+ sdist/
17
+ var/
18
+ wheels/
19
+ *.egg-info/
20
+ .installed.cfg
21
+ *.egg
22
+
23
+ # Virtual environments
24
+ venv/
25
+ env/
26
+ ENV/
27
+ .venv
28
+
29
+ # IDE
30
+ .vscode/
31
+ .idea/
32
+ *.swp
33
+ *.swo
34
+ *~
35
+
36
+ # uv
37
+ .uv/
38
+
39
+ # Testing
40
+ .pytest_cache/
41
+ .coverage
42
+ htmlcov/
43
+
44
+ # OS
45
+ .DS_Store
46
+ Thumbs.db
@@ -0,0 +1,51 @@
1
+ # prek hooks for airflow-mcp
2
+ # See https://github.com/j178/prek for more information
3
+ # To install: uv tool install prek && prek install
4
+ # To run manually: prek run --all-files
5
+
6
+ repos:
7
+ # General file checks
8
+ - repo: https://github.com/pre-commit/pre-commit-hooks
9
+ rev: v6.0.0
10
+ hooks:
11
+ - id: trailing-whitespace
12
+ - id: end-of-file-fixer
13
+ - id: check-yaml
14
+ - id: check-toml
15
+ - id: check-added-large-files
16
+ args: ['--maxkb=500']
17
+ - id: check-merge-conflict
18
+ - id: check-case-conflict
19
+ - id: mixed-line-ending
20
+ args: ['--fix=lf']
21
+ - id: check-docstring-first
22
+
23
+ # Python code formatting with ruff
24
+ - repo: https://github.com/astral-sh/ruff-pre-commit
25
+ rev: v0.14.14
26
+ hooks:
27
+ # Run the linter
28
+ - id: ruff-check
29
+ args: [--fix, --exit-non-zero-on-fix]
30
+ # Run the formatter
31
+ - id: ruff-format
32
+
33
+ # Type checking with mypy
34
+ - repo: https://github.com/pre-commit/mirrors-mypy
35
+ rev: v1.19.1
36
+ hooks:
37
+ - id: mypy
38
+ additional_dependencies:
39
+ - types-requests
40
+ - types-PyYAML
41
+ args: [--ignore-missing-imports, --no-strict-optional]
42
+ exclude: ^tests/
43
+
44
+ # Security checks
45
+ - repo: https://github.com/PyCQA/bandit
46
+ rev: 1.9.3
47
+ hooks:
48
+ - id: bandit
49
+ args: ['-c', 'pyproject.toml']
50
+ additional_dependencies: ['bandit[toml]']
51
+ exclude: ^tests/
@@ -0,0 +1,144 @@
1
+ <!-- START doctoc generated TOC please keep comment here to allow auto update -->
2
+ <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
3
+ **Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
4
+
5
+ - [Agent Guidelines for astro-airflow-mcp](#agent-guidelines-for-astro-airflow-mcp)
6
+ - [Architecture](#architecture)
7
+ - [Code Conventions](#code-conventions)
8
+ - [HTTP Client](#http-client)
9
+ - [Adapter Pattern](#adapter-pattern)
10
+ - [MCP Tools](#mcp-tools)
11
+ - [Error Handling](#error-handling)
12
+ - [Airflow Version Differences](#airflow-version-differences)
13
+ - [Testing](#testing)
14
+ - [Files to Know](#files-to-know)
15
+
16
+ <!-- END doctoc generated TOC please keep comment here to allow auto update -->
17
+
18
+ # Agent Guidelines for astro-airflow-mcp
19
+
20
+ Guidelines for AI coding assistants contributing to this repository.
21
+
22
+ ## Architecture
23
+
24
+ MCP server for Apache Airflow with adapter pattern for version compatibility:
25
+
26
+ ```
27
+ src/astro_airflow_mcp/
28
+ ├── server.py # Core infrastructure: config, auth, adapter management (FastMCP)
29
+ ├── tools/ # MCP tool implementations (grouped by domain)
30
+ │ ├── dag.py # DAG management (get, list, source, stats, pause, unpause)
31
+ │ ├── task.py # Task management (get, list, instance, logs, clear)
32
+ │ ├── dag_run.py # DAG run management (list, get, trigger, trigger_and_wait)
33
+ │ ├── asset.py # Asset/dataset tools (list, events, upstream events)
34
+ │ ├── admin.py # Admin tools (connections, variables, pools, plugins, providers, config, version)
35
+ │ └── diagnostic.py # Diagnostic tools (warnings, errors, explore, diagnose, health)
36
+ ├── resources.py # MCP resources (read-only endpoints)
37
+ ├── prompts.py # MCP prompts (guided workflows)
38
+ ├── adapters/
39
+ │ ├── base.py # Abstract adapter interface
40
+ │ ├── airflow_v2.py # Airflow 2.x API (/api/v1)
41
+ │ └── airflow_v3.py # Airflow 3.x API (/api/v2)
42
+ ├── models.py # Pydantic models (documentation/type reference)
43
+ └── plugin.py # Airflow 3.x plugin integration
44
+ ```
45
+
46
+ ## Code Conventions
47
+
48
+ ### HTTP Client
49
+
50
+ Use `httpx`, not `requests`. All HTTP calls should use `httpx.Client`:
51
+
52
+ ```python
53
+ # Good
54
+ with httpx.Client(timeout=30.0) as client:
55
+ response = client.get(url, headers=headers)
56
+
57
+ # Bad
58
+ response = requests.get(url, headers=headers)
59
+ ```
60
+
61
+ ### Adapter Pattern
62
+
63
+ All Airflow API calls go through adapters. Never call Airflow API directly from MCP tools:
64
+
65
+ ```python
66
+ # Good - use adapter
67
+ adapter = _get_adapter()
68
+ data = adapter.list_dags(limit=100)
69
+
70
+ # Bad - direct API call
71
+ response = httpx.get(f"{url}/api/v2/dags")
72
+ ```
73
+
74
+ When adding new API endpoints:
75
+ 1. Add abstract method to `adapters/base.py`
76
+ 2. Implement in both `airflow_v2.py` and `airflow_v3.py`
77
+ 3. Handle API differences (field names, paths, availability)
78
+
79
+ ### MCP Tools
80
+
81
+ Tools need descriptive docstrings for AI discovery:
82
+
83
+ ```python
84
+ @mcp.tool()
85
+ def get_dag_details(dag_id: str) -> str:
86
+ """Get detailed information about a specific DAG.
87
+
88
+ Use this tool when the user asks about:
89
+ - "Show me details for DAG X"
90
+ - "What's the schedule for DAG Y?"
91
+
92
+ Args:
93
+ dag_id: The ID of the DAG
94
+
95
+ Returns:
96
+ JSON with DAG metadata
97
+ """
98
+ ```
99
+
100
+ ### Error Handling
101
+
102
+ Adapters handle missing endpoints gracefully:
103
+
104
+ ```python
105
+ try:
106
+ return self._call("newEndpoint")
107
+ except NotFoundError:
108
+ return self._handle_not_found(
109
+ "newEndpoint",
110
+ alternative="Use alternativeEndpoint instead"
111
+ )
112
+ ```
113
+
114
+ ## Airflow Version Differences
115
+
116
+ | Feature | Airflow 2.x | Airflow 3.x |
117
+ |---------|-------------|-------------|
118
+ | API path | `/api/v1` | `/api/v2` |
119
+ | Auth | Basic auth | OAuth2/JWT |
120
+ | Assets | `datasets` | `assets` |
121
+ | DAG runs | `execution_date` | `logical_date` |
122
+
123
+ ## Testing
124
+
125
+ - Mock adapters, not HTTP libraries
126
+ - Unit tests: `tests/`
127
+ - Integration tests: `tests/integration/` (require running Airflow)
128
+
129
+ ```python
130
+ # Good - mock adapter (patch in the tool module that imports it)
131
+ mock_adapter = mocker.Mock()
132
+ mock_adapter.list_dags.return_value = {"dags": [...]}
133
+ mocker.patch("astro_airflow_mcp.tools.dag._get_adapter", return_value=mock_adapter)
134
+
135
+ # Bad - mock HTTP library
136
+ mocker.patch("httpx.Client")
137
+ ```
138
+
139
+ ## Files to Know
140
+
141
+ - `server.py`: All MCP tools defined here
142
+ - `adapters/base.py`: Interface contract for both versions
143
+ - `models.py`: Type reference (not used for validation currently)
144
+ - `docker-compose.test.yml`: Test against real Airflow instances
@@ -0,0 +1 @@
1
+ AGENTS.md
@@ -0,0 +1,28 @@
1
+ # Dockerfile for Airflow MCP Server (Standalone Mode)
2
+ FROM python:3.11-slim
3
+
4
+ # Set working directory
5
+ WORKDIR /app
6
+
7
+ # Install uv for fast dependency management
8
+ RUN pip install --no-cache-dir uv
9
+
10
+ # Copy project files
11
+ COPY pyproject.toml README.md ./
12
+ COPY src/ ./src/
13
+
14
+ # Install dependencies
15
+ RUN uv pip install --system -e .
16
+
17
+ # Expose port for HTTP transport (optional)
18
+ EXPOSE 8000
19
+
20
+ # Set default environment variables
21
+ ENV AIRFLOW_API_URL=http://localhost:8080
22
+ ENV PYTHONUNBUFFERED=1
23
+
24
+ # Default command runs in stdio mode (for MCP clients)
25
+ CMD ["python", "-m", "astro_airflow_mcp"]
26
+
27
+ # To run with HTTP transport, override with:
28
+ # docker run -p 8000:8000 astro-airflow-mcp python -m astro_airflow_mcp --transport http --host 0.0.0.0 --port 8000