Metadata-Version: 2.4
Name: zainar-halo-agent-tools
Version: 0.1.0
Summary: ZaiNar Halo MCP server — FastMCP tools and resources for RF proximity awareness
Author: Zainar
License: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: zainar-halo>=0.1.0
Requires-Dist: fastmcp>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

# zainar-halo-agent-tools

FastMCP server exposing ZaiNar RF halo awareness to LLM agents and Claude Desktop.

Gives an agent the ability to ask "what's around robot amr-7 right now?" and get
a live answer — entity types, 3D ranges (cm), closing speeds — sourced from
ZaiNar's RF network, not from cameras or line-of-sight sensors.

## Install

```bash
pip install zainar-halo-agent-tools
```

## Run the MCP server

```bash
zainar-halo-mcp
```

Add to Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "zainar-halo": { "command": "zainar-halo-mcp" }
  }
}
```

Inspect interactively:
```bash
npx @modelcontextprotocol/inspector zainar-halo-mcp
```

## Tools

| Tool | What it does |
|---|---|
| `get_halo(device_id)` | Rich egocentric halo — who's around this node, ranges, closing speeds |
| `set_halo_config(device_id, ...)` | Set safety perimeter and entity filters (operator-owned) |
| `query_near(device_id, radius_cm, entity_types)` | Ad-hoc proximity query, no persistent config change |
| `list_tracked_entities()` | All tracked entities with 3D positions and freshness |
| `list_zones()` | Active zones and entity counts |
| `get_zone_entities(zone)` | Raw TMI position list for a zone |

## Resources

| URI | What it returns |
|---|---|
| `zainar://halo/{device_id}` | Live halo JSON for a node |
| `zainar://zone/{zone}` | TMI position list for a zone |
| `zainar://entities` | All tracked entities |

## Demo vs. production

The out-of-the-box server uses `DemoLocationService` — a fixed set of 6
demo positions (warehouse scenario with AMR, forklift, human, drone).

In production, swap it for `ZainarLocationService` from the
`zainar-location-service` package, which connects to the kinesis-gw
WebSocket and maintains a live position queue. The tool signatures are
identical.

## See also

- `zainar-halo` — the robot client lib this package builds on
- `CLAUDE.md` at repo root — full architecture and integration guide
