# Sentiac agent tools

[![CI](https://github.com/Sentiac/agent-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/Sentiac/agent-tools/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/@sentiac/mcp)](https://www.npmjs.com/package/@sentiac/mcp)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

One MCP server and a set of skills that let a coding agent (Claude Code, Codex, OpenCode, Pi, Cursor, …) use Sentiac tools.

| | What it is | Where |
|---|---|---|
| **`@sentiac/mcp`** | The MCP server (stdio). Toolsets are loaded by name; today: **Visor**, the browser viewer for ROS 2 robots, driven by your agent. | [`packages/mcp`](packages/mcp) |
| **Skills** | [Agent Skills](https://agentskills.io) (`SKILL.md`) that teach an agent a workflow. | [`skills/`](skills) |
| **Claude Code plugin** | The same repo is a plugin: skills + MCP server in one install. | [`.claude-plugin/`](.claude-plugin), [`.mcp.json`](.mcp.json) |

Skills today: `sentiac-visor` (draw any robot data with recipes), `sentiac-visor-nav2` (a Nav2 view), `sentiac-visor-moveit2` (a MoveIt 2 arm view).

## Install

The quickest way, for every agent you have installed (it shows what it will change and asks first):

```bash
npx -y @sentiac/mcp init
```

`init` adds the MCP server in each agent's own way (`claude mcp add`, `codex mcp add`, `opencode.json`, `~/.cursor/mcp.json`) and copies the skills to where that agent reads them. Run `npx -y @sentiac/mcp uninstall` to undo it, `npx -y @sentiac/mcp doctor` to check things.

Or by hand, per agent:

| Agent | MCP server | Skills |
|---|---|---|
| Claude Code | `claude mcp add --scope user sentiac -- npx -y @sentiac/mcp@^0.1.0` | `/plugin marketplace add Sentiac/agent-tools` then `/plugin install sentiac@sentiac-tools` (brings both), or `npx skills add Sentiac/agent-tools` |
| Codex | `codex mcp add sentiac -- npx -y @sentiac/mcp@^0.1.0` | `npx skills add Sentiac/agent-tools` (installs to `~/.agents/skills`) |
| OpenCode | `opencode.json`: `"mcp": { "sentiac": { "type": "local", "command": ["npx", "-y", "@sentiac/mcp@^0.1.0"] } }` | `npx skills add Sentiac/agent-tools` |
| Cursor | `~/.cursor/mcp.json`: `"mcpServers": { "sentiac": { "command": "npx", "args": ["-y", "@sentiac/mcp@^0.1.0"] } }` | |
| Pi | no built-in MCP client (use an MCP extension) | `npx skills add Sentiac/agent-tools -a pi` |
| Anything else | any client that can start a stdio server: `npx -y @sentiac/mcp` | copy a folder from [`skills/`](skills) |

Only some toolsets: `npx -y @sentiac/mcp --tools visor` (or `SENTIAC_TOOLS=visor`). Every tool description costs context in every conversation, so load only what you use.

## Using Visor with your agent

1. Open Visor in your browser, then ask your agent to *"link Visor"*. It gives you a short code; enter it in the **Link your agent** box that appears at the bottom right of Visor (once; Visor remembers it). Both must be on the same computer. Chrome asks once whether Visor may connect to this computer (it only ever talks to your own machine); choose Allow. If the box does not show up, open Settings, Agent, and press Look again.
2. Start your robot's Visor bridge and give the agent the connection code it prints.
3. Ask for what you want to see: *"show the lidar and the map"*, *"plot the odometry speed"*, *"set up a Nav2 view"*.

The MCP server runs on your machine and talks to your own browser tab over a local, token-protected link, so the agent sees and changes what you see. It cannot write to the robot. Scripts an agent writes run in a sandbox in your browser, and you are asked once before the first one runs.

## Develop and test locally (before anything is published)

```bash
git clone https://github.com/Sentiac/agent-tools && cd agent-tools
npm install
npm test            # unit, end-to-end (stdio server + a fake page), installer, and the packed tarball
npm run check       # syntax, skills (strict YAML, names, referenced tools), versions, vendored files
```

Try it in an agent without publishing:

```bash
npm run local:plugin            # builds .local/plugin: the same plugin, running this checkout with node
claude --plugin-dir .local/plugin
node packages/mcp/bin/sentiac-mcp.mjs init --local     # or set up every agent to run this checkout
```

Any agent that reads Claude-style plugin folders (`.claude-plugin/`, `skills/`, `.mcp.json`) can load `.local/plugin` the same way.

More in [docs/DEVELOPING.md](docs/DEVELOPING.md) (layout, how the Visor library is brought in, adding a toolset or a skill) and [docs/PUBLISHING.md](docs/PUBLISHING.md) (what to settle and do before the first release).

## Contributing

Issues and pull requests are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). Report security problems privately, as described in [SECURITY.md](SECURITY.md). Changes are listed in [CHANGELOG.md](CHANGELOG.md).

## License

[MIT](LICENSE) © 2026 Sentiac Private Limited