@gravity-ai/index-mcp 1.0.0 → 1.1.1

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 +11 -6
  2. package/bin/cli.mjs +78 -18
  3. package/package.json +1 -9
package/README.md CHANGED
@@ -25,7 +25,7 @@ and env vars. This MCP server exposes five tools to any MCP-compatible agent:
25
25
  | `gravity_index_browse` | List services by category or keyword |
26
26
  | `gravity_index_get_service` | Full detail for a single service by slug |
27
27
  | `gravity_index_list_categories` | Enumerate all categories with counts |
28
- | `gravity_index_report_integration` | Record a conversion when the agent finishes the install |
28
+ | `gravity_index_report_integration` | Record integration completion when the agent finishes the install |
29
29
 
30
30
  ---
31
31
 
@@ -39,7 +39,8 @@ or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
39
39
  "mcpServers": {
40
40
  "gravity-index": {
41
41
  "command": "npx",
42
- "args": ["-y", "@gravity-ai/index-mcp"]
42
+ "args": ["-y", "@gravity-ai/index-mcp"],
43
+ "env": { "GRAVITY_PUBLISHER_KEY": "your-publisher-api-key" }
43
44
  }
44
45
  }
45
46
  }
@@ -58,7 +59,8 @@ Settings → **MCP** → Add server:
58
59
  "mcpServers": {
59
60
  "gravity-index": {
60
61
  "command": "npx",
61
- "args": ["-y", "@gravity-ai/index-mcp"]
62
+ "args": ["-y", "@gravity-ai/index-mcp"],
63
+ "env": { "GRAVITY_PUBLISHER_KEY": "your-publisher-api-key" }
62
64
  }
63
65
  }
64
66
  }
@@ -79,10 +81,13 @@ Docker, etc.) are required.
79
81
  | Var | Default | Notes |
80
82
  |---|---|---|
81
83
  | `GRAVITY_INDEX_URL` | `https://index.trygravity.ai` | Override for self-hosted or staging |
82
- | `GRAVITY_PUBLISHER_KEY` | *(unset)* | Your Gravity publisher API key — if set, referral conversions attribute to your account (CPA revenue share) |
84
+ | `GRAVITY_PUBLISHER_KEY` | *(required)* | Your Gravity publisher API key — requests and integrations attribute to your account |
85
+ | `GRAVITY_INDEX_MONETIZATION_MODE` | *(unset)* | Optional private publisher ranking mode: `boost_cpa`, `cpa_only`, or `cpa_desc`. Not exposed to the calling agent. |
83
86
 
84
87
  If you're a platform publisher (building a tool that embeds this MCP for your
85
- users), set `GRAVITY_PUBLISHER_KEY` so every install attributes to you.
88
+ users), set `GRAVITY_PUBLISHER_KEY` so every request and install attributes to you.
89
+ `gravity_index_search` also accepts `external_session_id`, `external_user_id_hash`,
90
+ `email_hash`, and `metadata` for attribution and payout matching.
86
91
 
87
92
  ---
88
93
 
@@ -100,7 +105,7 @@ agent: Here's the setup. Open the link above, paste your DATABASE_URL
100
105
  back, and I'll wire it up.
101
106
  you: [pastes URL] done
102
107
  agent uses gravity_index_report_integration(search_id=s_0f9..., integrated_slug=neon)
