# FabricIQ stdio MCP Server

Exposes a published **Microsoft Fabric Data Agent** as a native MCP tool
(`query_fabric_agent`) over stdio, so an MCP client (VS Code, GitHub Copilot
CLI, Microsoft Scout, etc.) can call it directly instead of shelling out to a
script per question.

This is the sibling project to
[foundryiq-rfp-kb](../foundryiq-rfp-kb) — same design pattern (stdio MCP
server, fresh Azure CLI token per call, per-workspace `config.json`), but
targets a Fabric Data Agent's OpenAI-compatible Assistants endpoint instead of
an Azure AI Search knowledge base.

A fresh Azure AD access token (scoped to `https://api.fabric.microsoft.com`)
is minted on every tool call via the Azure CLI
(`az account get-access-token`) — nothing is hardcoded and the token never
goes stale.

## What it calls

The tool talks directly to the Fabric Data Agent's **OpenAI-compatible
Assistants API** (this skips the Foundry "connected tool" hop, which can add
10-15 min of latency/timeouts when the agent is invoked indirectly):

```
https://api.fabric.microsoft.com/v1/workspaces/<ws>/dataagents/<id>/aiassistant/openai
```

Protocol per query (`api-version=2024-05-01-preview`):
1. `assistants.create(model="not used")` — model field is ignored by Fabric
2. `threads.create()`
3. `threads.messages.create(role="user", content=question)`
4. `threads.runs.create(assistant_id=...)`
5. poll `runs.retrieve` until status is terminal
6. `threads.messages.list(order="desc")` → latest assistant message
7. `threads.delete` — cleanup

## Prerequisites

- Python 3.10+
- [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) installed and logged in:
  ```powershell
  az login
  ```
  Your account needs at least **Viewer** access on the Fabric workspace
  hosting the data agent (and read access to its underlying data sources).
  The server requests a token for the workspace's specific tenant, so it
  works even if that tenant differs from your CLI's active tenant/subscription.

## Setup

1. Create and activate a virtual environment:
   ```powershell
   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   ```
2. Install dependencies:
   ```powershell
   pip install -r requirements.txt
   ```
3. Copy `config.example.json` to `config.json` and fill in your Fabric data
   agent details:
   ```powershell
   Copy-Item config.example.json config.json
   ```
   ```json
   {
     "endpoint": "https://api.fabric.microsoft.com/v1/workspaces/<ws>/dataagents/<id>/aiassistant/openai",
     "api_version": "2024-05-01-preview",
     "token_resource": "https://api.fabric.microsoft.com",
     "tenant_id": "<tenant-guid>",
     "subscription_id": "",
     "poll_timeout": 600,
     "poll_interval": 3
   }
   ```
   `endpoint` is the published URL from the data agent's **Publish** pane in
   Fabric (ends in `/aiassistant/openai`). `tenant_id` is the tenant where the
   Fabric workspace lives — set it whenever that differs from your CLI's
   default login context (prevents cross-tenant 401 errors); `subscription_id`
   is an optional fallback used only when `tenant_id` is empty (the two are
   mutually exclusive for `az account get-access-token`). `config.json` is
   gitignored — it holds your real values and should never be committed.

## Running standalone (sanity check)

The server speaks MCP JSON-RPC over stdio, so running it directly will just
block waiting for input on stdin — that's expected:

```powershell
.\.venv\Scripts\python.exe fabriciq_mcp_server.py --config config.json
```

Press `Ctrl+C` to stop. This only confirms the process starts without
import/config errors; normally an MCP client launches and drives it.

You can also run a one-shot CLI query without an MCP client, for a quick
smoke test:

```powershell
.\.venv\Scripts\python.exe fabriciq_query.py "What was the average LTIFR across completed manufacturing projects?"
```

## Registering with an MCP client

### VS Code (`mcp.json`)

A `.vscode/mcp.json` is already included in this repo:

```json
{
  "servers": {
    "fabriciq": {
      "type": "stdio",
      "command": "${workspaceFolder}/.venv/Scripts/python.exe",
      "args": [
        "${workspaceFolder}/fabriciq_mcp_server.py",
        "--config",
        "${workspaceFolder}/config.json"
      ]
    }
  }
}
```

### GitHub Copilot CLI (and Microsoft Scout, which rides on it)

The Copilot CLI reads its MCP server registrations from
`~/.copilot/mcp-config.json` (i.e. `C:\Users\<you>\.copilot\mcp-config.json`
on Windows). Add a `fabriciq` entry there alongside any existing servers
(e.g. `foundryiq`):

```json
{
  "mcpServers": {
    "fabriciq": {
      "type": "local",
      "command": "C:\\Users\\sansri\\stdio-mcpservers\\fabriciq-rfp-kpis-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\sansri\\stdio-mcpservers\\fabriciq-rfp-kpis-mcp\\fabriciq_mcp_server.py",
        "--config",
        "C:\\Users\\sansri\\stdio-mcpservers\\fabriciq-rfp-kpis-mcp\\config.json"
      ],
      "tools": ["query_fabric_agent"]
    }
  }
}
```

