Resolve tickets 067-069: named sessions, MCP server, embedded SKILL.md

Adds a sessions/<name>.json registry (068) so a running ottyl instance can be discovered by name; an `ottyl mcp --session <name>` subcommand (067) that starts a short-lived MCP server over stdio (via the official rmcp SDK), proxying query_logs/declare_param/declare_metric/create_dashboard/ add_panel/get_dashboard tool calls onto the existing HTTP API; and a SKILL.md (069), embedded into the binary and served at GET /SKILL.md, that documents how an agent connects to and drives a running instance. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A1ZJ3SrayzLzVndhVq9BmS
2026-09-06 13:57:30 +01:00
parent de9ba6f01b
commit c77404ba4e
8 changed files with 1093 additions and 7 deletions
@@ -0,0 +1,91 @@
+---
+name: ottyl
+description: Query and configure a running ottyl observability instance (logs, params, metrics, dashboards) via its MCP server.
+---
+
+# ottyl
+
+ottyl turns a piped command's stdout into a searchable log timeline plus ad-hoc metrics and
+dashboards, served from a single process. This doc covers how an agent connects to and drives a
+*running* instance.
+
+## Find a session
+
+Each `ottyl` process registers itself under a name (random, e.g. `comic-gazelle`, unless started
+with `--name <name>`). List known sessions:
+
+```
+ottyl sessions
+# comic-gazelle    port=51423   pid=8421
+```
+
+## Connect an MCP client
+
+Start the MCP server (a separate short-lived process) pointed at that session, and register it
+with your MCP client (e.g. Claude Code's `.mcp.json`):
+
+```
+ottyl mcp --session comic-gazelle
+# or, if you already know the port:
+ottyl mcp --port 51423
+```
+
+This exposes six tools, each a thin proxy onto the target instance's HTTP API.
+
+## Tools
+
+### `query_logs`
+Count or read log lines matching a FilterBar query.
+
+```json
+{ "filter": "regex(\"error\")", "count_only": true }
+```
+
+### `declare_param`
+Extract a named value from matching log lines.
+
+```json
+{
+  "name": "status_code",
+  "message_match_regex": "status=(\\d+)",
+  "capture_group": "1",
+  "kind": "number"
+}
+```
+
+### `declare_metric`
+Bucket event counts/values by label, derived from matching log lines.
+
+```json
+{
+  "name": "errors_total",
+  "message_match_regex": "level=error",
+  "label_params": ["status_code"]
+}
+```
+
+### `create_dashboard`
+Create an empty dashboard in a profile (defaults to the active profile).
+
+```json
+{ "name": "Errors" }
+```
+
+### `add_panel`
+Add a panel to a dashboard, or update one in place by `panel_id`.
+
+```json
+{
+  "dashboard_id": "<id from create_dashboard>",
+  "title": "Errors over time",
+  "promql": "rate(errors_total[5m])",
+  "chart_type": "line"
+}
+```
+
+### `get_dashboard`
+Read a dashboard's current panels.
+
+```json
+{ "dashboard_id": "<id>" }
+```