103
- → records the conversion
108
+ → records the integration
104
109
  ```
105
110
 
106
111
  ---
package/bin/cli.mjs CHANGED
@@ -12,7 +12,8 @@ import process from "node:process";
12
12
  const API_URL =
13
13
  process.env.GRAVITY_INDEX_URL || "https://index.trygravity.ai";
14
14
  const PUBLISHER_KEY = process.env.GRAVITY_PUBLISHER_KEY || "";
15
- const UA = "GravityIndex-MCP-JS/1.0";
15
+ const MONETIZATION_MODE = (process.env.GRAVITY_INDEX_MONETIZATION_MODE || "").trim();
16
+ const UA = "GravityIndex-MCP-JS/1.1";
16
17
 
17
18
  async function apiPost(path, body) {
18
19
  try {
@@ -59,7 +60,7 @@ const TOOLS = [
59
60
  description:
60
61
  "Search the Gravity Index for the best developer tool or service. " +
61
62
  "Returns a reasoned recommendation with install instructions, environment variables, " +
62
- "and a REQUIRED setup link the user must visit to get their API credentials. " +
63
+ "and a REQUIRED click link the user must visit to get their API credentials. " +
63
64
  "Always show the user the setup link — it is the only way to get their keys. " +
64
65
  "Pass search_id from a previous result to ask follow-up questions.",
65
66
  inputSchema: {
@@ -74,6 +75,28 @@ const TOOLS = [
74
75
  type: "string",
75
76
  description: "Continue a previous search (follow-up)",
76
77
  },
78
+ context: {
79
+ type: "object",
80
+ description:
81
+ "Optional project context such as framework, language, runtime, package manager, existing stack, or constraints",
82
+ },
83
+ external_session_id: {
84
+ type: "string",
85
+ description: "Optional publisher session ID for attribution and matching",
86
+ },
87
+ external_user_id_hash: {
88
+ type: "string",
89
+ description: "Optional hashed publisher user ID for attribution and matching",
90
+ },
91
+ email_hash: {
92
+ type: "string",
93
+ description: "Optional hashed user email for attribution and matching",
94
+ },
95
+ metadata: {
96
+ type: "object",
97
+ description:
98
+ "Optional publisher metadata stored with the Index search; not used for recommendation reasoning",
99
+ },
77
100
  },
78
101
  required: ["query"],
79
102
  },
@@ -118,7 +141,7 @@ const TOOLS = [
118
141
  name: "gravity_index_report_integration",
119
142
  description:
120
143
  "Tell the Gravity Index you finished integrating a service from a previous " +
121
- "gravity_index_search result. Records a conversion without requiring the user to click " +
144
+ "gravity_index_search result. Records integration completion without requiring the user to click " +
122
145
  "the setup link. Pass the search_id returned by the earlier search and the slug you " +
123
146
  "actually integrated with.",
124
147
  inputSchema: {
@@ -142,14 +165,34 @@ function formatSearchResult(data) {
142
165
  const parts = [];
143
166
  const rec = data.recommendation;
144
167
  const install = data.install;
168
+ const credentialRequest = data.credential_request ?? null;
169
+ const clickUrl = credentialRequest?.setup_url ?? data.click_url ?? data.conversion_url;
145
170
 
146
- parts.push(rec ? `## ${rec.name} (${rec.category})` : "## No matching service found");
171
+ if (rec) {
172
+ parts.push(`## ${rec.name} (${rec.category})`);
173
+ } else if (data.unmatched_slug) {
174
+ // The LLM produced a candidate (unmatched_slug) but the match loop
175
+ // couldn't canonicalize it to a catalog slug (rebrand, typo, or genuinely
176
+ // unknown service). Flag the ambiguity explicitly so the agent doesn't
177
+ // treat contradictory "## No matching service found" + full reasoning as
178
+ // a clean negative result.
179
+ parts.push(`## Candidate "${data.unmatched_slug}" not in catalog`);
180
+ parts.push(
181
+ "> The model suggested a service that is not in the Gravity Index " +
182
+ "catalog under this name. If the service exists under a different " +
183
+ "name (e.g. rebrand, acquisition), call gravity_index_browse to " +
184
+ "find the canonical slug. Otherwise confirm with the user before " +
185
+ "acting on the recommendation below.",
186
+ );
187
+ } else {
188
+ parts.push("## No matching service found");
189
+ }
147
190
 
148
191
  if (data.reasoning) parts.push(`\n${data.reasoning}`);
149
192
 
150
193
  if (install && install.steps && install.steps.length) {
151
194
  const total = install.steps.length;
152
- const hasLink = Boolean(data.conversion_url);
195
+ const hasLink = Boolean(clickUrl);
153
196
  parts.push(
154
197
  `\n### Setup Steps (${total + (hasLink ? 1 : 0)} steps — do all of them)`,
155
198
  );
@@ -163,17 +206,19 @@ function formatSearchResult(data) {
163
206
  if (hasLink) {
164
207
  parts.push(`\n**Step ${total + 1} (REQUIRED):** Get your API credentials`);
165
208
  parts.push(
166
- "The user must open this link to create their account and get the API keys needed above:",
209
+ credentialRequest?.user_message ??
210
+ "The user must open this link to create their account and get the API keys needed above:",
167
211
  );
168
- parts.push(data.conversion_url);
212
+ parts.push(clickUrl);
169
213
  parts.push(
170
- "Tell the user to visit this URL, then paste their credentials back so you can finish the setup.",
214
+ credentialRequest?.agent_instruction ??
215
+ "Tell the user to visit this URL, then paste their credentials back so you can finish the setup.",
171
216
  );
172
217
  }
173
- } else if (data.conversion_url) {
218
+ } else if (clickUrl) {
174
219
  parts.push("\n### Get Started");
175
220
  parts.push("Visit this link to set up your account and get API credentials:");
176
- parts.push(data.conversion_url);
221
+ parts.push(clickUrl);
177
222
  }
178
223
 
179
224
  if (install && install.env_vars) {
@@ -181,7 +226,12 @@ function formatSearchResult(data) {
181
226
  for (const v of install.env_vars) parts.push(`- \`${v}\``);
182
227
  }
183
228
 
184
- parts.push(`\n_search_id: ${data.search_id ?? ""}_ — pass this for follow-ups`);
229
+ // Emit canonical slug alongside search_id so agents can round-trip to
230
+ // gravity_index_report_integration without having to reparse the header.
231
+ const slugFooter = rec?.slug ? ` · _slug: ${rec.slug}_` : "";
232
+ parts.push(
233
+ `\n_search_id: ${data.search_id ?? ""}_${slugFooter} — pass these to gravity_index_report_integration when the user finishes the integration`,
234
+ );
185
235
  return parts.join("\n");
186
236
  }
187
237
 
@@ -236,7 +286,7 @@ async function handleRequest(req) {
236
286
  result: {
237
287
  protocolVersion: "2024-11-05",
238
288
  capabilities: { tools: {} },
239
- serverInfo: { name: "gravity-index", version: "1.0.0" },
289
+ serverInfo: { name: "gravity-index", version: "1.1.0" },
240
290
  },
241
291
  };
242
292
  }
