@neus/mcp-server 1.0.0 → 1.0.2

package/README.md

@@ -1,63 +1,40 @@
-# NEUS MCP (server package)
+# @neus/mcp-server
 
-**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.
+Model Context Protocol server for NEUS trust receipts, verification, and agent flows.
 
-**Production URL:** `https://mcp.neus.network/mcp`
+## Prefer the hosted endpoint
 
-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.
+For almost all integrations, connect to **`https://mcp.neus.network/mcp`** and follow **[MCP setup](https://docs.neus.network/mcp/setup)** (transport, auth, and access keys).
 
-**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.
+This npm package ships **public discovery metadata** (for example `server.json`) for registries and installers. The hosted MCP server runs at **`https://mcp.neus.network/mcp`** — see the [MCP docs](https://docs.neus.network/mcp/overview) for setup and usage.
 
-Public guides: **[docs.neus.network/mcp](https://docs.neus.network/mcp/overview)**.
+## Golden path (nine tools)
 
-**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
+Models should **call neus_context first** every session, then follow the tool order your client needs:
 
 | 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
+| `neus_context` | Session home — setup, verifier summaries, golden path |
+| `neus_verifiers_catalog` | Verifier metadata and JSON schemas |
+| `neus_proofs_check` | Eligibility only (does not create proofs) |
+| `neus_verify` | Start or continue verification when prerequisites already match |
+| `neus_verify_or_guide` | Guided flow when setup or consent is still missing |
+| `neus_proofs_get` | Read proof records, tags, and delegated context |
+| `neus_me` | Signed-in Profile when a personal access key is configured on the session |
+| `neus_agent_link` | Confirm agent identity and delegation readiness |
+| `neus_agent_create` | Prepare agent identity and delegation when setup is missing |
 
-Validate the public packaging contract (manifest ↔ `server.js` framing): **`npm run test:public-contract`**
+With a Profile access key on the MCP session, call **`neus_me`** and expect a successful status before relying on account-scoped behavior.
 
-Local MCP smoke (**context + discovery**): **`npm run test:e2e:local`**
+## Auth and safety
 
-Hosted MCP smoke (**same against production URL**): **`npm run test:e2e:live`**
+Use **`Authorization: Bearer`** with the **personal access key** from the NEUS app (Profile → Account). Do not embed secrets in public repos or client-side bundles. Inputs are validated at runtime.
 
-Agent create/link flow (**local server**): **`npm run test:e2e:agent`**
+## Docs and support
 
-**`neus_context`** regression (URLs from env — see **`test-agent-context.js`**): **`npm run test:agent-context`**
+- **Product MCP guides:** [docs.neus.network/mcp](https://docs.neus.network/mcp/overview)  
+- **Issues (public):** [github.com/neus/network/issues](https://github.com/neus/network/issues)
 
 ## License
 
-Apache-2.0
+Apache-2.0 (see the `license` field in `package.json`).

package/index.mjs

@@ -0,0 +1,21 @@
+/**
+ * @neus/mcp-server — discovery metadata only.
+ * The hosted NEUS MCP server runs at https://mcp.neus.network/mcp, not inside this npm package.
+ *
+ * @see https://mcp.neus.network/mcp
+ * @see https://docs.neus.network/mcp/setup
+ */
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** @returns {Record<string, unknown>} Parsed MCP registry / installer manifest (`server.json`). */
+export function loadServerManifest() {
+  const raw = readFileSync(join(__dirname, 'server.json'), 'utf8');
+  return JSON.parse(raw);
+}
+
+export const serverManifest = loadServerManifest();

package/package.json

@@ -1,47 +1,12 @@
 {
   "name": "@neus/mcp-server",
-  "version": "1.0.0",
-  "mcpName": "io.github.neus/neus-mcp",
-  "description": "NEUS MCP over HTTP: verifiers, proof checks, guided verify, reads, agent identity/delegation.",
+  "version": "1.0.2",
+  "description": "Public discovery metadata for the hosted NEUS MCP (streamable HTTP). Runtime is not shipped in this package.",
   "type": "module",
-  "main": "server.js",
-  "bin": {
-    "neus-mcp": "server.js"
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs"
   },
-  "scripts": {
-    "start": "node server.js",
-    "dev": "node --watch server.js",
-    "test:e2e:local": "node e2e-mcp-local.test.js",
-    "test:e2e:live": "node e2e-mcp-live.test.js",
-    "test:e2e:agent": "node e2e-mcp-agent-local.test.js",
-    "test:agent-context": "node test-agent-context.js",
-    "test:public-contract": "node test-public-mcp-contract.js"
-  },
-  "engines": {
-    "node": ">=22.13.0"
-  },
-  "dependencies": {
-    "@azure/monitor-opentelemetry": "^1.11.0",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/resources": "^2.7.1",
-    "viem": "^2.47.6",
-    "zod": "^4.3.6"
-  },
-  "keywords": [
-    "neus",
-    "mcp",
-    "model-context-protocol",
-    "verification",
-    "proofs",
-    "agents",
-    "gate-check",
-    "ai-agents",
-    "identity",
-    "web3",
-    "wallet-verification",
-    "sybil-resistance"
-  ],
   "license": "Apache-2.0",
   "author": "NEUS Network <info@neus.network>",
   "homepage": "https://neus.network",
@@ -50,18 +15,24 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/neus/protocol.git",
+    "url": "git+https://github.com/neus/network.git",
     "directory": "mcp"
   },
+  "keywords": [
+    "neus",
+    "mcp",
+    "model-context-protocol",
+    "verification",
+    "trust-receipts",
+    "proofs",
+    "agents"
+  ],
   "files": [
-    "server.js",
+    "index.mjs",
     "README.md",
-    "server.json",
-    "CHANGELOG.md",
-    "e2e-mcp-local.test.js",
-    "e2e-mcp-live.test.js",
-    "e2e-mcp-agent-local.test.js",
-    "test-agent-context.js",
-    "test-public-mcp-contract.js"
-  ]
+    "server.json"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  }
 }

package/server.json

@@ -3,7 +3,7 @@
   "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",
+  "version": "1.0.1",
   "repository": {
     "url": "https://github.com/neus/network",
     "source": "github"

package/CHANGELOG.md

@@ -1,18 +0,0 @@
-# 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/e2e-mcp-agent-local.test.js

@@ -1,220 +0,0 @@
-#!/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);
-});