@staraio/mcp 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +55 -2
  2. package/index.js +96 -0
  3. package/package.json +13 -4
package/README.md CHANGED
@@ -1,3 +1,56 @@
1
- # Temporary Holding Version
1
+ # @staraio/mcp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ MCP server for the [Star API](https://docs.staraio.co): Star waits in a sale's virtual line for
4
+ you and hands over each place as it reaches the front, so an agent can pass the line through tools
5
+ instead of raw HTTP.
6
+
7
+ ## Claude Code
8
+
9
+ ```bash
10
+ claude mcp add star --env STAR_API_KEY=sk_live_... -- npx -y @staraio/mcp
11
+ ```
12
+
13
+ Use a test key (`sk_test_...`) to build against the simulation. Create keys in the dashboard
14
+ (dashboard.staraio.co, API Platform).
15
+
16
+ ## Other MCP clients
17
+
18
+ ```json
19
+ {
20
+ "mcpServers": {
21
+ "star": {
22
+ "command": "npx",
23
+ "args": ["-y", "@staraio/mcp"],
24
+ "env": { "STAR_API_KEY": "sk_live_..." }
25
+ }
26
+ }
27
+ }
28
+ ```
29
+
30
+ `STAR_API_URL` overrides the base URL (testing only).
31
+
32
+ ## Tools
33
+
34
+ | Tool | What it does |
35
+ |---|---|
36
+ | `list_sites` | The supported sites and the goal each one offers. |
37
+ | `get_credits` | The key's balance, what live runs hold back, and the price of a pass. |
38
+ | `start_run` | Start a run: `event_url`, `passes`, `tasks`, `proxies`, and optionally `category`, `test_outcome` (test keys) and `idempotency_key`. |
39
+ | `get_run` | A run's current state and each slot's hand-over. |
40
+ | `wait_for_run` | Block until the run changes in a way that matters, then return it. Call it in a loop. |
41
+ | `list_runs` | Your runs, newest first, to recover a lost id. |
42
+ | `stop_run` | Stop a run and release its places. |
43
+
44
+ The tool does not take `accounts`. Run account-based sites (Ticketmaster) with `POST /v1/runs`
45
+ instead, so credentials never pass through the agent.
46
+
47
+ ## The usual loop
48
+
49
+ 1. `start_run` with the link that starts the line (the event or sale page, not a queue link you
50
+ built) and your proxies.
51
+ 2. `wait_for_run` in a loop while the run is in line. Stop when the run's `ended` is `true` (every
52
+ slot is ready or out).
53
+ 3. When a slot is `ready`, open its `handoff` and buy.
54
+
55
+ Keep `STAR_API_KEY` on the machine running the server, never in a browser. Full docs:
56
+ https://docs.staraio.co/mcp
package/index.js ADDED
@@ -0,0 +1,96 @@
1
+ #!/usr/bin/env node
2
+ // Star API as MCP tools. Configure with STAR_API_KEY (required) and STAR_API_URL.
3
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
4
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
5
+ import { z } from "zod";
6
+
7
+ import { StarError, client, waitForChange } from "@staraio/sdk";
8
+
9
+ const key = process.env.STAR_API_KEY;
10
+ if (!key) {
11
+ console.error("STAR_API_KEY is required");
12
+ process.exit(1);
13
+ }
14
+ const api = client({ baseUrl: process.env.STAR_API_URL ?? "https://api.staraio.co", key });
15
+
16
+ const server = new McpServer({ name: "star", version: "0.1.0" });
17
+
18
+ const ok = (data) => ({ content: [{ type: "text", text: JSON.stringify(data, null, 2) }] });
19
+
20
+ // Every tool returns the API's answer, or its error as {code, message, suggested_action}
21
+ // marked isError, so the model sees the same contract as a direct API caller.
22
+ function tool(name, description, inputSchema, run) {
23
+ server.registerTool(name, { description, inputSchema }, async (args) => {
24
+ try {
25
+ return ok(await run(args));
26
+ } catch (err) {
27
+ if (err instanceof StarError) return { ...ok(err.detail ?? { message: err.message }), isError: true };
28
+ throw err;
29
+ }
30
+ });
31
+ }
32
+
33
+ tool("list_sites", "Supported sites and the goals each one offers.", {}, () =>
34
+ api.sites(),
35
+ );
36
+
37
+ tool("get_credits", "The key's credit balance, what live runs hold back, and the price of a pass. A run that needs more answers insufficient_credits; a person adds credits through the checkout link.", {}, () =>
38
+ api.credits(),
39
+ );
40
+
41
+ tool(
42
+ "start_run",
43
+ "Start a run: Star holds places in the sale's virtual line with the user's own proxies and, as each reaches the front, hands over its link for the user to open and buy themselves. Returns the run object; follow it with wait_for_run.",
44
+ {
45
+ event_url: z.string().describe("The link that starts the line: the event or sale page, not a queue link you built. A hand-assembled queue URL is refused event_not_found or ends failed."),
46
+ goal: z.enum(["pass"]).default("pass").describe("What the run works toward; list_sites shows each site's goals"),
47
+ passes: z.number().int().min(1).max(50).describe("Places at the front to hand over, one per buyer"),
48
+ tasks: z.number().int().min(1).max(200).describe("Places Star holds in line to get them; more tasks, better odds"),
49
+ proxies: z.array(z.string().max(512)).min(1).describe("host:port:user:pass"),
50
+ category: z.string().regex(/^\d{1,4}$/).optional().describe("PuntoTicket ticket category code; defaults to the general sale"),
51
+ test_outcome: z.enum(["link", "session", "no_line", "fail"]).optional().describe("Test keys (sk_test_) only: how the simulated run plays out; defaults to link"),
52
+ idempotency_key: z.string().max(128).optional().describe("Reuse to get the same run back instead of a new one"),
53
+ },
54
+ ({ idempotency_key, ...body }) => api.startRun(body, idempotency_key),
55
+ );
56
+
57
+ tool(
58
+ "list_runs",
59
+ "The key's runs, newest first, as last stored: use it to find a run whose id was lost, then get_run for its live state.",
60
+ {
61
+ state: z.enum(["live", "ended"]).optional(),
62
+ limit: z.number().int().min(1).max(100).default(20),
63
+ cursor: z.string().max(200).optional().describe("next_cursor from the previous page"),
64
+ },
65
+ (params) => api.listRuns(params),
66
+ );
67
+
68
+ tool("get_run", "Current state of a run and of each slot. A slot at the front carries its handoff: a link to open, or a session (url, user_agent, cookies) to load into a browser you control, plus an extension_url for a person with the Star extension.", { run_id: z.string() }, ({ run_id }) =>
69
+ api.getRun(run_id),
70
+ );
71
+
72
+ tool(
73
+ "wait_for_run",
74
+ "Wait until the run changes in a way that matters (a slot reached the front and has its link, a slot failed, the run ended) or the timeout passes, then return it. Call in a loop while the run is in line.",
75
+ // MCP clients time a tool call out at 60s by default, so one wait stays under it.
76
+ { run_id: z.string(), timeout_seconds: z.number().int().min(1).max(55).default(45) },
77
+ ({ run_id, timeout_seconds }) => waitForChange(api, run_id, { timeoutMs: timeout_seconds * 1000 }),
78
+ );
79
+
80
+ tool("stop_run", "Stop a run: its places still in line are released; slots already handed over keep their links. Returns the run as it ended.", { run_id: z.string() }, async ({ run_id }) => {
81
+ await api.stopRun(run_id);
82
+ return api.getRun(run_id);
83
+ });
84
+
85
+ tool(
86
+ "report_issue",
87
+ "Report a problem to Star support in one call. Pass the run_id of a run that is stuck and Star attaches its state, so the report carries context. Use it when a run is broken, a hand-over will not open, or the API keeps rejecting something you cannot resolve. Returns the ticket id.",
88
+ {
89
+ message: z.string().min(1).max(4000).describe("What is wrong, in plain words"),
90
+ run_id: z.string().max(200).optional().describe("The run this is about; Star attaches its state"),
91
+ severity: z.enum(["low", "normal", "urgent"]).default("normal").describe("How urgent it is"),
92
+ },
93
+ (body) => api.reportIssue(body),
94
+ );
95
+
96
+ await server.connect(new StdioServerTransport());
package/package.json CHANGED
@@ -1,6 +1,15 @@
1
1
  {
2
2
  "name": "@staraio/mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "MCP server for the Star API: start ticket runs, follow them and answer what they ask.",
5
+ "type": "module",
6
+ "bin": { "star-mcp": "index.js" },
7
+ "files": ["index.js", "README.md"],
8
+ "engines": { "node": ">=20" },
9
+ "scripts": { "test": "node --test" },
10
+ "dependencies": {
11
+ "@modelcontextprotocol/sdk": "^1.32.1",
12
+ "@staraio/sdk": "^0.1.0",
13
+ "zod": "^4.0.0"
14
+ }
15
+ }