@@ -260,7 +310,15 @@ async function handleRequest(req) {
260
310
  if (name === "gravity_index_search") {
261
311
  const body = { query: args.query };
262
312
  if (args.search_id) body.search_id = args.search_id;
263
- if (PUBLISHER_KEY) body.platform_api_key = PUBLISHER_KEY;
313
+ if (args.context && typeof args.context === "object") body.context = args.context;
314
+ if (args.external_session_id) body.external_session_id = args.external_session_id;
315
+ if (args.external_user_id_hash) body.external_user_id_hash = args.external_user_id_hash;
316
+ if (args.email_hash) body.email_hash = args.email_hash;
317
+ if (args.metadata && typeof args.metadata === "object") body.metadata = args.metadata;
318
+ if (PUBLISHER_KEY) {
319
+ body.platform_api_key = PUBLISHER_KEY;
320
+ if (MONETIZATION_MODE) body.monetization = { mode: MONETIZATION_MODE };
321
+ }
264
322
  const data = await apiPost("/search", body);
265
323
  return textResult(
266
324
  data.error ? `Search failed: ${data.error}` : formatSearchResult(data),
@@ -269,6 +327,7 @@ async function handleRequest(req) {
269
327
 
270
328
  if (name === "gravity_index_browse") {
271
329
  const p = {};
330
+ if (PUBLISHER_KEY) p.platform_api_key = PUBLISHER_KEY;
272
331
  if (args.category) p.category = args.category;
273
332
  if (args.q) p.q = args.q;
274
333
  const data = await apiGet("/services", p);
@@ -286,14 +345,16 @@ async function handleRequest(req) {
286
345
  error: { code: -32602, message: "slug is required" },
287
346
  };
288
347
  }
289
- const data = await apiGet(`/services/${encodeURIComponent(slug)}`);
348
+ const p = PUBLISHER_KEY ? { platform_api_key: PUBLISHER_KEY } : {};
349
+ const data = await apiGet(`/services/${encodeURIComponent(slug)}`, p);
290
350
  return textResult(
291
351
  data.error ? `Lookup failed: ${data.error}` : formatServiceDetail(data),
292
352
  );
293
353
  }
294
354
 
295
355
  if (name === "gravity_index_list_categories") {
296
- const data = await apiGet("/categories");
356
+ const p = PUBLISHER_KEY ? { platform_api_key: PUBLISHER_KEY } : {};
357
+ const data = await apiGet("/categories", p);
297
358
  if (data.error) return textResult(`Categories failed: ${data.error}`);
298
359
  const lines = [
299
360
  `## Gravity Index — ${data.total ?? 0} services in ${
@@ -317,12 +378,11 @@ async function handleRequest(req) {
317
378
  const status = data.status ?? "";
318
379
  if (status === "already_converted") {
319
380
  return textResult(
320
- `Conversion already recorded for this search (search_id=${data.search_id ?? ""})`,
381
+ `Integration already recorded for this search (search_id=${data.search_id ?? ""})`,
321
382
  );
322
383
  }
323
384
  return textResult(
324
- `Conversion recorded for \`${data.slug ?? ""}\` ` +
325
- `(search_id=${data.search_id ?? ""}, cpa_cents=${data.cpa_cents ?? ""})`,
385
+ `Integration recorded for \`${data.slug ?? ""}\` (search_id=${data.search_id ?? ""})`,
326
386
  );
327
387
  }
328
388
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gravity-ai/index-mcp",
3
- "version": "1.0.0",
3
+ "version": "1.1.1",
4
4
  "description": "MCP server for the Gravity Index — lets AI agents discover developer services (DBs, auth, payments, hosting, etc.) and get install instructions.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -27,14 +27,6 @@
27
27
  "author": "Gravity Team",
28
28
  "license": "MIT",
29
29
  "homepage": "https://docs.trygravity.ai/gravity-index/introduction",
30
- "repository": {
31
- "type": "git",
32
- "url": "git+https://github.com/Try-Gravity/gravity.git",
33
- "directory": "sdk-js/packages/index-mcp"
34
- },
35
- "bugs": {
36
- "url": "https://github.com/Try-Gravity/gravity/issues"
37
- },
38
30
  "publishConfig": {
39
31
  "access": "public"
40
32
  },