gorz-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 GORZ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# GORZ MCP server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Solana memecoin safety checks for AI assistants and trading agents.
+
+Ask your assistant "is this coin safe?" and it checks the coin with [GORZ](https://gorz.app). You get the grade, every red flag with its reason, launch bundles, wallets selling in the same second, and links to known rug farms.
+
+GORZ reports what public on-chain data shows. It does not predict prices, and nothing it returns is financial advice.
+
+## Tools
+
+| Tool | What it does | Key needed |
+|---|---|---|
+| `gorz_check_coin` | Full safety read for a coin by its mint address. Includes the grade (safer / caution / risky / checking), hard stops, red flags, launch bundle, same-second sellers, rug-farm link, AI dump warning, and what happened in the hour after GORZ first graded it. | No |
+| `gorz_search_coins` | Find coins by ticker or name (`$BONK`, `fuzzy bear`). Returns their addresses and first GORZ grade. | No |
+| `gorz_check_wallet` | What GORZ has seen a wallet do: rug-farm group, launch bundles, snipes, and its record as a coin creator. | Yes |
+
+## Install
+
+Requires Node.js 18 or newer.
+
+### Claude Desktop, Cursor and other MCP clients
+
+Add this to your MCP config (for Claude Desktop that's `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "gorz": {
+      "command": "npx",
+      "args": ["-y", "gorz-mcp"],
+      "env": { "GORZ_API_KEY": "" }
+    }
+  }
+}
+```
+
+Leave `GORZ_API_KEY` empty to use the free tier.
+
+### Claude Code
+
+```
+claude mcp add gorz -- npx -y gorz-mcp
+```
+
+## Limits and keys
+
+| Plan | Checks per day | Price |
+|---|---|---|
+| Free | 300, no key | $0 |
+| Starter | 20,000, plus wallet lookups | $49 / 30 days |
+| Pro | 200,000 | $199 / 30 days |
+
+Get a key at [gorz.app/developers](https://gorz.app/developers), paid in SOL or USDC. GORZ is also on RapidAPI, where you can pay by card.
+
+## Settings
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `GORZ_API_KEY` | (empty) | Your GORZ key, for higher limits and wallet lookups |
+| `GORZ_API_URL` | `https://gorz.app/api/v1` | Only change this for testing |
+
+## Example
+
+> **You:** Is 2DtF5QVs1zPwpZVR7PGiCcnNsi36gJvMWxNbeDVCpump safe to buy?
+>
+> **Assistant** (after calling `gorz_check_coin`): GORZ first graded $YMB as risky at a $585K market cap, and it dumped within the hour…
+
+## License
+
+MIT

