@neus/mcp-server 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to `@neus/mcp-server` are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+- **SSOT:** MCP process env is built in `../src/config/mcpConfig.js` (`buildMcpConfig`); Zeus index tags live in `../src/utils/zeusProofIndexTags.cjs`. The container image is built with `docker build -f mcp/Dockerfile` from the protocol repo root.
+- This package is **not yet published** to the public npm registry. A manual publish workflow exists; when a release is published, it will be listed below with a version and date.
+
+### Current tree (1.0.0)
+
+- **Transport:** Streamable HTTP (default); `MCP_TRANSPORT=stdio` for local CLI. Hosted URL: `https://mcp.neus.network/mcp` (see [MCP docs](https://docs.neus.network/mcp/overview)).
+- **Registry:** `server.json` follows the MCP server registry schema. Its **`version`** field is **manifest / implementation semver** for registry consumers — **not** MCP wire **`protocolVersion`** (see **Runtime** below). **`$schema`** date is the registry JSON schema revision, not the wire revision.
+- **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`.
+- **Proof reads:** `neus_proofs_get` supports optional `tags` and `agentWallet` aligned with the HTTP proof-by-wallet contract; consolidated read path (no separate index/content tools).
+- **Context / copy:** Server `instructions` match public doc session order (context → optional Bearer + `neus_me` → work → `neus_proofs_get`); Bearer framed as optional. Tool descriptions verb-first; `neus_context` includes structured `proofCreation` where applicable.
+- **neus_verify:** `data` optional and defaults to `{}` when verifiers have no `requiredFields` (Zod + API aligned).
+- **Runtime:** Node `>=22.13` (see `package.json` `engines`). MCP wire `protocolVersion` / `mcp-protocol-version`: **`2025-11-25`**. Issues: [github.com/neus/network/issues](https://github.com/neus/network/issues). Implementation is maintained in the NEUS API repository; sources are not vendored into the public `neus/network` tree.

package/README.md

@@ -0,0 +1,63 @@
+# NEUS MCP (server package)
+
+**Integrators:** use the **[hosted MCP endpoint](https://docs.neus.network/mcp/setup)**. Connect once, add an access key when account-aware reuse is needed, and let tools check existing receipts before any browser handoff.
+
+**Production URL:** `https://mcp.neus.network/mcp`
+
+This directory is the **`@neus/mcp-server`** package (see `package.json`). It requires **Node >= 22.13** (see `package.json`). Most projects connect to the hosted URL above and do not need a local install.
+
+**npm:** `@neus/mcp-server` may not yet be published on the public npm registry. Run from this repo (`npm ci` in `mcp/`, then `node server.js` or `npm start`), or use the hosted endpoint.
+
+Public guides: **[docs.neus.network/mcp](https://docs.neus.network/mcp/overview)**.
+
+**Distribution:** Apache-2.0. The **`server.json`** file beside this README is MCP **installer / discovery manifest** metadata (`version` follows this package; MCP wire revision is negotiated at session initialize). **Documentation** stays on [docs.neus.network/mcp](https://docs.neus.network/mcp/overview). **Issues** use the **[neus/network](https://github.com/neus/network/issues)** tracker. Implementation is maintained **in the NEUS API repository** (not mirrored as a second `server.js` under the public repo tree).
+
+## Public Tools And Golden Path
+
+By default, **`server.js`** registers **nine** hosted tools. Models should **call neus_context first** each session. The **`server.json`** top-level `description` matches the MCP Registry length limit (≤100 chars) and stays aligned with this README.
+
+1. Call **`neus_context`** first every session.
+2. If a Profile access key is configured, call **`neus_me`**.
+3. For agents, call **`neus_agent_link`** before assuming identity or delegation is ready.
+4. Use **`neus_proofs_check`** to check access without creating anything.
+5. If requirements are satisfied, continue without hosted verify.
+6. Use **`neus_proofs_get`** when you need authoritative proof records, tags, delegated reads, or qHashes.
+7. Use **`neus_verify`** only when your Profile personal access key, signing, and wallet identifiers already match NEUS guidance for this verifier path.
+8. Use **`neus_verify_or_guide`** only when proof, profile, payment, provider, wallet, or delegation setup is missing.
+9. Use **`neus_agent_create`** only when agent setup is missing, then confirm with **`neus_agent_link`**.
+
+Also use **`neus_verifiers_catalog`** when **`neus_context`** is not enough for JSON schemas. After **`neus_context`**, when a Profile access key is configured on this MCP session, call **`neus_me`** and expect **`status: ok`** before relying on profile-scoped behavior.
+
+Inputs are validated with **Zod** at runtime. When your MCP client attaches **`Authorization: Bearer`** plus the **personal access key** minted under Profile → Account, NEUS resolves the signed-in Profile ([auth docs](https://docs.neus.network/mcp/setup)).
+
+### Tool list
+
+| Tool | Role |
+| --- | --- |
+| `neus_context` | Session home — URLs, CLI, auth mode, `goldenPath`, `jobs`, `verifierSummary`, reminders |
+| `neus_verifiers_catalog` | Full verifier metadata and schemas |
+| `neus_proofs_check` | Eligibility only (no new proofs) |
+| `neus_verify_or_guide` | Fallback orchestration when setup or browser-only consent is missing |
+| `neus_verify` | Create or continue verification when the Profile + signing path is correct |
+| `neus_proofs_get` | Proof records, inventory, tags, delegated reads |
+| `neus_me` | Signed-in Profile (when MCP carries your personal access key) |
+| `neus_agent_create` | Start missing agent identity + delegation setup |
+| `neus_agent_link` | Confirm agent readiness |
+
+Deploy-only helpers may appear in extended developer builds; hosted production stays on the nine-tool surface above.
+
+## Checks
+
+Validate the public packaging contract (manifest ↔ `server.js` framing): **`npm run test:public-contract`**
+
+Local MCP smoke (**context + discovery**): **`npm run test:e2e:local`**
+
+Hosted MCP smoke (**same against production URL**): **`npm run test:e2e:live`**
+
+Agent create/link flow (**local server**): **`npm run test:e2e:agent`**
+
+**`neus_context`** regression (URLs from env — see **`test-agent-context.js`**): **`npm run test:agent-context`**
+
+## License
+
+Apache-2.0

package/e2e-mcp-agent-local.test.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { privateKeyToAccount } from 'viem/accounts';
+
+const PORT = 3105;
+const BASE_URL = `http://127.0.0.1:${PORT}`;
+const CONTROLLER_WALLET = '0x0000000000000000000000000000000000000001';
+
+function wait(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForHealth(url, timeoutMs = 15000) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    try {
+      const res = await fetch(`${url}/health`);
+      if (res.ok) return true;
+    } catch {
+      // Ignore until ready.
+    }
+    await wait(250);
+  }
+  return false;
+}
+
+function parseSseJson(raw) {
+  const trimmed = String(raw || '').trim();
+  if (trimmed.startsWith('{')) {
+    return JSON.parse(trimmed);
+  }
+  const dataLine = String(raw || '')
+    .split(/\r?\n/)
+    .find((line) => line.startsWith('data: '));
+  if (!dataLine) {
+    throw new Error(`Unexpected MCP response: ${raw}`);
+  }
+  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-smoke', version: '1.0.0' },
+      },
+    }),
+  });
+
+  const raw = await response.text();
+  const sessionId = response.headers.get('mcp-session-id');
+  if (sessionId) {
+    let detail = raw.slice(0, 2000);
+    try {
+      const j = parseSseJson(raw);
+      if (j?.error) detail = JSON.stringify(j.error);
+    } catch {
+      // keep truncated raw
+    }
+    throw new Error(`MCP initialize should be stateless and must not return mcp-session-id ${sessionId}: ${detail}`);
+  }
+
+  parseSseJson(raw);
+  return { headers };
+}
+
+async function listTools(baseUrl, headers, id) {
+  const response = await fetch(`${baseUrl}/mcp`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id,
+      method: 'tools/list',
+      params: {},
+    }),
+  });
+
+  const raw = await response.text();
+  const payload = parseSseJson(raw);
+  return payload?.result?.tools || [];
+}
+
+async function callTool(baseUrl, headers, id, name, args) {
+  const response = await fetch(`${baseUrl}/mcp`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id,
+      method: 'tools/call',
+      params: {
+        name,
+        arguments: args,
+      },
+    }),
+  });
+
+  const raw = await response.text();
+  const payload = parseSseJson(raw);
+  const text = payload?.result?.content?.[0]?.text;
+  if (!text) {
+    throw new Error(`Missing tool payload for ${name}: ${raw}`);
+  }
+  return JSON.parse(text);
+}
+
+async function main() {
+  console.log('\n=== NEUS MCP Agent Local E2E ===');
+  console.log(`Spawning MCP on ${BASE_URL}`);
+
+  const child = spawn(process.execPath, ['server.js'], {
+    cwd: new URL('.', import.meta.url),
+    env: {
+      ...process.env,
+      MCP_TRANSPORT: 'http',
+      HOST: '127.0.0.1',
+      PORT: String(PORT),
+    },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  child.stdout.on('data', () => {});
+  child.stderr.on('data', () => {});
+
+  let headers = null;
+
+  try {
+    const ready = await waitForHealth(BASE_URL);
+    if (!ready) {
+      throw new Error('MCP server did not become healthy in time');
+    }
+    console.log('  ✓ Health endpoint');
+
+    ({ headers } = await initMcpSession(BASE_URL));
+    console.log('  ✓ MCP stateless initialize');
+
+    const tools = await listTools(BASE_URL, headers, 99);
+    const verifyTool = tools.find((t) => t.name === 'neus_verify');
+    const props = Object.keys(verifyTool?.inputSchema?.properties || {});
+    if (!props.includes('walletAddress') || !props.includes('verifierIds') || !props.includes('data')) {
+      throw new Error(`tools/list must expose neus_verify args; got properties: ${props.join(',')}`);
+    }
+    console.log('  ✓ tools/list exposes neus_verify parameter schema');
+
+    const proofsCheckTool = tools.find((t) => t.name === 'neus_proofs_check');
+    const proofsCheckProps = Object.keys(proofsCheckTool?.inputSchema?.properties || {});
+    if (proofsCheckProps.includes('sponsorGrant')) {
+      throw new Error(`tools/list must not expose legacy sponsorGrant; got properties: ${proofsCheckProps.join(',')}`);
+    }
+    console.log('  legacy sponsorGrant input hidden from tools/list');
+
+    const createResult = await callTool(BASE_URL, headers, 2, 'neus_agent_create', {
+      agentId: 'smoke-agent',
+      agentWallet: 'generate',
+      controllerWallet: CONTROLLER_WALLET,
+    });
+    if (createResult?.status !== 'signatures_required') {
+      throw new Error(`Unexpected create status: ${JSON.stringify(createResult)}`);
+    }
+
+    const generatedWallet = createResult?.agent?.generatedWallet;
+    if (!generatedWallet?.privateKey || !generatedWallet?.address) {
+      throw new Error(`Missing generated wallet payload: ${JSON.stringify(createResult)}`);
+    }
+
+    const derivedAddress = privateKeyToAccount(generatedWallet.privateKey).address.toLowerCase();
+    if (derivedAddress !== String(generatedWallet.address).toLowerCase()) {
+      throw new Error(`Generated wallet mismatch: ${generatedWallet.address} !== ${derivedAddress}`);
+    }
+    console.log('  ✓ Generated wallet key/address pair matches');
+
+    if (!String(createResult.hostedVerifyUrl || '').includes('agentWallet=')) {
+      throw new Error(`Missing agentWallet in hostedVerifyUrl: ${createResult.hostedVerifyUrl}`);
+    }
+    if (!String(createResult.hostedVerifyUrl || '').includes('controllerWallet=')) {
+      throw new Error(`Missing controllerWallet in hostedVerifyUrl: ${createResult.hostedVerifyUrl}`);
+    }
+    console.log('  ✓ Agent create hostedVerifyUrl includes agent + controller context');
+
+    const linkResult = await callTool(BASE_URL, headers, 3, 'neus_agent_link', {
+      agentWallet: createResult.agent.agentWallet,
+      principal: CONTROLLER_WALLET,
+    });
+    if (linkResult?.status !== 'link_required') {
+      throw new Error(`Unexpected link status: ${JSON.stringify(linkResult)}`);
+    }
+    if (linkResult?.nextSteps?.action !== 'open_hosted_verify') {
+      throw new Error(`Unexpected next step action: ${JSON.stringify(linkResult)}`);
+    }
+    if (linkResult?.principal?.toLowerCase() !== CONTROLLER_WALLET.toLowerCase()) {
+      throw new Error(`Principal was not preserved: ${JSON.stringify(linkResult)}`);
+    }
+    console.log('  ✓ Agent link returns browser-first guidance with principal context');
+
+    console.log('\n--- Summary ---');
+    console.log('Passed: 5  Failed: 0');
+  } finally {
+    child.kill('SIGTERM');
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/e2e-mcp-live.test.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+
+/**
+ * Hosted NEUS MCP smoke (production by default). Set MCP_E2E_BASE_URL to override.
+ *
+ * Hosted MCP may be stateful or stateless during rollout. If initialize returns
+ * mcp-session-id, reuse it and send notifications/initialized before tools/list.
+ */
+
+const BASE_URL = String(process.env.MCP_E2E_BASE_URL || 'https://mcp.neus.network').replace(/\/$/, '');
+
+const EXPECTED_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_KEYS = [
+  'product',
+  'setup',
+  'mode',
+  'goldenPath',
+  'jobs',
+  'tools',
+  'proofModel',
+  'agentModel',
+  'safetyRules',
+  'verifierSummary'
+];
+
+function unwrapDataArray(value, label) {
+  if (Array.isArray(value)) return value;
+  if (value?.success === true && Array.isArray(value.data)) return value.data;
+  throw new Error(`${label} must return an array or { success: true, data: array }, got: ${JSON.stringify(value).slice(0, 400)}`);
+}
+
+function parseSseJson(raw) {
+  const trimmed = String(raw || '').trim();
+  if (!trimmed) return null;
+  if (trimmed.startsWith('{')) {
+    return JSON.parse(trimmed);
+  }
+  const dataLine = String(raw || '')
+    .split(/\r?\n/)
+    .find((line) => line.startsWith('data: '));
+  if (!dataLine) {
+    throw new Error(`Unexpected MCP response: ${raw.slice(0, 500)}`);
+  }
+  return JSON.parse(dataLine.slice('data: '.length));
+}
+
+const COMMON_HEADERS = {
+  'content-type': 'application/json',
+  'mcp-protocol-version': '2025-11-25',
+  accept: 'application/json, text/event-stream'
+};
+
+async function post(baseUrl, body, extraHeaders = {}) {
+  const response = await fetch(`${baseUrl}/mcp`, {
+    method: 'POST',
+    headers: { ...COMMON_HEADERS, ...extraHeaders },
+    body: JSON.stringify(body)
+  });
+  const raw = await response.text();
+  return {
+    status: response.status,
+    payload: parseSseJson(raw),
+    sessionId: response.headers.get('mcp-session-id')
+  };
+}
+
+async function callTool(baseUrl, headers, id, name, args) {
+  const { payload } = await post(baseUrl, {
+    jsonrpc: '2.0',
+    id,
+    method: 'tools/call',
+    params: { name, arguments: args }
+  }, headers);
+  const text = payload?.result?.content?.[0]?.text;
+  if (!text) {
+    throw new Error(`Missing tool payload for ${name}: ${JSON.stringify(payload).slice(0, 400)}`);
+  }
+  return JSON.parse(text);
+}
+
+async function main() {
+  console.log('\n=== NEUS MCP hosted E2E ===');
+  console.log(`BASE_URL=${BASE_URL}`);
+
+  // initialize
+  const { status: initStatus, payload: initPayload, sessionId } = await post(BASE_URL, {
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'initialize',
+    params: {
+      protocolVersion: '2025-11-25',
+      capabilities: {},
+      clientInfo: { name: 'mcp-live-e2e', version: '1.0.0' }
+    }
+  });
+  if (initStatus !== 200) {
+    throw new Error(`Initialize HTTP ${initStatus}: ${JSON.stringify(initPayload).slice(0, 400)}`);
+  }
+  if (!initPayload?.result?.protocolVersion) {
+    throw new Error(`Initialize missing protocolVersion: ${JSON.stringify(initPayload).slice(0, 400)}`);
+  }
+  const sessionHeaders = sessionId ? { 'mcp-session-id': sessionId } : {};
+  if (sessionId) {
+    const { status: initializedStatus } = await post(BASE_URL, {
+      jsonrpc: '2.0',
+      method: 'notifications/initialized',
+      params: {}
+    }, sessionHeaders);
+    if (initializedStatus !== 202 && initializedStatus !== 200) {
+      throw new Error(`notifications/initialized HTTP ${initializedStatus}`);
+    }
+  }
+  console.log(sessionId ? '  ✓ initialize (stateful streamable HTTP)' : '  ✓ initialize (stateless HTTP)');
+
+  // tools/list
+  const { payload: listPayload } = await post(BASE_URL, {
+    jsonrpc: '2.0',
+    id: 2,
+    method: 'tools/list',
+    params: {}
+  }, sessionHeaders);
+  if (listPayload?.error) {
+    throw new Error(`tools/list failed: ${JSON.stringify(listPayload.error).slice(0, 400)}`);
+  }
+  const tools = listPayload?.result?.tools || [];
+  const names = tools.map((t) => t.name);
+  if (names.join(',') !== EXPECTED_TOOLS.join(',')) {
+    throw new Error(`Unexpected hosted tool list.\nExpected: ${EXPECTED_TOOLS.join(', ')}\nGot: ${names.join(', ')}`);
+  }
+  console.log('  ✓ tools/list');
+
+  // neus_context
+  const ctx = await callTool(BASE_URL, sessionHeaders, 3, 'neus_context', {});
+  const keys = Object.keys(ctx).sort();
+  const expectedKeys = [...NEUS_CONTEXT_KEYS].sort();
+  if (keys.join(',') !== expectedKeys.join(',')) {
+    throw new Error(`Unexpected neus_context shape.\nExpected keys: ${expectedKeys.join(', ')}\nGot: ${keys.join(', ')}`);
+  }
+  if (!Array.isArray(ctx.goldenPath) || ctx.goldenPath.length === 0) {
+    throw new Error('neus_context.goldenPath must be a non-empty array');
+  }
+  if (!Array.isArray(ctx.verifierSummary)) {
+    throw new Error('neus_context.verifierSummary must be an array');
+  }
+  console.log('  ✓ neus_context contract (ten keys)');
+
+  // neus_verifiers_catalog
+  const cat = unwrapDataArray(await callTool(BASE_URL, sessionHeaders, 4, 'neus_verifiers_catalog', {}), 'neus_verifiers_catalog');
+  console.log(`  ✓ neus_verifiers_catalog (array, length=${cat.length})`);
+
+  // neus_proofs_check
+  const chk = await callTool(BASE_URL, sessionHeaders, 5, 'neus_proofs_check', {
+    wallet: '0x0000000000000000000000000000000000000001',
+    verifiers: ['ownership-basic']
+  });
+  if (typeof chk?.eligible !== 'boolean') {
+    throw new Error(`neus_proofs_check missing eligible boolean: ${JSON.stringify(chk).slice(0, 400)}`);
+  }
+  console.log('  ✓ neus_proofs_check');
+
+  // neus_verify_or_guide
+  const vog = await callTool(BASE_URL, sessionHeaders, 6, 'neus_verify_or_guide', {
+    walletAddress: '0x0000000000000000000000000000000000000001',
+    verifierIds: ['ownership-basic']
+  });
+  if (typeof vog?.eligible !== 'boolean') {
+    throw new Error(`neus_verify_or_guide missing eligible boolean: ${JSON.stringify(vog).slice(0, 400)}`);
+  }
+  console.log('  ✓ neus_verify_or_guide');
+
+  // neus_proofs_get
+  const pg = await callTool(BASE_URL, sessionHeaders, 7, 'neus_proofs_get', {
+    identifier: '0x0000000000000000000000000000000000000001',
+    limit: 5
+  });
+  if (!pg || typeof pg !== 'object' || !Array.isArray(pg.data?.proofs)) {
+    throw new Error(`neus_proofs_get missing data.proofs array: ${JSON.stringify(pg).slice(0, 400)}`);
+  }
+  console.log('  ✓ neus_proofs_get');
+
+  // neus_me
+  const me = await callTool(BASE_URL, sessionHeaders, 8, 'neus_me', {});
+  if (typeof me?.status !== 'string') {
+    throw new Error(`neus_me missing status string: ${JSON.stringify(me).slice(0, 400)}`);
+  }
+  console.log('  ✓ neus_me');
+
+  // neus_agent_link
+  const al = await callTool(BASE_URL, sessionHeaders, 9, 'neus_agent_link', {
+    agentWallet: '0x0000000000000000000000000000000000000001'
+  });
+  if (typeof al?.status !== 'string') {
+    throw new Error(`neus_agent_link missing status string: ${JSON.stringify(al).slice(0, 400)}`);
+  }
+  console.log('  ✓ neus_agent_link');
+
+  // neus_agent_create
+  const ac = await callTool(BASE_URL, sessionHeaders, 10, 'neus_agent_create', {
+    agentId: 'e2e-test-agent',
+    agentWallet: 'generate'
+  });
+  if (typeof ac?.status !== 'string' && typeof ac?.error !== 'string') {
+    throw new Error(`neus_agent_create missing status or error: ${JSON.stringify(ac).slice(0, 400)}`);
+  }
+  console.log('  ✓ neus_agent_create');
+
+  // neus_verify (preparation step)
+  const v = await callTool(BASE_URL, sessionHeaders, 11, 'neus_verify', {
+    walletAddress: '0x0000000000000000000000000000000000000001',
+    verifierIds: ['ownership-basic']
+  });
+  if (typeof v?.status !== 'string' && typeof v?.error !== 'string') {
+    throw new Error(`neus_verify missing status or error: ${JSON.stringify(v).slice(0, 400)}`);
+  }
+  console.log('  ✓ neus_verify');
+
+  console.log('\n--- Summary ---');
+  console.log('Passed');
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});