@neus/mcp-server 1.0.0

package/server.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.neus/neus-mcp",
+  "title": "NEUS MCP",
+  "description": "NEUS hosted MCP: verifiers, proofs, verify flows, agents. Always call neus_context first.",
+  "version": "1.0.0",
+  "repository": {
+    "url": "https://github.com/neus/network",
+    "source": "github"
+  },
+  "websiteUrl": "https://docs.neus.network/mcp/overview",
+  "icons": [
+    {
+      "src": "https://neus.network/images/neus-brand-pack/neus-mark-128.png",
+      "sizes": ["128x128"],
+      "mimeType": "image/png"
+    }
+  ],
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://mcp.neus.network/mcp"
+    }
+  ],
+  "capabilities": {
+    "tools": {
+      "supported": true,
+      "listChanged": false
+    },
+    "elicitation": {
+      "supported": true
+    }
+  },
+  "tools": [
+    {
+      "name": "neus_context",
+      "description": "NEUS MCP session home: product summary, setup, access-key mode, verifier summaries, reuse-first workflow, tools, and safety rules. Always call first."
+    },
+    {
+      "name": "neus_verifiers_catalog",
+      "description": "Full verifier directory with JSON schemas. Use after neus_context when payloads need exact fields beyond the summary."
+    },
+    {
+      "name": "neus_proofs_check",
+      "description": "Checks whether existing proofs satisfy verifier IDs. Eligibility only; never creates proofs."
+    },
+    {
+      "name": "neus_verify",
+      "description": "Creates or continues verification only when Profile access, wallet, and signing already satisfy NEUS for this verifier. Check existing receipts first."
+    },
+    {
+      "name": "neus_verify_or_guide",
+      "description": "Fallback orchestration after reuse checks: use only when proof, profile, payment, provider, wallet, or delegation setup is missing."
+    },
+    {
+      "name": "neus_proofs_get",
+      "description": "Reads proof records, tags, delegated agent reads, Profile summary fields, and live proof state. qHashes in the response are authoritative."
+    },
+    {
+      "name": "neus_me",
+      "description": "Returns the signed-in NEUS Profile when a personal access key from Profile → Account is configured on this MCP session."
+    },
+    {
+      "name": "neus_agent_link",
+      "description": "Readiness check for an agent wallet: returns linked when agent-identity and agent-delegation proofs exist; otherwise link_required with hostedVerifyUrl."
+    },
+    {
+      "name": "neus_agent_create",
+      "description": "Prepares agent-identity and agent-delegation payloads (signatures and/or hostedVerifyUrl). Does not finalize receipts; confirm with neus_agent_link after signing. Skills/services fields are metadata only, not secrets."
+    }
+  ],
+  "license": "Apache-2.0",
+  "author": {
+    "name": "NEUS",
+    "email": "info@neus.network",
+    "url": "https://neus.network"
+  },
+  "keywords": [
+    "neus",
+    "mcp",
+    "model-context-protocol",
+    "verification",
+    "trust-receipts",
+    "proofs",
+    "delegation",
+    "identity",
+    "agents",
+    "profile",
+    "wallet",
+    "ai-agents",
+    "ethereum",
+    "solana",
+    "did",
+    "x402"
+  ],
+  "examples": [
+    {
+      "title": "Bootstrap a session",
+      "description": "Load the MCP session home plus verifier summaries.",
+      "prompt": "Call neus_context first, then follow the returned goldenPath. If Bearer is configured, call neus_me before any account-aware work."
+    },
+    {
+      "title": "Register an AI agent",
+      "description": "Identity and delegation proofs for an agent wallet; confirm readiness before use.",
+      "prompt": "Use neus_agent_link first when an agent wallet already exists. Use neus_agent_create only when setup is missing. If a hosted URL is returned, share it exactly, then call neus_agent_link after completion."
+    },
+    {
+      "title": "Gate before a new verification",
+      "description": "Eligibility only—no new proof creation.",
+      "prompt": "Use neus_proofs_check for wallet 0x... and verifier IDs [\"ownership-basic\", \"proof-of-human\"]. Report only whether requirements are satisfied and which verifiers matched—do not start a new verification. Use qHash as the trust receipt reference; contentHash identifies proven content."
+    },
+    {
+      "title": "Reuse first, guide only when missing",
+      "description": "Check existing trust before any browser handoff.",
+      "prompt": "Call neus_proofs_check for wallet 0x... and verifier IDs [\"ownership-basic\"]. If eligible, continue without hosted verify. If not eligible, call neus_verify_or_guide, share any returned hosted URL exactly, then call neus_proofs_get after completion and report the qHash from the proof record."
+    },
+    {
+      "title": "Tag-filtered proof inventory (delegated context)",
+      "description": "Filter proof reads by tags—for memory, skills, jobs—same tool as listing proofs.",
+      "prompt": "For wallet 0x..., call neus_proofs_get with tags=memory,skill and optional agentWallet only when delegated reads apply. Summarize proof titles, tags, and qHashes only—no invented records."
+    },
+    {
+      "title": "Instant verification with Profile access key",
+      "description": "When MCP carries your NEUS access key and the profile wallet matches, some instant verifiers may submit without a wallet signature.",
+      "prompt": "My NEUS personal access key is configured on this MCP connection and walletAddress 0x... matches my NEUS profile wallet. Call neus_context, then neus_me, then neus_proofs_check. If the existing receipt satisfies the request, stop. If not, call neus_verify only when prerequisites match; otherwise explain the next returned setup step."
+    }
+  ],
+  "compatibility": {
+    "claudeDesktop": true,
+    "claudeCode": true,
+    "cursor": true,
+    "vscode": true
+  }
+}

