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.
- astro_airflow_mcp-0.3.0/.claude/commands/add-adapter-method.md +40 -0
- astro_airflow_mcp-0.3.0/.claude/commands/add-tool.md +45 -0
- astro_airflow_mcp-0.3.0/.claude/commands/check-airflow-compat.md +31 -0
- astro_airflow_mcp-0.3.0/.claude/skills/airflow-adapter/SKILL.md +37 -0
- astro_airflow_mcp-0.3.0/.claude/skills/airflow-adapter/api-differences.md +51 -0
- astro_airflow_mcp-0.3.0/.claude/skills/airflow-adapter/patterns.md +86 -0
- astro_airflow_mcp-0.3.0/.gitignore +46 -0
- astro_airflow_mcp-0.3.0/.pre-commit-config.yaml +51 -0
- astro_airflow_mcp-0.3.0/AGENTS.md +144 -0
- astro_airflow_mcp-0.3.0/CLAUDE.md +1 -0
- astro_airflow_mcp-0.3.0/Dockerfile +28 -0
- astro_airflow_mcp-0.3.0/LICENSE +201 -0
- astro_airflow_mcp-0.3.0/Makefile +118 -0
- astro_airflow_mcp-0.3.0/PKG-INFO +452 -0
- astro_airflow_mcp-0.3.0/README.md +434 -0
- astro_airflow_mcp-0.3.0/docker-compose.test.yml +99 -0
- astro_airflow_mcp-0.3.0/pyproject.toml +97 -0
- astro_airflow_mcp-0.3.0/scripts/run-integration-tests.sh +76 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/__init__.py +9 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/__main__.py +161 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/adapter_manager.py +130 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/adapters/__init__.py +128 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/adapters/airflow_v2.py +367 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/adapters/airflow_v3.py +435 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/adapters/base.py +450 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/auth.py +169 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/__init__.py +5 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/assets.py +122 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/config.py +223 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/context.py +153 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/dags.py +217 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/instances.py +155 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/main.py +194 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/output.py +32 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/runs.py +240 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/cli/tasks.py +171 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/config/__init__.py +13 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/config/interpolation.py +44 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/config/loader.py +195 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/config/models.py +108 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/constants.py +14 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/logging.py +66 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/models.py +310 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/plugin.py +66 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/prompts.py +97 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/resources.py +39 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/server.py +135 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/tools/__init__.py +5 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/tools/admin.py +471 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/tools/asset.py +214 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/tools/dag.py +287 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/tools/dag_run.py +365 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/tools/diagnostic.py +311 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/tools/task.py +342 -0
- astro_airflow_mcp-0.3.0/src/astro_airflow_mcp/utils.py +74 -0
- astro_airflow_mcp-0.3.0/tests/__init__.py +1 -0
- astro_airflow_mcp-0.3.0/tests/integration/__init__.py +5 -0
- astro_airflow_mcp-0.3.0/tests/integration/conftest.py +84 -0
- astro_airflow_mcp-0.3.0/tests/integration/dags/integration_dag.py +20 -0
- astro_airflow_mcp-0.3.0/tests/integration/passwords.json +1 -0
- astro_airflow_mcp-0.3.0/tests/integration/test_api_endpoints.py +518 -0
- astro_airflow_mcp-0.3.0/tests/test_adapters.py +985 -0
- astro_airflow_mcp-0.3.0/tests/test_config.py +539 -0
- astro_airflow_mcp-0.3.0/tests/test_consolidated_tools.py +221 -0
- astro_airflow_mcp-0.3.0/tests/test_models.py +290 -0
- astro_airflow_mcp-0.3.0/tests/test_plugin.py +56 -0
- astro_airflow_mcp-0.3.0/tests/test_server.py +554 -0
- astro_airflow_mcp-0.3.0/tests/test_utils.py +198 -0
- astro_airflow_mcp-0.3.0/tests/test_version.py +18 -0
- 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
|