# adf-mcp-server

Read-only MCP (Model Context Protocol) server for Azure Data Factory
monitoring and root-cause analysis, built for use from VS Code / Claude Code.

**Status: Step 1 (skeleton + health check).** No Azure connectivity yet -
that's added in Step 2 (auth) and Step 3 (ADF tools).

## Requirements

- Python 3.11+

## Local setup

```bash
cd adf-mcp-server
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env
```

`.env` currently only needs the server settings block (`ADF_MCP_*`). The
`AZURE_*` lines are placeholders for Step 2 - leave them commented out for now.

## Running the server

```bash
python -m adf_mcp.server
# or, after `pip install -e .`:
adf-mcp-server
```

The server communicates over **stdio** - running it directly in a terminal
will look like it hangs; that's expected, it's waiting for an MCP client
(VS Code extension, Claude Code, `mcp dev`, etc.) to connect via stdin/stdout.

### Configuring in VS Code

Point your MCP-capable extension's server config at:

```json
{
  "command": "python",
  "args": ["-m", "adf_mcp.server"],
  "cwd": "/absolute/path/to/adf-mcp-server"
}
```

Once connected, call the `health_check` tool - it should return
`{"status": "ok", ...}` without touching Azure at all.

## Running tests

```bash
pip install -e ".[dev]" pytest-asyncio
pytest -v
```

## Project layout

See `src/adf_mcp/` - `server.py` (MCP transport), `config.py` (settings),
`logging_config.py` (structured logging). Domain logic and Azure
connectivity are added under `src/adf_mcp/domain/` from Step 3 onward.

## Troubleshooting

- **Client shows "server disconnected" immediately**: check `python -m
  adf_mcp.server` runs cleanly on its own first - a startup exception will
  kill the process before the client ever connects.
- **Client can't parse responses / garbled output**: something wrote to
  stdout other than the MCP protocol itself (e.g. a stray `print()`). All
  logging in this project goes to stderr for exactly this reason.