Metadata-Version: 2.4
Name: xhr-assistant-mcp
Version: 0.3.1
Summary: MCP server and agent instructions for connecting AI agents to xHR
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastmcp<4.0.0,>=3.2.4
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: keyring<26,>=25
Requires-Dist: platformdirs<5,>=4
Requires-Dist: pydantic-settings<3.0,>=2.4
Requires-Dist: tzdata>=2024.1
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: pytest-asyncio<1,>=0.24; extra == "dev"
Requires-Dist: twine<7,>=6; extra == "dev"

# xHR Assistant MCP

`xhr-assistant-mcp` connects AI agents to xHR through the Model Context
Protocol (MCP). It runs locally over stdio and includes the xHR skill catalog
required by the agent, so users do not need to clone another repository.

## Requirements

- Python 3.11 or newer
- An xHR access token for the environment you want to use
- An MCP client that supports stdio servers

## Install

Installing with `pipx` keeps the MCP server isolated and makes the
`xhr-assistant` command available globally:

```bash
python -m pip install --user pipx
python -m pipx ensurepath
pipx install xhr-assistant-mcp
```

Alternatively, install it in a virtual environment:

```bash
python -m venv .venv
```

Activate the environment:

```bash
# macOS or Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1
```

Then install the package:

```bash
python -m pip install xhr-assistant-mcp
```

## Configure an MCP client

When installed with `pipx`, use this stdio configuration:

```json
{
  "command": "xhr-assistant",
  "args": ["mcp"],
  "env": {
    "XHR_AUTHORIZATION": "Bearer <XHR_ACCESS_TOKEN>"
  }
}
```

If the MCP client cannot find commands from your `PATH`, use the absolute path
returned by:

```bash
python -c "import shutil; print(shutil.which('xhr-assistant'))"
```

For a virtual-environment installation, point `command` at that environment's
Python executable:

```json
{
  "command": "/absolute/path/to/.venv/bin/python",
  "args": ["-m", "xhr_assistant_mcp", "mcp"],
  "env": {
    "XHR_AUTHORIZATION": "Bearer <XHR_ACCESS_TOKEN>"
  }
}
```

On Windows, the executable path is typically
`C:\\absolute\\path\\to\\.venv\\Scripts\\python.exe`.

Restart or reconnect the MCP client after changing its configuration.

## Environments

Production is the default environment:

| Environment | API | Application |
| --- | --- | --- |
| `prod` | `https://api.x-hr.co` | `https://app.x-hr.co` |
| `sandbox` | `https://api.sandbox.x-hr.co` | `https://sandbox.x-hr.co` |

Select an environment before starting the MCP server:

```bash
xhr-assistant config set-env sandbox
xhr-assistant config show
```

Use an access token issued by the selected environment. Changing environments
clears the cached account context, so reconnect the MCP client afterward.

To keep separate configurations for different MCP clients, set
`XHR_ASSISTANT_CONFIG_FILE` in each server configuration:

```json
{
  "command": "xhr-assistant",
  "args": ["mcp"],
  "env": {
    "XHR_ASSISTANT_CONFIG_FILE": "/absolute/path/to/xhr-sandbox.json",
    "XHR_AUTHORIZATION": "Bearer <SANDBOX_XHR_ACCESS_TOKEN>"
  }
}
```

Initialize that specific configuration once:

```bash
# macOS or Linux
XHR_ASSISTANT_CONFIG_FILE=/absolute/path/to/xhr-sandbox.json \
  xhr-assistant config set-env sandbox
```

```powershell
# Windows PowerShell
$env:XHR_ASSISTANT_CONFIG_FILE = "C:\path\to\xhr-sandbox.json"
xhr-assistant config set-env sandbox
```

### Environment variables

| Variable | Purpose |
| --- | --- |
| `XHR_AUTHORIZATION` | Bearer access token used for xHR API requests. Recommended for backend and non-interactive agents. |
| `XHR_ASSISTANT_CONFIG_FILE` | Optional path to an isolated configuration file. |
| `XHR_API_BASE_URL` | Optional API URL used when creating a new configuration file. |
| `XHR_APP_URL` | Optional application URL used when creating a new configuration file. |

Do not commit access tokens or place them in agent prompts. Supply secrets with
your process environment or secret manager.

## MCP tools

The agent workflow uses two restricted tools:

- `read` reads an approved xHR skill entrypoint. Agents start at
  `skills/SKILL.md`, select a domain, and read the matching leaf skill.
- `exec` runs only a script declared by the selected leaf skill. It is not a
  general-purpose shell.

The MCP server attaches the configured xHR context to API operations. The xHR
API remains responsible for authentication and authorization.

## MCP prompt

The server publishes the `xhr_assistant_system_prompt` prompt. MCP clients can
load it as the system instructions for an xHR-capable agent.

> **Required integration step:** inject this prompt into the agent's system
> instructions. Connecting the MCP server alone exposes the tools, but does not
> teach the agent the required skill-navigation and safe-execution workflow.

The prompt accepts a `mode` argument:

- `full` (default) includes the domain catalog.
- `compact` includes only the navigation, execution, authentication, and data
  safety contract.

Python agent hosts can retrieve the same instructions directly:

```python
import os

from xhr_assistant_mcp import get_agent_instructions

system_prompt = get_agent_instructions(mode="full")

# Pass both values to your agent framework:
agent_config = {
    "instructions": system_prompt,
    "mcp_servers": {
        "xhr-assistant": {
            "command": "xhr-assistant",
            "args": ["mcp"],
            "env": {
                "XHR_AUTHORIZATION": os.environ["XHR_AUTHORIZATION"],
            },
        }
    },
}
```

`agent_config` is framework-neutral pseudoconfiguration: map `instructions` to
your framework's system/developer prompt field and map the stdio server object
to its MCP configuration. Keep the token in the backend process environment;
do not copy it into `system_prompt`.

If the host supports MCP prompts natively, it may fetch
`xhr_assistant_system_prompt` from the connected server instead. Inject the
returned text before the agent handles xHR requests.

## Verify the installation

```bash
xhr-assistant --help
xhr-assistant config show
xhr-assistant prompt --mode compact
```

The MCP server communicates over stdin/stdout, so start it through an MCP
client rather than expecting an HTTP port or browser page.

