@vruum/mcp 0.8.0 → 0.9.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 +1 -1
- package/README.md +28 -22
- package/package.json +1 -1
- package/tools.json +3 -3
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
[](LICENSE)
|
|
5
5
|
[](https://registry.modelcontextprotocol.io)
|
|
6
6
|
|
|
7
|
-
Official MCP access to [**Vruum**](https://vruum.ai), the AI revenue platform. Give your agent the whole revenue motion — research prospects, build pipeline, run email and LinkedIn outreach, triage replies, manage deals through close, and read Stripe-backed revenue truth — through **
|
|
7
|
+
Official MCP access to [**Vruum**](https://vruum.ai), the AI revenue platform. Give your agent the whole revenue motion — research prospects, build pipeline, run email and LinkedIn outreach, triage replies, manage deals through close, and read Stripe-backed revenue truth — through **33 compound tools** rather than a sprawl of endpoints. Outreach runs inside **objectives**: a goal, the people it targets, and the policy for reaching them.
|
|
8
8
|
|
|
9
9
|
This package is a **stdio bridge**: it serves the tool surface locally (no credentials needed to introspect) and proxies execution to `https://api.vruum.ai/mcp` under your token. Every call is authorized server-side — the bridge grants no authority your Vruum account doesn't already have.
|
|
10
10
|
|
|
@@ -63,11 +63,10 @@ env = { VRUUM_MCP_TOKEN = "vk_live_…" }
|
|
|
63
63
|
<summary><b>Already use the Vruum CLI?</b> — no token needed here</summary>
|
|
64
64
|
|
|
65
65
|
```sh
|
|
66
|
-
npx @vruum/cli
|
|
67
|
-
vruum login --token vk_live_…
|
|
66
|
+
npx @vruum/cli login --token vk_live_…
|
|
68
67
|
```
|
|
69
68
|
|
|
70
|
-
Credentials land in `~/.vruum/credentials` and the bridge picks them up automatically — omit the `env` block entirely.
|
|
69
|
+
The CLI needs Node 22+. Credentials land in `~/.vruum/credentials` and the bridge picks them up automatically — omit the `env` block entirely.
|
|
71
70
|
</details>
|
|
72
71
|
|
|
73
72
|
Verify it works without configuring anything:
|
|
@@ -86,44 +85,51 @@ Once connected, these are ordinary requests to your agent:
|
|
|
86
85
|
| *"Review my outreach drafts"* | `get_outreach_review` → you approve, edit, or reject each one |
|
|
87
86
|
| *"Research Acme Corp and tell me if they fit"* | `research` — website, funding, careers signals, ICP match with reasoning |
|
|
88
87
|
| *"Find a warm intro to this person"* | `find_warm_path` — separates verified paths from unverified connector candidates |
|
|
89
|
-
| *"Which
|
|
88
|
+
| *"Which objectives are actually working?"* | `get_objective_outcomes` — contacted, replied, and meetings booked, compared across objectives |
|
|
90
89
|
| *"What's at risk in my pipeline?"* | `inspect_pipeline` — the 5 most at-risk deals, risk-first |
|
|
91
90
|
| *"Draft a LinkedIn post about X"* | `manage_content` — your agent writes it, you approve, Vruum schedules and publishes |
|
|
92
91
|
|
|
93
|
-
|
|
94
|
-
|
|
92
|
+
Your harness authors outreach copy, replies, LinkedIn posts, and comments through
|
|
93
|
+
their review surfaces. Saved analysis can also run on the server after an
|
|
94
|
+
explicit request through `manage_assistant`. Retained email work has a separate
|
|
95
|
+
activation and exact approval contract; analysis does not grant permission to send.
|
|
95
96
|
|
|
96
97
|
## Tool surface
|
|
97
98
|
|
|
98
|
-
|
|
99
|
+
33 compound tools. Read operations inspect saved data; write operations mutate it.
|
|
100
|
+
Some writes buy provider work or produce external effects. Each tool describes
|
|
101
|
+
its own authorization and retry contract.
|
|
99
102
|
|
|
100
103
|
| Area | Tools |
|
|
101
104
|
| --- | --- |
|
|
102
105
|
| **Daily operating** | `get_daily_briefing` · `get_next_actions` · `inspect_pipeline` |
|
|
103
106
|
| **Search & research** | `search` · `fetch` · `research` · `import_prospects` · `find_warm_path` |
|
|
104
107
|
| **People** | `get_person_360` · `manage_person` |
|
|
105
|
-
| **
|
|
108
|
+
| **Relationship identity** | `get_network_identity_review` · `manage_network_identity_resolution` |
|
|
109
|
+
| **Objectives & outreach** | `get_outreach_review` · `manage_messages` · `manage_outreach` · `manage_relationship_action` |
|
|
106
110
|
| **Engagement & content** | `get_engagement_review` · `manage_engagements` · `get_content_review` · `manage_content` |
|
|
107
|
-
| **
|
|
111
|
+
| **Performance** | `get_objective_outcomes` · `get_performance_metrics` |
|
|
108
112
|
| **Deals** | `get_deal_360` · `manage_deal` |
|
|
109
113
|
| **Revenue** | `get_revenue` · `manage_revenue` |
|
|
110
114
|
| **Accounts & knowledge** | `manage_account` · `manage_kb` |
|
|
111
|
-
| **
|
|
115
|
+
| **Imports & assistant** | `manage_history_import` · `manage_assistant` |
|
|
116
|
+
| **Workspaces, config & skills** | `get_operator_companies` · `manage_settings` · `skill` |
|
|
112
117
|
|
|
113
|
-
|
|
118
|
+
`manage_outreach` also creates, configures, launches, and pauses objectives. `get_operator_companies` lists the workspaces your login can act in; it is not limited to Vruum staff.
|
|
114
119
|
|
|
115
|
-
|
|
116
|
-
`get_revenue` account and service-margin views, and the reviewed finance-statement
|
|
117
|
-
action in `manage_revenue`. Hosted remote MCP already exposes these contracts;
|
|
118
|
-
stdio clients receive the updated advertised schema after package publication
|
|
119
|
-
and upgrade. Finance attestation, binding decisions and measurement approval
|
|
120
|
-
retain their separate server-side checks.
|
|
120
|
+
Full schemas, descriptions and MCP safety annotations live in [`tools.json`](tools.json) — generated from the live server definition, never hand-edited.
|
|
121
121
|
|
|
122
122
|
The current package also carries the retained-email decision instructions in
|
|
123
123
|
`manage_messages`. A saved email uses its displayed Action version, proposal
|
|
124
124
|
revision, and fingerprint. Approval is not a delivery receipt; changed content
|
|
125
|
-
requires new work.
|
|
126
|
-
|
|
125
|
+
requires new work. Public `manage_assistant` activation remains analysis-only.
|
|
126
|
+
|
|
127
|
+
Use `manage_assistant action=follow_up` to continue completed private analysis.
|
|
128
|
+
Retain the same request UUID, parent Action, displayed revision, and message on
|
|
129
|
+
an uncertain retry. The server creates one new Action and reconstructs permitted
|
|
130
|
+
history with fresh company context. Read earlier turns through the
|
|
131
|
+
`previous_action_id` returned by `fetch assistant_task`; each turn retains its
|
|
132
|
+
own complete content references. Opening or reading work never starts analysis.
|
|
127
133
|
|
|
128
134
|
## Configuration
|
|
129
135
|
|
|
@@ -146,7 +152,7 @@ your agent ──stdio/JSON-RPC──▶ @vruum/mcp
|
|
|
146
152
|
(authorized server-side)
|
|
147
153
|
```
|
|
148
154
|
|
|
149
|
-
Listings are a **static snapshot** bundled at release. That's what makes credential-free introspection possible, and it means a newly added tool won't *appear* until the next release — calls still execute correctly, since they proxy through.
|
|
155
|
+
Listings are a **static snapshot** bundled at release. That's what makes credential-free introspection possible, and it means a newly added tool won't *appear* until the next release — calls still execute correctly, since they proxy through. In the monorepo, a snapshot test fails any change that lets `tools.json` drift from the server definition, so a release never ships a stale listing.
|
|
150
156
|
|
|
151
157
|
## Safety and credentials
|
|
152
158
|
|
|
@@ -167,7 +173,7 @@ Listings are a **static snapshot** bundled at release. That's what makes credent
|
|
|
167
173
|
|
|
168
174
|
## Development
|
|
169
175
|
|
|
170
|
-
This repo is a **build artifact of the Vruum monorepo**, resynced automatically on release. `tools.json` is generated from the
|
|
176
|
+
This repo is a **build artifact of the Vruum monorepo**, resynced automatically on release. `tools.json` is generated from the server definition, and a snapshot test in the monorepo fails when the two differ. Between releases, the hosted server can be ahead of this snapshot.
|
|
171
177
|
|
|
172
178
|
```
|
|
173
179
|
src/index.ts the bridge — token resolution, static listings, proxied calls
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vruum/mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.0",
|
|
4
4
|
"mcpName": "ai.vruum/mcp",
|
|
5
5
|
"description": "Stdio MCP bridge for the hosted Vruum revenue-platform MCP (https://api.vruum.ai/mcp): serves the advertised tool surface for credential-free introspection and proxies tool calls with your Vruum token.",
|
|
6
6
|
"license": "MIT",
|
package/tools.json
CHANGED
|
@@ -1051,7 +1051,7 @@
|
|
|
1051
1051
|
"openWorldHint": true,
|
|
1052
1052
|
"readOnlyHint": false
|
|
1053
1053
|
},
|
|
1054
|
-
"description": "Manage Assistant\n\nStart
|
|
1054
|
+
"description": "Manage Assistant\n\nStart or continue private saved analysis, or cancel saved assistant work.\n\n- start_analysis: no id; payload={request_id (UUID), message}. Call only\n after the user requests this analysis. This call explicitly grants\n revenue_operator.read_analysis.v1: paid model work using permitted reads,\n without tool writes or external effects. Keep the exact request UUID and\n message on retries; the saved task journal owns request identity and\n recovery. An uncertain response never authorizes a replacement task.\n- cancel: id=the saved task's Action UUID; payload={expected_version} from\n a fresh fetch assistant_task. The original current actor or a current\n workspace owner/operator may cancel future continuation. An in-flight\n effect or provider call may still finish; cancellation cannot recall it.\n- follow_up: id=the completed analysis Action UUID; payload={request_id,\n expected_version, message}. Only its current original actor/login can\n continue the latest turn. This explicitly buys a new analysis Action in\n the same private conversation. Keep the exact UUID, parent, revision and\n message on retries, including an uncertain acknowledgement. The server\n reconstructs permitted history and refreshes company context. Historical\n answers are not current facts or approval for effects.\n\nAll actions are scalar: no id arrays or items. No caller history, imported\nthread, email activation, additional effects, actor transfer, or worker\ncontrol fields are accepted. This facade adds no authority to its target.\nThe task is private to its original current actor and login; owner/operator\noversight gives metadata and cancellation, never another member's content.\nExisting retained email work uses its exact linked review without changing\nthe sender. Inspect fetch assistant_task, page fetch assistant_task_events,\nand retrieve full content with fetch assistant_task_content. Read prior\nturns by following previous_action_id from fetch assistant_task until it is\nnull, then order by conversation_turn. Follow next_action_id to newer work. There is no steering of active work or shared conversation. Public chat\ncompletion limits remain active.\n\n### Responses:\n\n**200**: Successful Response (Success Response)\nContent-Type: application/json\n\nPrivate saved conversations support (assistant_saved_conversations):\nProduct support is not permission. Inspect current work and follow the domain's authorization and review rules.\n- follow_up: manage_assistant action=follow_up. Continue the latest completed private analysis at its current revision. Exact request UUID retries return the same child Action. Use existing fetch assistant_task links to read every permitted prior turn. Historical answers are not current facts or execution authority.\n- active_steering: unsupported. A running task cannot accept new messages. Complete it before following up.\n- sharing: unsupported. No shared participants, source publication, or actor transfer.\n\nSaved assistant tasks support (assistant_saved_tasks):\nProduct support is not permission. Inspect current work and follow the domain's authorization and review rules.\n- start: manage_assistant action=start_analysis. An explicit request grants paid read_analysis.v1 only. Exact request UUID retries recover the same task.\n- list: fetch type=assistant_tasks. Page own work or authorized workspace metadata with next_cursor.\n- inspect: fetch type=assistant_task. Read current state, Action version and exact review links.\n- events: fetch type=assistant_task_events. Page journal events by sequence; no raw worker state or hidden reasoning.\n- content: fetch type=assistant_task_content. Read complete immutable content pages under the original current actor and login.\n- cancel: manage_assistant action=cancel. Cancel at the current Action version; in-flight effects may still finish.\n- conversation_import: unsupported. No caller history, thread import, or appended task messages.\n- email_activation: unsupported. No public email-task start or added external effects.\n- executor_transfer: unsupported. No actor, sender, or harness/worker authority transfer.",
|
|
1055
1055
|
"inputSchema": {
|
|
1056
1056
|
"properties": {
|
|
1057
1057
|
"action": {
|
|
@@ -1345,7 +1345,7 @@
|
|
|
1345
1345
|
"openWorldHint": true,
|
|
1346
1346
|
"readOnlyHint": false
|
|
1347
1347
|
},
|
|
1348
|
-
"description": "Manage History Import\n\nImport past conversations, optionally discovering relevant CRM relationships.\n\nThe web equivalent is
|
|
1348
|
+
"description": "Manage History Import\n\nImport past conversations, optionally discovering relevant CRM relationships.\n\nThe web equivalent is People → Import → Past conversations. Workspace\nowners/operators only; pilot gates remain effective. Vruum also offers a\ndefault import in Actions when an owner connects an account.\nFirst fetch history_import_setup. Fetch history_import_preview with\ncontact_selection=recent (people who replied first, then the most recently\nactive, up to 1,000 identities; contacts_limited=true when more exist) or with selected person_ids\nfrom history_import_people, plus source/date limits. Optional\ndiscover_relationships=true permits empty person_ids. Explain bounded private\nsamples, model screening and quote verification, the $2 model allowance,\nresearch-candidate additions, evidence retention, and conditional undo.\n- propose: no id. Payload {scope, scope_digest, client_request_id}; copy the\n preview's scope unchanged. Retain the UUID request ID on exact retries.\n This saves one review Action and reads no provider data.\n- approve: id=run UUID. Show the saved scope and disclosures to the human\n before calling. Payload {scope_digest, expected_action_version} from a\n fresh fetch history_import. Approval authorizes metadata enumeration and\n matched bodies within saved limits. A discovery scope also authorizes its\n sampled model review and verified contact/account additions. Existing-only\n scopes run no models. Neither scope authorizes sending or qualification.\n- pause/resume: id=run UUID, no payload. Preserve the exact approved scope.\n Reconnect the source in Integrations before retrying a disconnected run.\n Changed accounts/identities require a new preview and approval.\n- stop: id=run UUID, no payload. End further work and retain captured history.\n- remove: id=run UUID, no payload. Confirm removal with the human. Deletes\n this import's history and discovery evidence; untouched new memberships are\n archived. Changed records and memberships used elsewhere survive.\n\nPoll fetch history_import; page history_import_batches for receipts.\nSource completeness stays unverified, including after complete_with_gaps.\nRead captured bodies through fetch relationship_history / relationship_history_detail,\nsubtype=people, id=person UUID. Never fabricate native message IDs.\n\n### Responses:\n\n**200**: Successful Response (Success Response)\nContent-Type: application/json",
|
|
1349
1349
|
"inputSchema": {
|
|
1350
1350
|
"properties": {
|
|
1351
1351
|
"action": {
|
|
@@ -2609,7 +2609,7 @@
|
|
|
2609
2609
|
"type": "null"
|
|
2610
2610
|
}
|
|
2611
2611
|
],
|
|
2612
|
-
"description": "Set to 'compact' for a lightweight projection WITHOUT message body — keeps message_id, person_name, category, sequence_number, channel, status, match_score, touches_completed, objective_id, first_content_touch, channel_rewrite_reason, expires_at, connection_status. first_content_touch=true = the person has never received a content-bearing message (connection requests don't count): treat the item as an OPENER regardless of sequence_number; null = row predates the conversation_state brief (fall back to the sequence_number heuristic). expires_at (needs_draft rows only) = when the nightly sweep auto-rejects the row if still unauthored (regenerate grants a fresh window) — author nearest-deadline-first (sort_by=expiring) to beat it. connection_status = the linked plan's LinkedIn connection state: a linkedin_message row with connection_status='connected' is a WARM follow-up (they accepted the invite) — dispatch these first. Cheap on tokens for triage. An unrecognized value 422s.",
|
|
2612
|
+
"description": "Set to 'compact' for a lightweight projection WITHOUT message body — keeps message_id, person_name, category, sequence_number, channel, status, match_score (the person's latest fit score) and match_scored_at (the day it was made; score_min/score_max match only scores whose research still holds), touches_completed, objective_id, first_content_touch, channel_rewrite_reason, expires_at, connection_status. first_content_touch=true = the person has never received a content-bearing message (connection requests don't count): treat the item as an OPENER regardless of sequence_number; null = row predates the conversation_state brief (fall back to the sequence_number heuristic). expires_at (needs_draft rows only) = when the nightly sweep auto-rejects the row if still unauthored (regenerate grants a fresh window) — author nearest-deadline-first (sort_by=expiring) to beat it. connection_status = the linked plan's LinkedIn connection state: a linkedin_message row with connection_status='connected' is a WARM follow-up (they accepted the invite) — dispatch these first. Cheap on tokens for triage. An unrecognized value 422s.",
|
|
2613
2613
|
"title": "Fields"
|
|
2614
2614
|
},
|
|
2615
2615
|
"has_reply": {
|