@keelage/mcp 0.1.1 → 0.2.0

package/README.md

@@ -24,6 +24,7 @@ Or from a checkout: `node core/bin/keelage.mjs` starts the stdio server.
 |---|---|
 | `keelage_scan` | The structural verdict for one token: verified source, launcher template, owner privileges, transfer-tax code, honeypot flags, sells clearing, holder concentration tier, ATH drawdown and 30-day-low band, entry test, size rule. Four states: `ELIGIBLE`, `NOT_ELIGIBLE`, `FAIL`, `UNVERIFIED`. |
 | `keelage_holders` | Top wallets with pools, contracts and burn addresses labeled; top-10 share excluding pools and contracts; burn share; share held by EIP-7702 smart accounts. |
+| `keelage_x` | What X is saying about the token in the last 24 hours: posts and accounts, repeated-template share, large profiles and the chain they meant, views, a one-line read of the narrative. Its own call: a scan never reads X. Offered only where the server has a posts source. |
 | `keelage_template` | Which launcher template the contract came from, with the template verdict, the ABI privileges and the transfer-tax identifier count. |
 | `keelage_record` | The dated studies, with sample sizes, behind every rule. |
 
@@ -63,7 +64,7 @@ A stricter preset ships only when every line it moves has a documented source: a
 
 ## Hosted
 
-The same server runs at `https://mcp.keelage.ai/mcp` over Streamable HTTP (POST JSON-RPC; GET answers 405). No key and no sign-in. Per caller, 20 counted calls a day across `keelage_scan` and `keelage_holders`; `keelage_record` and `keelage_template` are never counted. The caller is the `X-Wallet` header when you send one (a 0x address), otherwise a salted hash of the network address that changes daily. Past the quota a priced tool answers with its price in USDG on Robinhood Chain and `x402.status: "not open yet"`; settlement opens when the merchant address is published. The hosted code is this package plus one transport file, so the two give the same answers.
+The same server runs at `https://mcp.keelage.ai/mcp` over Streamable HTTP (POST JSON-RPC; GET answers 405). No key and no sign-in. Per caller, 20 counted calls a day across `keelage_scan`, `keelage_holders` and `keelage_x`; `keelage_record` and `keelage_template` are never counted. The caller is the `X-Wallet` header when you send one (a 0x address), otherwise a salted hash of the network address that changes daily. Past the quota a priced tool draws on the caller's prepaid credit, or answers with its price in USDG on Robinhood Chain and the payment terms: send USDG to the merchant address on [keelage.ai/#ledger](https://keelage.ai/#ledger), register the transaction once with the hosted-only tool `keelage_pay`, and the wallet that sent it is credited; later calls that carry `X-Wallet` draw on it. The server holds no wallet key; it reads receipts from the chain. The hosted code is this package plus one transport file, so the two give the same answers.
 
 ## Command line
 

package/bin/keelage.mjs

@@ -5,6 +5,7 @@
 //   keelage serve                same
 //   keelage scan <0x>  [--text] [--ruleset <name|json>]  verdict as JSON (or the text card)
 //   keelage holders <0x> [--no-smart]
+//   keelage x <0x> [--fresh]      what X is saying in the last 24h (needs SOCIALDATA_API_KEY)
 //   keelage template <0x>
 //   keelage record [study-key]
 //   keelage tools                the MCP tool list
@@ -12,6 +13,7 @@ import { scanOne, renderScanText } from '../lib/gate.mjs';
 import { renderScanJson } from '../lib/render.mjs';
 import { holdersFor } from '../lib/holders.mjs';
 import { templateFor } from '../lib/template.mjs';
+import { xFor } from '../lib/x.mjs';
 import { trackRecord } from '../lib/record.mjs';
 import { serve, TOOLS } from '../server/mcp.mjs';
 
