# linkyun-ops-mcp

MCP adapter for LinkYun operations metrics.

The server exposes MCP tools for Agents and forwards every request to the
`linkyun-agent` Ops HTTP API. It does not connect to databases, generate SQL,
define metrics, or make authorization decisions.

## Tools

- `ops_list_metrics`: list metrics available to the configured operator token.
- `ops_query_metric`: query one backend metric with the backend query contract.
- `ops_get_home_recommendations`: get home banner/platform/hot ranking config.
- `ops_preview_home_recommendations`: validate partial home recommendation config.
- `ops_set_home_recommendations`: replace supplied home recommendation modules with audit.
- `ops_list_agents`: list/find workspace agents with operations fields.
- `ops_get_agent`: get one workspace agent by code.
- `ops_list_agent_tags`: list active tag library and discover categories.
- `ops_update_agent`: update allowed Agent operations fields with audit.
- `ops_get_tracking_summary`: query one campaign tracking funnel summary.
- `ops_get_tracking_breakdown`: compare funnels by `link_id`, `source`, or `campaign`.
- `ops_get_tracking_trend`: query hourly or daily campaign funnel trends.
- `ops_list_tracking_short_links`: list short-link configs, optionally with metrics.
- `ops_create_tracking_short_link`: create a short-link config with audit reason.
- `ops_update_tracking_short_link`: update a short-link config with audit reason.

## Configuration

```text
LINKYUN_OPS_BASE_URL=http://localhost:8080
LINKYUN_OPS_TOKEN=ops_...
LINKYUN_OPS_CLIENT=linkyun-ops-mcp
LINKYUN_OPS_TIMEOUT_MS=10000
```

## Development

```powershell
npm.cmd install
npm.cmd run build
npm.cmd test
npm.cmd run lint
openspec validate ops-mcp-adapter-mvp --strict
openspec validate ops-agent-management-tools --strict
openspec validate ops-tracking-analytics-v2 --strict
```

## Claude Desktop Example

```json
{
  "mcpServers": {
    "linkyun-ops": {
      "command": "node",
      "args": ["D:/Projects/linkyun/linkyun-ops/linkyun-ops-mcp/dist/index.js"],
      "env": {
        "LINKYUN_OPS_BASE_URL": "http://localhost:8080",
        "LINKYUN_OPS_TOKEN": "ops_..."
      }
    }
  }
}
```

Agents must convert relative time phrases into explicit RFC3339 timestamps
before calling `ops_query_metric` or tracking analytics tools.

## Metric Notes

`ops_query_metric` forwards metric codes to the backend Ops API. Adding a new
backend metric usually does not require an MCP tool schema change unless the
query contract itself changes.

Common backend metric codes:

- `accounts_created`
- `registered_users`
- `agents_created`
- `chat_messages`
- `agent_assistant_messages`
- `agent_likes`
- `moment_likes`
- `moment_favorites`

`agent_likes`, `moment_likes`, and `moment_favorites` support `rank` in the
backend. They also accept optional `agent_code` for aggregate, timeseries, and
compare queries; for Moment metrics, `agent_code` means Moments belonging to
that Agent.

## Tracking Notes

Tracking analytics tools forward to backend Ops APIs and return backend JSON
unchanged. Adding a new backend event count or conversion-rate field does not
require an MCP schema change unless the request contract changes.

Supported event counts include:

- `click`
- `landing_open`
- `valid_open`
- `register_start`
- `register_success`
- `create_idol_start`
- `create_idol_success`
- `chat_start`
- `first_message_sent`
- `first_agent_reply_received`
- `discovery_view`
- `agent_search`
- `agent_design_sheet_view`
- `add_friend_success`
- `message_sent`
- `agent_reply_received`
- `chat_send_fail`
- `agent_reply_timeout`
- `group_chat_create_success`
- `group_chat_upgrade_success`
- `group_message_sent`
- `group_agent_reply_received`
- `group_reply_timeout`
- `moments_view`
- `agent_moments_view`
- `moment_like`
- `moment_comment`
- `share_agent_open`
- `guest_session_create_success`
- `guest_message_sent`
- `guest_reply_received`
- `guest_enter_app`
- `welcome_view`
- `guest_explore_click`
- `guest_home_view`
- `guest_tab_click`
- `auth_required_view`
- `auth_required_source`
- `auth_required_action`
- `auth_required_close`
- `auth_method_select`
- `auth_success`
- `auth_fail`
- `redirect_after_auth_start`
- `redirect_after_auth_success`
- `redirect_after_auth_fail`
- `pending_action_execute_success`
- `pending_action_execute_fail`
- `guest_to_auth_start`
- `guest_to_auth_success`
- `guest_create_intent`
- `guest_companion_intent`
- `guest_interaction_intent`

Tracking responses may include these conversion-rate fields:

- `landing_open_rate = landing_open / click`
- `valid_open_rate = valid_open / landing_open`
- `register_start_rate = register_start / landing_open`
- `register_success_rate = register_success / landing_open`
- `create_idol_start_rate = create_idol_start / landing_open`
- `create_idol_success_rate = create_idol_success / landing_open`
- `register_to_create_success_rate = create_idol_success / register_success`
- `chat_start_rate = chat_start / valid_open`
- `first_message_sent_rate = first_message_sent / valid_open`
- `first_agent_reply_received_rate = first_agent_reply_received / first_message_sent`

Use `ops_get_tracking_breakdown` for channel or campaign comparison, and
`ops_get_tracking_trend` for day/hour trend charts. Short-link writes require
`reason`; disabling a link uses `status: "disabled"` rather than delete.

Use `ops_list_tracking_short_links` with `include_metrics=true` and explicit
`created_from` / `created_to` values to return per-link funnel metrics.

Example tracking questions:

- List short links with metrics for `2026-07-01T00:00:00+08:00` to `2026-07-08T00:00:00+08:00`.
- Compare `ai_world_launch_202606` by `source` for an explicit date range.
- Query daily funnel trend for one `link_id`.
- Query whether campaign traffic reached chat activation using `chat_start`,
  `first_message_sent`, and `first_agent_reply_received`.