package/test-agent-context.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+/**
+ * Print a compact neus_context view for MCP connectivity checks.
+ * Usage: MCP_E2E_BASE_URL=http://127.0.0.1:3110 node test-agent-context.js
+ */
+
+const BASE_URL = String(process.env.MCP_E2E_BASE_URL || 'https://mcp.neus.network').replace(/\/$/, '');
+
+function parseSseJson(raw) {
+  const dataLine = String(raw || '')
+    .split(/\r?\n/)
+    .find((line) => line.startsWith('data: '));
+  if (!dataLine) throw new Error(`Unexpected MCP response: ${raw.slice(0, 2000)}`);
+  return JSON.parse(dataLine.slice('data: '.length));
+}
+
+async function initMcpSession(baseUrl) {
+  const headers = {
+    'content-type': 'application/json',
+    'mcp-protocol-version': '2025-11-25',
+    accept: 'application/json, text/event-stream'
+  };
+  const response = await fetch(`${baseUrl}/mcp`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: {
+        protocolVersion: '2025-11-25',
+        capabilities: {},
+        clientInfo: { name: 'agent-context-probe', version: '1.0.0' }
+      }
+    })
+  });
+  const raw = await response.text();
+  const sessionId = response.headers.get('mcp-session-id');
+  if (!sessionId) throw new Error(`initialize failed HTTP ${response.status}: ${raw.slice(0, 2000)}`);
+  parseSseJson(raw);
+  return { sessionId, headers };
+}
+
+async function callNeusContext(baseUrl, sessionId, headers) {
+  const response = await fetch(`${baseUrl}/mcp`, {
+    method: 'POST',
+    headers: { ...headers, 'mcp-session-id': sessionId },
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: 2,
+      method: 'tools/call',
+      params: { name: 'neus_context', arguments: {} }
+    })
+  });
+  const raw = await response.text();
+  const payload = parseSseJson(raw);
+  const text = payload?.result?.content?.[0]?.text;
+  if (!text) throw new Error(`no neus_context body: ${raw.slice(0, 2000)}`);
+  return JSON.parse(text);
+}
+
+async function close(baseUrl, sessionId, headers) {
+  try {
+    await fetch(`${baseUrl}/mcp`, {
+      method: 'DELETE',
+      headers: { ...headers, 'mcp-session-id': sessionId }
+    });
+  } catch {
+    /* ignore */
+  }
+}
+
+async function main() {
+  let sessionId;
+  let headers;
+  try {
+    ({ sessionId, headers } = await initMcpSession(BASE_URL));
+    const ctx = await callNeusContext(BASE_URL, sessionId, headers);
+    const summary = {
+      mode: ctx.mode,
+      headline: ctx.product?.headline,
+      goldenPath: ctx.goldenPath,
+      jobIntents: Array.isArray(ctx.jobs) ? ctx.jobs.map((j) => j.intent) : [],
+      verifierCount: Array.isArray(ctx.verifierSummary) ? ctx.verifierSummary.length : null,
+      urls: ctx.setup
+        ? {
+            mcp: ctx.setup.mcpEndpoint,
+            profile: ctx.setup.profileUrl,
+            accessKeys: ctx.setup.accessKeysUrl
+          }
+        : null
+    };
+    console.log(JSON.stringify(summary, null, 2));
+  } finally {
+    if (sessionId && headers) await close(BASE_URL, sessionId, headers);
+  }
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/test-public-mcp-contract.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+
+/**
+ * Static contract guard for the hosted NEUS MCP surface.
+ * Fails on drift across server.json, README, docs, and core server framing.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const MCP_DIR = __dirname;
+
+/** Final public tool surface (order must match server.json and hosted registration). */
+const PUBLIC_TOOLS = [
+  'neus_context',
+  'neus_verifiers_catalog',
+  'neus_proofs_check',
+  'neus_verify',
+  'neus_verify_or_guide',
+  'neus_proofs_get',
+  'neus_me',
+  'neus_agent_link',
+  'neus_agent_create'
+];
+
+const NEUS_CONTEXT_TOP_LEVEL = [
+  'product',
+  'setup',
+  'mode',
+  'goldenPath',
+  'jobs',
+  'tools',
+  'proofModel',
+  'agentModel',
+  'safetyRules',
+  'verifierSummary'
+];
+
+/** Required words in MCP package README (minimal teaching surface). */
+const README_REQUIRED = [
+  'neus_context',
+  'neus_verifiers_catalog',
+  'neus_proofs_check',
+  'neus_verify_or_guide',
+  'neus_verify',
+  'neus_proofs_get',
+  'neus_me',
+  'neus_agent_create',
+  'neus_agent_link',
+  'call neus_context first'
+];
+
+/** Core teaching pages that must retain `neus_proofs_get` mention. */
+const NETWORK_DOC_FILES = ['overview.mdx', 'tools.mdx', 'setup.mdx', 'proofs-get.mdx'];
+
+/** Banned in public MCP-facing manifest + hosted package README (adapter boundary). */
+const BANNED_PUBLIC_SUBSTR = ['Zeus', 'Hostinger', 'trust layer', 'Verification MCP', 'runtime ledger', 'receipt chain'];
+
+function fail(msg) {
+  console.error(`\nPUBLIC MCP CONTRACT FAILURE: ${msg}\n`);
+  process.exit(1);
+}
+
+function readUtf8(rel) {
+  return readFileSync(join(MCP_DIR, rel), 'utf8');
+}
+
+/** Slice of server.js covering public TOOLS[] entries (exclusive of extended tools). */
+function getPublicToolsDocumentationBlock(serverJs) {
+  const start = serverJs.indexOf('const TOOLS = [');
+  if (start < 0) return null;
+  const zeus = serverJs.indexOf("name: 'zeus_url_fetch'", start);
+  if (zeus < 0) return null;
+  return serverJs.slice(start, zeus);
+}
+
+/** First tool-level description string before inputSchema for a named TOOLS entry. */
+function extractToolDescriptionFromToolsBlock(block, toolName) {
+  const needle = `name: '${toolName}'`;
+  const idx = block.indexOf(needle);
+  if (idx < 0) return null;
+  const fromName = block.slice(idx);
+  const schemaAt = fromName.indexOf('inputSchema:');
+  if (schemaAt < 0) return null;
+  const head = fromName.slice(0, schemaAt);
+  const multiline = head.match(/description:\s*\n\s*'((?:[^'\\]|\\.)*)'/);
+  const single = head.match(/description:\s*'((?:[^'\\]|\\.)*)'/);
+  const raw = multiline ? multiline[1] : single ? single[1] : null;
+  return raw;
+}
+
+function main() {
+  const serverJson = JSON.parse(readUtf8('server.json'));
+  const readme = readUtf8('README.md');
+  const serverJs = readUtf8('server.js');
+
+  const title = serverJson.title || '';
+  if (title.includes('Verification MCP')) fail('server.json title must not contain "Verification MCP".');
+
+  /** Official MCP Registry rejects longer server summaries (422). */
+  const REGISTRY_SERVER_DESCRIPTION_MAX = 100;
+  const serverDesc = String(serverJson.description || '');
+  if (serverDesc.length > REGISTRY_SERVER_DESCRIPTION_MAX) {
+    fail(
+      `server.json top-level description must be <= ${REGISTRY_SERVER_DESCRIPTION_MAX} chars for MCP Registry (got ${serverDesc.length})`
+    );
+  }
+
+  if (!Array.isArray(serverJson.tools)) fail('server.json tools must be an array');
+
+  const names = serverJson.tools.map((t) => t?.name).filter(Boolean);
+  if (names.length !== PUBLIC_TOOLS.length) fail(`server.json must expose exactly ${PUBLIC_TOOLS.length} tools`);
+  const setErr = PUBLIC_TOOLS.some((n, i) => names[i] !== n);
+  if (setErr) {
+    fail(
+      `server.json tool order/set mismatch.\nExpected: ${PUBLIC_TOOLS.join(', ')}\nActual: ${names.join(', ')}`
+    );
+  }
+
+  const extra = names.filter((n) => !PUBLIC_TOOLS.includes(n));
+  if (extra.length) fail(`server.json has unexpected tools: ${extra.join(', ')}`);
+
+  const sjPlain = JSON.stringify(serverJson);
+  if (/\b[Hh]ub\b/.test(sjPlain)) fail('server.json must not use public "Hub" language');
+
+  for (const banned of BANNED_PUBLIC_SUBSTR) {
+    if (banned !== 'Verification MCP' && sjPlain.includes(banned)) fail(`server.json must not contain: ${banned}`);
+  }
+
+  if (/\b[Hh]ub\b/.test(readme)) fail('mcp/README.md must not use public "Hub" language');
+
+  for (const needle of README_REQUIRED) {
+    if (!readme.includes(needle)) fail(`mcp/README.md must mention: ${needle}`);
+  }
+
+  const repoRoot = join(MCP_DIR, '..', '..');
+  const networkMcpDocs = join(repoRoot, 'network', 'docs', 'mcp');
+  if (!existsSync(networkMcpDocs)) {
+    fail(`network MCP docs directory missing (expected ${networkMcpDocs})`);
+  }
+
+  for (const doc of NETWORK_DOC_FILES) {
+    const p = join(networkMcpDocs, doc);
+    if (!existsSync(p)) fail(`Missing required doc: ${p}`);
+    const text = readFileSync(p, 'utf8');
+    if (!text.includes('neus_proofs_get')) fail(`${doc} must document neus_proofs_get`);
+    if (/\b[Hh]ub\b/.test(text)) fail(`${doc} must not use public "Hub" language`);
+    if (text.includes('Zeus')) fail(`${doc} must not expose "Zeus"`);
+  }
+
+  if (!/call neus_context first/i.test(serverJs)) {
+    fail('server.js MCP instructions must tell models to call neus_context first');
+  }
+
+  const bpStart = serverJs.indexOf('function buildPublicNeusContextPayload(');
+  if (bpStart < 0) fail('server.js must define buildPublicNeusContextPayload');
+  const bpDelim = '// ERROR REMEDIATION';
+  const bpEnd = serverJs.indexOf(bpDelim, bpStart);
+  if (bpEnd < 0) fail('cannot locate buildPublicNeusContextPayload boundary before ERROR_REMEDIATION');
+  const bpSlice = serverJs.slice(bpStart, bpEnd);
+
+  for (const key of NEUS_CONTEXT_TOP_LEVEL) {
+    if (key === 'verifierSummary') {
+      if (!/\bverifierSummary\b/.test(bpSlice)) fail('buildPublicNeusContextPayload must define verifierSummary');
+    } else if (!bpSlice.includes(`${key}:`)) {
+      fail(`buildPublicNeusContextPayload must define ${key}`);
+    }
+  }
+  const noise = ['defaultCallOrder:', 'routing:', 'toolSelection:', 'responseRules:', 'catalogMeta', 'billing:', 'integrationGuidelines'];
+  for (const bad of noise) {
+    if (bpSlice.includes(bad)) fail(`buildPublicNeusContextPayload must not carry legacy section: ${bad}`);
+  }
+  if (/\bzeus\b/i.test(bpSlice)) fail('buildPublicNeusContextPayload must not mention Zeus');
+  if (/\bhub\b/i.test(bpSlice)) fail('buildPublicNeusContextPayload must not mention Hub wording');
+
+  const toolsDoc = getPublicToolsDocumentationBlock(serverJs);
+  if (!toolsDoc) fail('Cannot slice public TOOLS block before zeus_url_fetch');
+  for (const toolName of PUBLIC_TOOLS) {
+    const fromJs = extractToolDescriptionFromToolsBlock(toolsDoc, toolName);
+    const fromJson = serverJson.tools.find((t) => t.name === toolName)?.description;
+    if (fromJs == null) fail(`Parse TOOLS[].description failed for ${toolName}`);
+    if (fromJs !== fromJson) {
+      fail(
+        `server.json tool "${toolName}" description must equal TOOLS in server.js.\nmanifest: ${JSON.stringify(fromJson)}\nserver.js: ${JSON.stringify(fromJs)}`
+      );
+    }
+  }
+
+  console.log('PUBLIC MCP CONTRACT OK');
+}
+
+main();