@@ -44,11 +46,14 @@ else if (cmd === 'scan') {
 } else if (cmd === 'holders') {
   if (!arg) { log('usage: keelage holders <0x address> [--no-smart]'); process.exit(2); }
   out(await holdersFor(arg, { withSmartAccounts: !flags.has('--no-smart') }));
+} else if (cmd === 'x') {
+  if (!arg) { log('usage: keelage x <0x address> [--fresh]'); process.exit(2); }
+  out(await xFor(arg, { log, force: flags.has('--fresh') }));
 } else if (cmd === 'template') {
   if (!arg) { log('usage: keelage template <0x address>'); process.exit(2); }
   out(await templateFor(arg));
 } else if (cmd === 'record') { out(trackRecord({ study: arg || null })); }
 else if (cmd === 'tools') { out(TOOLS); }
 else if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
-  process.stdout.write('keelage [serve] | scan <0x> [--text] [--ruleset <name|json>] | holders <0x> [--no-smart] | template <0x> | record [study] | tools\n');
+  process.stdout.write('keelage [serve] | scan <0x> [--text] [--ruleset <name|json>] | holders <0x> [--no-smart] | x <0x> [--fresh] | template <0x> | record [study] | tools\n');
 } else { log(`unknown command ${cmd}`); process.exit(2); }

package/lib/pay.mjs

@@ -0,0 +1,75 @@
+// pay.mjs - how a paid call is paid: the terms a priced tool quotes, and the receipt check that turns a USDG
+// transfer on Robinhood Chain into prepaid credit. Pure: no network here. The hosted transport fetches the
+// receipt and the ledger; this module only reads them.
+//
+// The scheme is a receipt, not a signature: the caller sends USDG to the merchant address from their own wallet,
+// then registers the transaction hash once (keelage_pay). The sending wallet is credited and spends by sending
+// the X-Wallet header on later calls. No key sits on any server; the server only reads the chain.
+export const PAY = Object.freeze({
+  chainId: 4663,
+  network: 'eip155:4663',
+  rpc: 'https://rpc.mainnet.chain.robinhood.com',
+  asset: '0x5fc5360d0400a0fd4f2af552add042d716f1d168', // USDG, 6 decimals, EIP-1967 proxy
+  assetSymbol: 'USDG',
+  decimals: 6,
+  payTo: '0xaE313a57B2CE1cbd31bB82C90ced3CFaC0862bA1', // Keelage merchant, receive-only, published on keelage.ai/#ledger
+  treasury: '0x000936C5EE6A180C26F3Edf0aF16c6bF0DFB7171',
+  transferTopic: '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
+  minDepositUsdg: '0.10', // below this a deposit is still credited, but the tx fee alone outweighs it
+});
+
+const ONE = 10n ** BigInt(PAY.decimals);
+
+// Units (bigint, 6 decimals) to a plain decimal string: 1234567n -> "1.234567", 50000n -> "0.05".
+export function unitsToUsdg(units) {
+  const u = BigInt(units); const neg = u < 0n; const a = neg ? -u : u;
+  const whole = a / ONE, frac = (a % ONE).toString().padStart(PAY.decimals, '0').replace(/0+$/, '');
+  return (neg ? '-' : '') + whole.toString() + (frac ? '.' + frac : '');
+}
+
+// A decimal string ("0.05") to units. Throws on anything that is not a plain non-negative decimal.
+export function usdgToUnits(s) {
+  const m = /^(\d+)(?:\.(\d{1,6}))?$/.exec(String(s).trim());
+  if (!m) throw new Error(`not a USDG amount: ${s}`);
+  return BigInt(m[1]) * ONE + BigInt((m[2] || '').padEnd(PAY.decimals, '0'));
+}
+
+const addrOfTopic = (t) => '0x' + String(t || '').slice(-40).toLowerCase();
+
+// Read a transaction receipt (eth_getTransactionReceipt result) for USDG transfers to the merchant address.
+// Returns { ok, txHash, block, from, units, amount } summing every qualifying Transfer log, or { ok:false, err }.
+// A receipt with status 0x0, no qualifying log, or several senders is refused; nothing is credited from it.
+export function depositFromReceipt(receipt, { payTo = PAY.payTo, asset = PAY.asset } = {}) {
+  if (!receipt || typeof receipt !== 'object') return { ok: false, err: 'no receipt: the transaction is not mined yet, or the hash is wrong' };
+  if (receipt.status !== '0x1' && receipt.status !== 1) return { ok: false, err: 'the transaction reverted; nothing moved' };
+  const to = payTo.toLowerCase(), token = asset.toLowerCase();
+  const senders = new Map();
+  for (const log of receipt.logs || []) {
+    if (String(log.address || '').toLowerCase() !== token) continue;
+    const [sig, fromT, toT] = log.topics || [];
+    if (String(sig || '').toLowerCase() !== PAY.transferTopic || addrOfTopic(toT) !== to) continue;
+    const from = addrOfTopic(fromT);
+    let units; try { units = BigInt(log.data); } catch { continue; }
+    if (units <= 0n) continue;
+    senders.set(from, (senders.get(from) || 0n) + units);
+  }
+  if (!senders.size) return { ok: false, err: `no ${PAY.assetSymbol} transfer to ${PAY.payTo} in this transaction` };
+  if (senders.size > 1) return { ok: false, err: 'the transaction carries transfers from more than one wallet; send from one wallet' };
+  const [[from, units]] = senders;
+  return { ok: true, txHash: String(receipt.transactionHash || '').toLowerCase(), block: receipt.blockNumber ? Number(BigInt(receipt.blockNumber)) : null, from, units, amount: unitsToUsdg(units) };
+}
+
+// The terms a priced tool quotes when the free calls are used: what to pay, where, and how to be recognised.
+export function paymentTerms(tool, price) {
+  return {
+    version: 1, status: 'open', scheme: 'receipt',
+    network: PAY.network, chainId: PAY.chainId, asset: PAY.asset, assetSymbol: PAY.assetSymbol, decimals: PAY.decimals,
+    payTo: PAY.payTo, amount: price, per: 'call', tool,
+    steps: [
+      `Send ${PAY.assetSymbol} on Robinhood Chain (chain id ${PAY.chainId}) from your wallet to ${PAY.payTo}. Any amount; ${PAY.minDepositUsdg} or more makes sense against the gas.`,
+      'Call keelage_pay with { tx: "<transaction hash>" } once. The sending wallet is credited with the amount.',
+      'Send the header X-Wallet: <your address> on every call. Priced calls past the free 20 a day draw on the credit at the price quoted on keelage.ai/#pricing.',
+    ],
+    ledger: 'https://keelage.ai/#ledger',
+  };
+}