Note the schema differs from VS Code's `mcp.json`: Copilot CLI uses
`"mcpServers"` (not `"servers"`) and `"type": "local"` (not `"stdio"`), but
the mechanism is identical — a local subprocess over stdin/stdout, no
URL/port involved. Restart Scout / start a new Copilot CLI session after
editing this file for the change to take effect.

### Microsoft Scout "Add MCP Server" dialog (GUI alternative)

Scout also has a GUI front-end for the same `mcp-config.json` — if you'd
rather not hand-edit the file, use its **Add MCP Server** dialog instead
(check first whether `fabriciq` already shows up in Scout's server list from
the file edit above; if so, skip this to avoid a duplicate registration):

- **Name:** `fabriciq-rfp-kpis-mcp`
- **Remote/Local:** Command
- **Command** (paste as one combined string):
  ```
  C:\Users\sansri\stdio-mcpservers\fabriciq-rfp-kpis-mcp\.venv\Scripts\python.exe C:\Users\sansri\stdio-mcpservers\fabriciq-rfp-kpis-mcp\fabriciq_mcp_server.py --config C:\Users\sansri\stdio-mcpservers\fabriciq-rfp-kpis-mcp\config.json
  ```
- **Environment variables:** leave blank (auth comes from your existing
  `az login` session, not env vars)
- **Tool-call timeout:** the Fabric Assistants API run can take noticeably
  longer than a search retrieval. Bump this above the default (~60s) —
  120–180s is a reasonable starting point, or match `poll_timeout` from
  `config.json` (default 600s) if Scout allows it.

## Microsoft Scout skill (`SKILL.md`)

This repo includes [SKILL.md](SKILL.md) — a Scout skill that teaches the
agent *how* to use the registered `fabriciq-rfp-kpis-mcp-query_fabric_agent`
MCP tool correctly (call it directly instead of shelling out, when to use it
vs. a document/search knowledge base, treat a "no exact match" reply as valid
free text rather than an error, never fabricate numbers, etc.).

**Registering the MCP server (steps above) is not enough on its own** — Scout
needs this skill imported separately so the agent knows these usage rules
exist and when to invoke the tool. Two things have to both be true for Scout
to use this correctly:

1. The `fabriciq` MCP server is registered in `~/.copilot/mcp-config.json`
   (see the GitHub Copilot CLI section above) — this is what makes the
   `fabriciq-rfp-kpis-mcp-query_fabric_agent` tool exist at all.
2. **[SKILL.md](SKILL.md) is imported into Scout's Skills/Extensions.** Add
   this skill via Scout's extensions/skills UI (import from this repo path)
   so the skill's `name`/`description` frontmatter is indexed and Scout knows
   to route Fabric/KPI questions through this tool with the correct calling
   convention.

After importing, restart Scout (or start a new session) so it re-discovers
both the MCP tool and the skill.

### Other MCP clients

Point the client's server registration at the same venv Python + script +
`--config` path shown above. Use absolute paths so the server resolves
correctly regardless of the client's working directory.

## Config resolution order

`--config` flag → `FABRICIQ_CONFIG` env var → `config.json` in the process's
current working directory. Individual `FABRICIQ_*` env vars
(`FABRICIQ_ENDPOINT`, `FABRICIQ_TENANT_ID`, `FABRICIQ_SUBSCRIPTION_ID`,
`FABRICIQ_API_VERSION`, `FABRICIQ_TOKEN_RESOURCE`, `FABRICIQ_POLL_TIMEOUT`,
`FABRICIQ_POLL_INTERVAL`) override individual fields on top of whatever
config file was loaded.

## Exposed tool

- **`query_fabric_agent(question: str) -> str`** — runs the Fabric Data
  Agent's Assistants-API conversation and returns the raw text answer.
  Intended for quantified project intelligence: KPI outcomes (OEE, LTIFR,
  TRIR, defect rates), financial data (cost variance, gross margin, change
  orders), risk register entries, milestone schedule data, certifications,
  client satisfaction scores. Not intended for narrative case-study text —
  use a document/search knowledge base (like `foundryiq-rfp-kb`) for that.
  A "couldn't find matching data" reply is valid free text from the agent,
  not a structural error — the caller decides what it means.

## Troubleshooting

- **`Failed to acquire Fabric access token. Run 'az login' first.`** — your
  CLI session expired or doesn't have access to the tenant/subscription in
  `config.json`. Re-run `az login` (and `az login --tenant <tenant_id>` if
  needed).
- **401 / authentication failed** — check `tenant_id` and that your account
  has access to the Fabric workspace hosting the data agent.
- **403 / access denied** — ensure your account has at least Viewer
  permission on the Fabric workspace and read access to the data agent's
  underlying data sources.
- **Fabric run polling exceeded `<n>`s** — the agent took longer than
  `poll_timeout` (default 600s) to finish. Increase `poll_timeout` in
  `config.json` if your queries are genuinely heavy.
- **No config found** — ensure `config.json` exists next to the script, or
  pass `--config <path>` / set `FABRICIQ_CONFIG`.
- **Stray output breaking the client** — all logging must go to stderr (this
  is already handled in `fabriciq_mcp_server.py`); don't add `print()` calls
  that write to stdout.