@staraio/mcp 0.0.0-stage → 0.2.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.
- package/README.md +60 -2
- package/index.js +16 -0
- package/package.json +13 -4
- package/tools.js +127 -0
package/README.md
CHANGED
|
@@ -1,3 +1,61 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @staraio/mcp
|
|
2
2
|
|
|
3
|
-
|
|
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 sites the tool can run, each with its `link` (which page to send), `link_example`, goals and whether it takes a ticket category. |
|
|
37
|
+
| `list_categories` | The ticket categories of an event (`event_url`), with the `code` to pass as `category` and the default. |
|
|
38
|
+
| `get_credits` | The key's balance, what live runs hold back, and the price of a pass. |
|
|
39
|
+
| `add_credits` | A checkout link (`amount_cents`) for a person to open and pay; credits land once the payment is confirmed. |
|
|
40
|
+
| `start_run` | Start a run: `event_url`, `passes`, `tasks`, `proxies`, and optionally `category`, `test_outcome` (test keys) and `idempotency_key`. |
|
|
41
|
+
| `get_run` | A run's current state, each slot's hand-over and, while live, `proxy_health`. |
|
|
42
|
+
| `wait_for_run` | Block until the run changes in a way that matters, then return it. Call it in a loop. |
|
|
43
|
+
| `list_runs` | Your runs, newest first, to recover a lost id. |
|
|
44
|
+
| `stop_run` | Stop a run and release its places. |
|
|
45
|
+
| `report_issue` | Open a support ticket, with a stuck run's state attached when you pass its `run_id`. |
|
|
46
|
+
|
|
47
|
+
The tool does not take `accounts`, and `list_sites` leaves out the sites that need them. Run
|
|
48
|
+
account-based sites (Ticketmaster) with `POST /v1/runs` instead, so credentials never pass through
|
|
49
|
+
the agent.
|
|
50
|
+
|
|
51
|
+
## The usual loop
|
|
52
|
+
|
|
53
|
+
1. `list_sites`, and send the page the site's `link` asks for. On a site with `categories: true`,
|
|
54
|
+
`list_categories` gives the `code` to pass as `category`.
|
|
55
|
+
2. `start_run` with that link and your proxies.
|
|
56
|
+
3. `wait_for_run` in a loop while the run is in line. Stop when the run's `ended` is `true` (every
|
|
57
|
+
slot is ready or out).
|
|
58
|
+
4. When a slot is `ready`, open its `handoff` and buy.
|
|
59
|
+
|
|
60
|
+
Keep `STAR_API_KEY` on the machine running the server, never in a browser. Full docs:
|
|
61
|
+
https://docs.staraio.co/mcp
|
package/index.js
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Star API as MCP tools over stdio. Configure with STAR_API_KEY (required) and STAR_API_URL.
|
|
3
|
+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
4
|
+
|
|
5
|
+
import { client } from "@staraio/sdk";
|
|
6
|
+
|
|
7
|
+
import { buildServer } from "./tools.js";
|
|
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
|
+
await buildServer(api).connect(new StdioServerTransport());
|
package/package.json
CHANGED
|
@@ -1,6 +1,15 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@staraio/mcp",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
}
|
|
3
|
+
"version": "0.2.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", "tools.js", "README.md"],
|
|
8
|
+
"engines": { "node": ">=20" },
|
|
9
|
+
"scripts": { "test": "node --test" },
|
|
10
|
+
"dependencies": {
|
|
11
|
+
"@modelcontextprotocol/sdk": "^1.32.1",
|
|
12
|
+
"@staraio/sdk": "^0.2.0",
|
|
13
|
+
"zod": "^4.0.0"
|
|
14
|
+
}
|
|
15
|
+
}
|
package/tools.js
ADDED
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
// The Star API as MCP tools, on a server built around any client with the SDK's shape. index.js
|
|
2
|
+
// wires it to stdio and a real key; tests wire it to a fake client, with no network.
|
|
3
|
+
import { createRequire } from "node:module";
|
|
4
|
+
|
|
5
|
+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
6
|
+
import { z } from "zod";
|
|
7
|
+
|
|
8
|
+
import { StarError, waitForChange } from "@staraio/sdk";
|
|
9
|
+
|
|
10
|
+
const { version } = createRequire(import.meta.url)("./package.json");
|
|
11
|
+
|
|
12
|
+
const ok = (data) => ({ content: [{ type: "text", text: JSON.stringify(data, null, 2) }] });
|
|
13
|
+
|
|
14
|
+
export function buildServer(api) {
|
|
15
|
+
const server = new McpServer({ name: "star", version });
|
|
16
|
+
|
|
17
|
+
// Every tool returns the API's answer, or its error as {code, message, suggested_action}
|
|
18
|
+
// marked isError, so the model sees the same contract as a direct API caller.
|
|
19
|
+
function tool(name, description, inputSchema, run) {
|
|
20
|
+
server.registerTool(name, { description, inputSchema }, async (args) => {
|
|
21
|
+
try {
|
|
22
|
+
return ok(await run(args));
|
|
23
|
+
} catch (err) {
|
|
24
|
+
if (err instanceof StarError) return { ...ok(err.detail ?? { message: err.message }), isError: true };
|
|
25
|
+
throw err;
|
|
26
|
+
}
|
|
27
|
+
});
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
tool(
|
|
31
|
+
"list_sites",
|
|
32
|
+
"The sites start_run can run, with the goals and hand-overs each offers. Before start_run, read the site's `link` (which page to send) and `link_example`. When a site has `categories: true`, call list_categories for the event to pick a ticket category. Sites whose line needs the customer's own site accounts are left out on purpose: run those with POST /v1/runs, so credentials never pass through the agent.",
|
|
33
|
+
{},
|
|
34
|
+
async () => {
|
|
35
|
+
const out = await api.sites();
|
|
36
|
+
return { ...out, sites: (out.sites ?? []).filter((s) => !s.accounts) };
|
|
37
|
+
},
|
|
38
|
+
);
|
|
39
|
+
|
|
40
|
+
tool(
|
|
41
|
+
"list_categories",
|
|
42
|
+
"The ticket categories of the event behind a link, as its page shows them now: pass a `code` as start_run's `category`; `default` is what a run without one queues for (null when no category is open), and `open: false` is a category not on sale. A site with `categories: false` answers an empty list. Errors: event_not_found, site_not_supported.",
|
|
43
|
+
{ event_url: z.string().max(2048).describe("The event's link, the same one start_run takes") },
|
|
44
|
+
({ event_url }) => api.categories(event_url),
|
|
45
|
+
);
|
|
46
|
+
|
|
47
|
+
tool(
|
|
48
|
+
"get_credits",
|
|
49
|
+
"The key's credit balance, what live runs hold back, and the price of a pass. A run that needs more answers insufficient_credits; then call add_credits for a checkout link a person opens to pay.",
|
|
50
|
+
{},
|
|
51
|
+
() => api.credits(),
|
|
52
|
+
);
|
|
53
|
+
|
|
54
|
+
tool(
|
|
55
|
+
"add_credits",
|
|
56
|
+
"Create a checkout link to add prepaid credits. An agent cannot pay: give the returned `url` to a person to open and pay, and the credits land once the payment is confirmed (check with get_credits). Live keys only; a test key needs no credits.",
|
|
57
|
+
{
|
|
58
|
+
amount_cents: z.number().int().min(1000).max(500000).describe("Credits to buy, in US cents (1000 to 500000)"),
|
|
59
|
+
},
|
|
60
|
+
(body) => api.creditsCheckout(body),
|
|
61
|
+
);
|
|
62
|
+
|
|
63
|
+
tool(
|
|
64
|
+
"start_run",
|
|
65
|
+
"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.",
|
|
66
|
+
{
|
|
67
|
+
event_url: z.string().max(2048).describe("The link that starts the line, the page list_sites names in the site's `link` (see `link_example`). A link assembled by hand is refused event_not_found or ends failed."),
|
|
68
|
+
goal: z.enum(["pass"]).default("pass").describe("What the run works toward; list_sites shows each site's goals"),
|
|
69
|
+
passes: z.number().int().min(1).max(50).describe("Places at the front to hand over, one per buyer"),
|
|
70
|
+
tasks: z.number().int().min(1).max(200).describe("Places Star holds in line to get them; more tasks, better odds. A live run holds at most 200"),
|
|
71
|
+
proxies: z.array(z.string().max(512)).min(1).max(20000).describe("host:port:user:pass"),
|
|
72
|
+
category: z.string().regex(/^\d{1,4}$/).optional().describe("Ticket category `code` from list_categories, on sites with categories: true; defaults to the event's `default`"),
|
|
73
|
+
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"),
|
|
74
|
+
idempotency_key: z.string().max(128).optional().describe("Reuse to get the same run back instead of a new one"),
|
|
75
|
+
},
|
|
76
|
+
({ idempotency_key, ...body }) => api.startRun(body, idempotency_key),
|
|
77
|
+
);
|
|
78
|
+
|
|
79
|
+
tool(
|
|
80
|
+
"list_runs",
|
|
81
|
+
"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.",
|
|
82
|
+
{
|
|
83
|
+
state: z.enum(["live", "ended"]).optional(),
|
|
84
|
+
limit: z.number().int().min(1).max(100).default(20),
|
|
85
|
+
cursor: z.string().max(200).optional().describe("next_cursor from the previous page"),
|
|
86
|
+
},
|
|
87
|
+
(params) => api.listRuns(params),
|
|
88
|
+
);
|
|
89
|
+
|
|
90
|
+
tool(
|
|
91
|
+
"get_run",
|
|
92
|
+
"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. `handoff.no_line: true` means the sale had no line: the link was reached without waiting and is not charged as a pass. `handoff.expired: true` is a session past its life, its cookies removed. While the run is live, `proxy_health` is {tasks, failing}: tasks running and tasks failing on their proxy right now (null once ended); many failing means rotate the proxies.",
|
|
93
|
+
{ run_id: z.string() },
|
|
94
|
+
({ run_id }) => api.getRun(run_id),
|
|
95
|
+
);
|
|
96
|
+
|
|
97
|
+
tool(
|
|
98
|
+
"wait_for_run",
|
|
99
|
+
"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.",
|
|
100
|
+
// MCP clients time a tool call out at 60s by default, so one wait stays under it.
|
|
101
|
+
{ run_id: z.string(), timeout_seconds: z.number().int().min(1).max(55).default(45) },
|
|
102
|
+
({ run_id, timeout_seconds }) => waitForChange(api, run_id, { timeoutMs: timeout_seconds * 1000 }),
|
|
103
|
+
);
|
|
104
|
+
|
|
105
|
+
tool(
|
|
106
|
+
"stop_run",
|
|
107
|
+
"Stop a run: its places still in line are released; slots already handed over keep their links. Returns the run as it ended.",
|
|
108
|
+
{ run_id: z.string() },
|
|
109
|
+
async ({ run_id }) => {
|
|
110
|
+
await api.stopRun(run_id);
|
|
111
|
+
return api.getRun(run_id);
|
|
112
|
+
},
|
|
113
|
+
);
|
|
114
|
+
|
|
115
|
+
tool(
|
|
116
|
+
"report_issue",
|
|
117
|
+
"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.",
|
|
118
|
+
{
|
|
119
|
+
message: z.string().min(1).max(4000).describe("What is wrong, in plain words"),
|
|
120
|
+
run_id: z.string().max(200).optional().describe("The run this is about; Star attaches its state"),
|
|
121
|
+
severity: z.enum(["low", "normal", "urgent"]).default("normal").describe("How urgent it is"),
|
|
122
|
+
},
|
|
123
|
+
(body) => api.reportIssue(body),
|
|
124
|
+
);
|
|
125
|
+
|
|
126
|
+
return server;
|
|
127
|
+
}
|