# @dailui/omega-api-mcp

An [MCP](https://modelcontextprotocol.io) server that gives an AI agent one tool to reach the **Omega-API judge**.

> Give agents access to the judge without moving the judge into the agent.

The agent calls the tool with a turn; the judge — which stays on the server — returns a decision and a gate action.
Zero judge logic runs in the agent. Apache-2.0. Node 18+.

## The tool

**`omega_judge_turn`** — judge one agent turn: does the conversational process move? Returns a decision and a gate
action. It measures process shape, not whether the goal was reached.

Input:

| field          | type                 | notes                                             |
| -------------- | -------------------- | ------------------------------------------------- |
| `input`        | string (optional)    | the user / incoming message                       |
| `output`       | string (optional)    | the agent's drafted reply (at least one of these) |
| `session_id`   | string (**required**) | one id per conversation · the same on every turn · a new id for a new conversation |
| `turn_id`      | string (optional)    | omit for a single agent · Hive member: `{agent}_{run_token}_{nnn}` |
| `privacy_mode` | `FULL` \| `REDACTED` | optional                                          |

Result:

```json
{
  "turn_id": "t_…",
  "decision": "PROCEED | CLARIFY | STOP",
  "reason_family": "…",
  "side": "…",
  "gate": { "action": "release | clarify | suppress | none", "release_original": true }
}
```

Act on the gate **before** showing the reply: `release` → show · `clarify` → regenerate then call again ·
`suppress` → stop or escalate · `none` → observe only, show.

## Reading agents together (Hive)

A Hive draws the relation of two agents **only** from a shared token in `turn_id`, set **before** the run.
Timing can only suggest an association; it never certifies one. Without the token each agent is still judged normally.

```
turn_id = {agent}_{run_token}_{nnn}
agent      your label · [a-z0-9-]
run_token  10 lowercase hex · one per PAIR of agents, per run · new run = new token
nnn        3 digits shared by both agents for the same exchange (agents counting on their own: s001 · declared, not aligned · no relation graph)
```

Rules: one `session_id` per agent for the whole token (a restart needs a new token) · three agents on one token are not certified ·
a re-used `turn_id` for a different turn returns `409 TURN_CONFLICT` and the turn is **not recorded**. Full rules: [omega.dailui.com/integrations.php](https://omega.dailui.com/integrations.php) and your account's Integration page.

In this server `session_id` is required on every call (no implicit session: two conversations are never fused); `409 TURN_CONFLICT` comes back as a visible tool error.

## Before you start: register → key → judge → meter

Register a project and get an API key (`oapi_live_…`) at <https://omega.dailui.com/signup.php>. Your first 100
judgments are free; after that, billing applies.

## Add it to your MCP host

Most hosts (Claude Desktop, IDE agents) launch MCP servers from a config file. Add:

```json
{
  "mcpServers": {
    "omega-api": {
      "command": "npx",
      "args": ["-y", "@dailui/omega-api-mcp"],
      "env": { "OMEGA_API_KEY": "oapi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}
```

The host starts the server over stdio and the `omega_judge_turn` tool becomes available to the agent.

## What it does not claim

It measures whether the process **moved**. It does not promise the agent achieved the user's goal — the two are
independent. It returns no scores or internal measures, only the decision and the gate.

## Links

- Learn more: <https://omega.dailui.com/integrations.php>
- Python client: `pip install omega-api` · JavaScript client: `npm install @dailui/omega-api`
- Examples & HTTP runner: <https://github.com/DaiLui/omega-api-examples>

## License

Apache-2.0.