package/index.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// GORZ MCP server: lets AI assistants and trading agents check Solana memecoins with GORZ (https://gorz.app).
+// Tools: gorz_check_coin, gorz_search_coins, gorz_check_wallet. Talks to the public GORZ API v1 over HTTPS.
+// Optional env: GORZ_API_KEY (higher limits + wallet lookups; get one at https://gorz.app/developers),
+//               GORZ_API_URL (default https://gorz.app/api/v1).
+import {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js';
+import {StdioServerTransport} from '@modelcontextprotocol/sdk/server/stdio.js';
+import {z} from 'zod';
+
+const VERSION = '0.1.0';
+const BASE = (process.env.GORZ_API_URL || 'https://gorz.app/api/v1').replace(/\/+$/, '');
+const KEY = (process.env.GORZ_API_KEY || '').trim();
+const ADDRESS = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+
+async function call(path, params) {
+  const url = BASE + path + '?' + new URLSearchParams(params).toString();
+  const headers = {'user-agent': 'gorz-mcp/' + VERSION, accept: 'application/json'};
+  if (KEY) headers['x-api-key'] = KEY;
+  let r;
+  try { r = await fetch(url, {headers, signal: AbortSignal.timeout(15000)}); }
+  catch (e) { return {ok: false, status: 0, body: {error: 'Could not reach GORZ (' + (e?.name === 'TimeoutError' ? 'timed out' : e?.message || 'network error') + '). Try again shortly.'}}; }
+  const body = await r.json().catch(() => ({error: 'GORZ sent an unreadable reply (HTTP ' + r.status + ').'}));
+  return {ok: r.ok, status: r.status, body, left: r.headers.get('x-ratelimit-remaining'), plan: r.headers.get('x-gorz-plan')};
+}
+
+const text = (s) => ({content: [{type: 'text', text: s}]});
+const fail = (s) => ({content: [{type: 'text', text: s}], isError: true});
+const usd = (n) => n == null || !Number.isFinite(Number(n)) ? 'n/a' : '$' + Number(n).toLocaleString('en-US', {maximumFractionDigits: Number(n) < 1 ? 8 : 0});
+const pct = (n) => n == null || !Number.isFinite(Number(n)) ? 'n/a' : Number(n).toFixed(1) + '%';
+function limitNote(res) {
+  if (res.status === 429) return '\n\nDaily limit reached. ' + (KEY ? 'Your plan limit resets at 00:00 UTC.' : 'The free tier is 300 checks a day. A key raises it: https://gorz.app/developers');
+  if (res.status === 402) return '\n\nThis GORZ key has expired. Renew it at https://gorz.app/developers';
+  if (res.status === 401) return '\n\n' + (KEY ? 'The GORZ_API_KEY was not accepted.' : 'This needs a GORZ API key (set GORZ_API_KEY). Get one at https://gorz.app/developers');
+  return '';
+}
+
+function coinReport(b) {
+  const lines = [];
+  lines.push(`${b.symbol ? '$' + b.symbol : 'Unknown coin'}${b.name ? ' (' + b.name + ')' : ''}`);
+  lines.push(`Address: ${b.mint}`);
+  if (b.live) {
+    lines.push(`GORZ grade right now: ${String(b.grade || 'n/a').toUpperCase()}${b.score != null ? ` (score ${b.score}/100)` : ''}${b.limitedData ? ' (limited data so far)' : ''}`);
+    if (b.hardStops?.length) lines.push(`Hard stops (GORZ Safe Mode would hide this coin): ${b.hardStops.join('; ')}`);
+    if (b.aiWarning) lines.push('GORZ AI warning: the trading pattern matches coins that went on to dump.');
+    if (b.flags?.length) { lines.push('Red flags:'); for (const f of b.flags) lines.push(`  - [${f.status}] ${f.label}: ${f.detail}`); }
+    else lines.push('Red flags: none right now.');
+    const m = b.market, w = b.wallets;
+    if (m) lines.push(`Market: price ${usd(m.priceUsd)}, market cap ${usd(m.marketCapUsd)}, liquidity ${usd(m.liquidityUsd)}, 5 min change ${pct(m.change5mPct)}, buyers in last 5 min ${m.buyers5m ?? 'n/a'}${m.graduated ? ', graduated' : ''}`);
+    if (w) {
+      lines.push(`Holders: top 10 hold ${pct(w.top10Pct)}, snipers ${w.snipers ?? 'n/a'}, bundled ${pct(w.bundledPct)}${w.devExited ? ', creator has sold out' : ''}`);
+      const lb = w.launchBundle || {};
+      if (lb.wallets) lines.push(`Launch bundle: ${lb.wallets} wallets took ${pct(lb.supplyPct)} at launch and have sold ${pct(lb.soldPct)}${lb.repeatBundlers ? ` (${lb.repeatBundlers} seen bundling before)` : ''}`);
+      if (w.soldTogetherMax || w.boughtTogetherMax) lines.push(`Same-second trading (most seen): ${w.soldTogetherMax ?? 0} wallets sold together, ${w.boughtTogetherMax ?? 0} bought together`);
+    }
+  } else lines.push('Not trading on the GORZ radar right now (GORZ has seen it before).');
+  if (b.farm) lines.push(`Rug-farm link: wallet group ${b.farm.code} has launched ${b.farm.coins} coins, ${b.farm.diedWithinHour} died within an hour. Case file: ${b.farm.caseFile}`);
+  if (b.firstGrade) lines.push(`First GORZ grade: ${b.firstGrade.grade} at ${usd(b.firstGrade.marketCapUsd)} market cap; 1 hour later: ${b.firstGrade.after1h || 'still being checked'}.`);
+  lines.push(`Full page: ${b.page}`);
+  lines.push(`\n${b.disclaimer || 'Not financial advice.'}`);
+  return lines.join('\n');
+}
+
+const server = new McpServer({name: 'gorz', version: VERSION});
+
+server.registerTool('gorz_check_coin', {
+  title: 'Check a Solana coin with GORZ',
+  description: 'Safety read for a Solana memecoin by its contract (mint) address: GORZ grade (safer / caution / risky / checking), every red flag with its reason, hard stops, launch bundles, wallets buying or selling in the same second, rug-farm links, an AI dump warning, and what happened in the hour after GORZ first graded it. Use before buying or recommending a coin. Facts from public on-chain data, not price predictions.',
+  inputSchema: {mint: z.string().describe('Solana token mint (contract) address, e.g. 2DtF5QVs1zPwpZVR7PGiCcnNsi36gJvMWxNbeDVCpump')},
+  annotations: {readOnlyHint: true, openWorldHint: true},
+}, async ({mint}) => {
+  mint = String(mint || '').trim();
+  if (!ADDRESS.test(mint)) return fail('That is not a Solana address. If you only have a ticker or name, use gorz_search_coins first.');
+  const res = await call('/check', {mint});
+  if (res.status === 404 && res.body?.found === false) return text(`GORZ has not seen ${mint}. It may be too old, not on Solana, or not traded recently.`);
+  if (!res.ok) return fail((res.body?.error || `GORZ returned HTTP ${res.status}.`) + limitNote(res));
+  return text(coinReport(res.body) + (res.left != null ? `\n(GORZ calls left today: ${res.left})` : ''));
+});
+
+server.registerTool('gorz_search_coins', {
+  title: 'Find a Solana coin on GORZ by ticker or name',
+  description: 'Look up coins GORZ has graded by ticker, name or address (e.g. "$BONK", "fuzzy bear"). Returns up to 8 matches with their contract address, first GORZ grade and what happened an hour later. Use this to get the address, then gorz_check_coin for the full safety read. Tickers are not unique: many coins copy the same name.',
+  inputSchema: {query: z.string().describe('Ticker, name or address to look for')},
+  annotations: {readOnlyHint: true, openWorldHint: true},
+}, async ({query}) => {
+  const q = String(query || '').trim();
+  if (q.replace(/[\s$]/g, '').length < 2) return fail('Give at least 2 characters to search for.');
+  const res = await call('/search', {q});
+  if (!res.ok) return fail((res.body?.error || `GORZ returned HTTP ${res.status}.`) + limitNote(res));
+  const rows = res.body?.results || [];
+  if (!rows.length) return text(`No coin matching "${q}" has been graded by GORZ.`);
+  return text(`${rows.length} match${rows.length > 1 ? 'es' : ''} for "${q}" (copycat names are common, check the address):\n` + rows.map((r, i) =>
+    `${i + 1}. $${r.symbol || '?'} (${r.name || 'no name'})\n   address: ${r.mint}\n   first GORZ grade: ${r.grade || 'n/a'} at ${usd(r.marketCapUsd)}; 1 hour later: ${r.after1h || 'unknown'}`).join('\n'));
+});
+
+server.registerTool('gorz_check_wallet', {
+  title: 'Check a Solana wallet with GORZ',
+  description: 'What GORZ has seen a Solana wallet do: membership in a rug-farm wallet group, launch bundles it took part in, how often it sniped, bundled or bought early, and its record as a coin creator. Needs a GORZ API key (GORZ_API_KEY).',
+  inputSchema: {address: z.string().describe('Solana wallet address')},
+  annotations: {readOnlyHint: true, openWorldHint: true},
+}, async ({address}) => {
+  address = String(address || '').trim();
+  if (!ADDRESS.test(address)) return fail('That is not a Solana wallet address.');
+  if (!KEY) return fail('Wallet lookups need a GORZ API key. Set GORZ_API_KEY in this server\'s settings. Keys: https://gorz.app/developers');
+  const res = await call('/wallet', {address});
+  if (!res.ok) return fail((res.body?.error || `GORZ returned HTTP ${res.status}.`) + limitNote(res));
+  const b = res.body, s = b.seenAs || {}, out = [`Wallet ${b.wallet}`];
+  out.push(b.farmGroup ? `Rug-farm group ${b.farmGroup.code}: ${b.farmGroup.coins} coins launched, ${b.farmGroup.diedWithinHour} died within an hour.` : 'Not linked to a known rug-farm group.');
+  out.push(b.launchBundles ? `Took part in ${b.launchBundles.launches} launch bundles (last ${new Date(b.launchBundles.lastAt).toISOString().slice(0, 10)}).` : 'No launch bundles seen.');
+  out.push(`Seen as: sniper ${s.sniper ?? 0}x, bundler ${s.bundler ?? 0}x, early buyer ${s.earlyBuyer ?? 0}x.`);
+  if (b.creator?.summary) out.push('As a coin creator: ' + (typeof b.creator.summary === 'string' ? b.creator.summary : JSON.stringify(b.creator.summary)));
+  out.push(`\n${b.disclaimer || 'Not financial advice.'}`);
+  return text(out.join('\n'));
+});
+
+await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "gorz-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "GORZ MCP server: Solana memecoin safety checks for AI assistants and trading agents (grade, red flags, launch bundles, same-second sellers, rug-farm links).",
+  "type": "module",
+  "bin": {"gorz-mcp": "index.mjs"},
+  "main": "index.mjs",
+  "files": ["index.mjs", "README.md", "LICENSE"],
+  "engines": {"node": ">=18"},
+  "keywords": ["mcp", "model-context-protocol", "solana", "memecoin", "rug-check", "crypto", "safety", "ai-agent", "gorz"],
+  "homepage": "https://gorz.app/developers",
+  "license": "MIT",
+  "mcpName": "io.github.GORZ-APP/gorz",
+  "repository": {"type": "git", "url": "https://github.com/GORZ-APP/gorz-mcp"},
+  "dependencies": {"@modelcontextprotocol/sdk": "1.32.2", "zod": "4.6.7"}
+}