@adviverse/mcp 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.
package/LICENSE ADDED
@@ -0,0 +1,25 @@
1
+ Adviverse SDK License Agreement
2
+
3
+ Copyright (c) 2026 Adviverse. All rights reserved.
4
+
5
+ This package (the "Software") is licensed, not sold. Subject to your compliance
6
+ with this Agreement and the Adviverse terms of service, Adviverse grants you a
7
+ limited, non-exclusive, non-transferable, revocable license to use the Software
8
+ solely to integrate your application or service with the Adviverse ad network.
9
+
10
+ You may not: (a) modify, reverse engineer, decompile, or disassemble the Software
11
+ except to the extent applicable law expressly permits; (b) remove or alter any
12
+ proprietary notices; (c) redistribute, sell, sublicense, rent, or lease the
13
+ Software on a standalone basis; or (d) use the Software to build or operate a
14
+ competing advertising network.
15
+
16
+ The Software is provided "AS IS", without warranty of any kind, express or
17
+ implied, including but not limited to the warranties of merchantability, fitness
18
+ for a particular purpose, and noninfringement. To the maximum extent permitted by
19
+ law, Adviverse shall not be liable for any claim, damages, or other liability
20
+ arising from or in connection with the Software.
21
+
22
+ This license terminates automatically if you breach it; on termination you must
23
+ cease all use and delete all copies.
24
+
25
+ Licensing inquiries: legal@adviverse.com
package/README.md ADDED
@@ -0,0 +1,83 @@
1
+ # @adnet/mcp — Adviverse MCP server
2
+
3
+ A [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI
4
+ agents manage an Adviverse account through a curated, typed toolset (backed by
5
+ [`@adnet/sdk`](../../services/sdk)).
6
+
7
+ ## What it exposes (20 tools)
8
+
9
+ - **Account** — `whoami`
10
+ - **Campaigns** — `list_campaigns`, `get_campaign`, `create_campaign`, `update_campaign`, `submit_campaign`, `set_campaign_status`
11
+ - **Creatives** — `list_creatives`, `create_creative`
12
+ - **Inventory** — `list_properties`, `create_property`, `verify_property`, `list_placements`, `create_placement`, `get_placement_tag`
13
+ - **Finance (read-only)** — `get_balance`, `list_ledger`
14
+ - **Reporting** — `advertiser_report`, `publisher_report`
15
+ - **Deals** — `list_deals`
16
+
17
+ Treasury moves (deposits/payouts) and API-key minting are intentionally **not**
18
+ exposed — those stay human-gated in the dashboard.
19
+
20
+ ## Auth
21
+
22
+ Create a scoped key in the dashboard (**Settings → API keys**) — pick **Read-only**
23
+ for a monitoring agent or **Read & write** for one that manages campaigns/inventory.
24
+ The server reads it from the environment:
25
+
26
+ | Env var | Required | Default |
27
+ |---|---|---|
28
+ | `ADVIVERSE_API_KEY` | yes | — (`ak_<prefix>.<secret>`) |
29
+ | `ADVIVERSE_BASE_URL` | no | `https://adviverse.com` |
30
+
31
+ A read-only key makes every mutating tool return a `403 missing scope: write` —
32
+ scopes are enforced server-side.
33
+
34
+ ## Hosted (no install) — `https://mcp.adviverse.com/mcp`
35
+
36
+ A multi-tenant Streamable-HTTP server is hosted for you. Point any remote-MCP
37
+ client at the URL and pass **your own** key in the `Authorization` header — the
38
+ server runs a per-session client bound to that key (keys are never shared):
39
+
40
+ ```json
41
+ {
42
+ "mcpServers": {
43
+ "adviverse": {
44
+ "url": "https://mcp.adviverse.com/mcp",
45
+ "headers": { "Authorization": "Bearer ak_xxx.yyy" }
46
+ }
47
+ }
48
+ }
49
+ ```
50
+
51
+ No key → `401`. The hosted server (`src/http.ts`) talks to the control-plane
52
+ internally; see `deploy/docker-compose.yml` for the service definition.
53
+
54
+ ## Run locally (stdio)
55
+
56
+ ```bash
57
+ pnpm --filter @adnet/mcp build # bundles standalone dist/index.js (stdio) + dist/http.js
58
+ ADVIVERSE_API_KEY=ak_xxx.yyy node dist/index.js
59
+ ```
60
+
61
+ ### Claude Desktop / other MCP clients
62
+
63
+ ```json
64
+ {
65
+ "mcpServers": {
66
+ "adviverse": {
67
+ "command": "node",
68
+ "args": ["/abs/path/packages/mcp/dist/index.js"],
69
+ "env": { "ADVIVERSE_API_KEY": "ak_xxx.yyy" }
70
+ }
71
+ }
72
+ }
73
+ ```
74
+
75
+ The build is bundled (no `node_modules` needed at the run site), so the single
76
+ `dist/index.js` is all you ship.
77
+
78
+ ## Regenerating against API changes
79
+
80
+ The MCP is hand-curated on top of `@adnet/sdk`; the full machine-readable surface
81
+ lives at `GET /v1/docs-json` (and Swagger UI at `/v1/docs`). Regenerate the spec
82
+ with `pnpm --filter @adnet/control-plane openapi` if you want to codegen clients
83
+ for the long-tail endpoints not surfaced here.