@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.
- package/README.md +11 -6
- package/bin/cli.mjs +78 -18
- 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
|
|
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` | *(
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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(
|
|
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
|
-
|
|
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(
|
|
212
|
+
parts.push(clickUrl);
|
|
169
213
|
parts.push(
|
|
170
|
-
|
|
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 (
|
|
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(
|
|
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
|
-
|
|
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.
|
|
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 (
|
|
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
|
|
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
|
|
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
|
-
`
|
|
381
|
+
`Integration already recorded for this search (search_id=${data.search_id ?? ""})`,
|
|
321
382
|
);
|
|
322
383
|
}
|
|
323
384
|
return textResult(
|
|
324
|
-
`
|
|
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.
|
|
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
|
},
|