package/lib/x.mjs

@@ -0,0 +1,36 @@
+// x.mjs - the keelage_x tool: what X is saying about one token in the last 24 hours, as its own paid call.
+//
+// A scan does not read X (the verdict is structural); this call does, and is priced separately. The facts come
+// from x-meta.mjs: posts and accounts in 24h, copy-paste share, large profiles and the chain they meant, views,
+// and a one-line model-written gist. Display only: never a gate, never a rank key.
+//
+// Sources: the posts need SOCIALDATA_API_KEY; the gist needs XAI_API_KEY (no gist key = facts without the line).
+// Without the posts key the tool is not offered (tools/list leaves it out) and a direct call answers an error
+// before any network read, so a caller is never charged for an empty answer.
+import { isAddress, getJson, candidateFromPairs, CHAIN } from './gate.mjs';
+import { xMeta, xLine, X_META_TTL_H } from './x-meta.mjs';
+
+export function xConfigured() { return !!process.env.SOCIALDATA_API_KEY; }
+
+export async function xFor(address, { log = console.error, force = false } = {}) {
+  const raw = String(address || '').trim();
+  if (!isAddress(raw)) return { ok: false, address: raw, err: 'not a contract address (0x + 40 hex characters)' };
+  const a = raw.toLowerCase();
+  if (!xConfigured()) return { ok: false, address: a, err: 'X read not available on this server: no posts source configured' };
+  const d = await getJson(`https://api.dexscreener.com/tokens/v1/${CHAIN}/${a}`);
+  if (d?.__err) return { ok: false, address: a, err: `dexscreener: ${d.__err}` };
+  const c = candidateFromPairs(CHAIN, a, d);
+  if (!c) return { ok: false, address: a, err: `no DexScreener pair on ${CHAIN} for this address (not traded here, or a different chain)` };
+  let x = null;
+  try { x = await xMeta(c, { log, force }); } catch (e) { return { ok: false, address: a, symbol: c.symbol, err: `x: ${e.message}` }; }
+  if (!x) return { ok: false, address: a, symbol: c.symbol, err: 'X posts source answered with an error; nothing cached for this token' };
+  const { v, ...facts } = x;
+  return {
+    ok: true, address: a, chain: CHAIN, symbol: c.symbol, name: c.name || null,
+    windowHours: 24, cacheHours: X_META_TTL_H,
+    sources: { posts: facts.source || 'socialdata', gist: facts.meta != null ? 'xai' : null },
+    ...facts,
+    line: xLine(x),
+    note: 'Context only: X chatter is never a gate and never a rank key in a Keelage verdict.',
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keelage/mcp",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Token intelligence for Robinhood Chain, as an MCP server. Structural verdicts, holder maps, launcher templates and a published track record. Research only, not financial advice.",
   "type": "module",
   "license": "MIT",

package/server/core.mjs

@@ -7,9 +7,16 @@ import { renderScanJson } from '../lib/render.mjs';
 import { holdersFor } from '../lib/holders.mjs';
 import { templateFor } from '../lib/template.mjs';
 import { trackRecord } from '../lib/record.mjs';
+import { xFor, xConfigured } from '../lib/x.mjs';
 import { knownRulesets, THRESHOLDS } from '../lib/calc.mjs';
 
-export const SERVER_INFO = { name: 'keelage', title: 'Keelage', version: '0.1.0' };
+// The version the server reports is the package's, read through io so the hosted bundle (package.json embedded) agrees.
+import { io } from '../lib/io.mjs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+const PKG_DIR = (() => { try { return join(dirname(fileURLToPath(import.meta.url)), '..'); } catch { return '/keelage'; } })();
+const PKG_VERSION = (() => { try { return JSON.parse(io.read(join(PKG_DIR, 'package.json'))).version; } catch { return '0.0.0'; } })();
+export const SERVER_INFO = { name: 'keelage', title: 'Keelage', version: PKG_VERSION };
 const SUPPORTED = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
 const ADDRESS_SCHEMA = { type: 'string', description: 'Token contract address on Robinhood Chain (0x + 40 hex characters).', pattern: '^0x[0-9a-fA-F]{40}$' };
 // The ruleset the verdict is computed under: a preset by name, or the default with some lines replaced.
@@ -40,6 +47,13 @@ export const TOOLS = [
     inputSchema: { type: 'object', properties: { address: ADDRESS_SCHEMA, smartAccounts: { type: 'boolean', description: 'Check each listed wallet for EIP-7702 delegation (one RPC call per wallet). Default true.' } }, required: ['address'] },
     annotations: { readOnlyHint: true, openWorldHint: true, idempotentHint: true },
   },
+  {
+    name: 'keelage_x',
+    title: 'What X is saying',
+    description: 'What X is saying about one Robinhood Chain token in the last 24 hours: posts and accounts, how much is a repeated template, which large profiles posted and whether they meant this chain\'s token, views, and a one-line read of the narrative. Context only, never part of the verdict; a scan does not read X. Cached 6 hours per token.',
+    inputSchema: { type: 'object', properties: { address: ADDRESS_SCHEMA, fresh: { type: 'boolean', description: 'Skip the 6-hour cache and read X again. Default false.' } }, required: ['address'] },
+    annotations: { readOnlyHint: true, openWorldHint: true, idempotentHint: true },
+  },
   {
     name: 'keelage_template',
     title: 'Launcher template',
@@ -58,8 +72,9 @@ export const TOOLS = [
 
 export async function callTool(name, args = {}) {
   switch (name) {
-    case 'keelage_scan': return renderScanJson(await scanOne(args.address, { log: (...a) => console.error(...a), ruleset: args.ruleset ?? 'default' }));
+    case 'keelage_scan': return renderScanJson(await scanOne(args.address, { log: (...a) => console.error(...a), ruleset: args.ruleset ?? 'default', withX: false }));
     case 'keelage_holders': return holdersFor(args.address, { withSmartAccounts: args.smartAccounts !== false });
+    case 'keelage_x': return xFor(args.address, { log: (...a) => console.error(...a), force: args.fresh === true });
     case 'keelage_template': return templateFor(args.address);
     case 'keelage_record': return trackRecord({ study: args.study || null });
     default: throw Object.assign(new Error(`unknown tool ${name}`), { code: -32602 });
@@ -67,7 +82,9 @@ export async function callTool(name, args = {}) {
 }
 
 // Prices per call in USDG on Robinhood Chain, as published on keelage.ai/#pricing. Free tools are never counted.
-export const TOOL_PRICES = { keelage_scan: '0.05', keelage_holders: '0.03' };
+export const TOOL_PRICES = { keelage_scan: '0.05', keelage_holders: '0.03', keelage_x: '0.02' };
+// keelage_x is offered only where a posts source is configured; a scan never reads X, so the X call is its own price.
+export const offeredTools = () => TOOLS.filter((t) => t.name !== 'keelage_x' || xConfigured());
 export const FREE_TOOLS = ['keelage_record', 'keelage_template'];
 export const FREE_CALLS_PER_DAY = 20;
 export { SUPPORTED };
@@ -85,12 +102,12 @@ export async function dispatch(msg) {
         const asked = String(params.protocolVersion || '');
         const protocolVersion = SUPPORTED.includes(asked) ? asked : SUPPORTED[0];
         return ok(id, { protocolVersion, capabilities: { tools: { listChanged: false } }, serverInfo: SERVER_INFO,
-          instructions: 'Keelage reads Robinhood Chain tokens from the chain and answers with a structural verdict, a holder map, a launcher template and the published track record. Every answer is research only, not financial advice. Unknown facts are null, never zero.' });
+          instructions: 'Keelage reads Robinhood Chain tokens from the chain and answers with a structural verdict, a holder map, a launcher template, the published track record and, as its own call, what X is saying. Every answer is research only, not financial advice. Unknown facts are null, never zero.' });
       }
       case 'notifications/initialized': return;
       case 'notifications/cancelled': return;
       case 'ping': return ok(id, {});
-      case 'tools/list': return ok(id, { tools: TOOLS });
+      case 'tools/list': return ok(id, { tools: offeredTools() });
       case 'tools/call': {
         const name = params.name, args = params.arguments || {};
         if (!TOOLS.some((t) => t.name === name)) return err(id, -32602, `unknown tool ${name}`);

package/server/hosted-io.mjs

@@ -5,5 +5,6 @@ import { setIO, memoryIO } from '../lib/io.mjs';
 import thresholds from '../data/thresholds.json' with { type: 'json' };
 import trackRecord from '../data/track-record.json' with { type: 'json' };
 import templates from '../lib/templates.json' with { type: 'json' };
+import pkg from '../package.json' with { type: 'json' };
 
-setIO(memoryIO({ 'data/thresholds.json': thresholds, 'data/track-record.json': trackRecord, 'lib/templates.json': templates }));
+setIO(memoryIO({ 'data/thresholds.json': thresholds, 'data/track-record.json': trackRecord, 'lib/templates.json': templates, 'package.json': pkg }));