SDK quickstart

Before you start

Use Node.js 22 or newer. The offline sample needs no Neuron login. The live walkthrough needs a Neuron account with workspace access and a published Operating model containing a process with stages. Installing the SDK does not create a workspace or publish a model. No npm package is published and no npm account or provider API key is needed.

1. Download and install

Open the GitHub v0.1.0-beta.3 release linked below. Download neuron-sdk-0.1.0-beta.3.tgz and SHA256SUMS from the same release, and place both in a new project directory. Run these commands in that directory.

shasum -a 256 -c SHA256SUMS
npm install ./neuron-sdk-0.1.0-beta.3.tgz
NEURON_MCP_ENDPOINT=https://neuron.patternlab.ai/api/published-mcp node node_modules/@neuron/sdk/examples/oauth-web/server.mjs

2. Sign in and choose access

Open the printed http://127.0.0.1:8787 URL and choose Sign in and connect. Sign in at Neuron, then select Business context and setup for your workspace and its Operating model entry. Leave unrelated capabilities unchecked. These are two separate read grants: workspace understanding and the published model/processes. The example requests no execution or editing scope.

Consent expires if you leave it unfinished. Start sign-in again if necessary. OAuth keeps the token in the local server session; you do not copy a token, browser cookie, database URI or password into code.

3. Read the full published model

Choose Discover my workspace context and models, select a published model and choose Read full published model. Expand the complete model JSON. The SDK assembles all supported model segments and checks their version and fingerprint before returning a result. This is the permitted published snapshot, not draft definitions or live source records.

If no model appears, reconnect and select its Operating model entry. If none exists, a workspace manager must publish one. The example will not create one for you.

4. Walk through a process

Select a process and choose Read process flow. Inspect its stage directory, modeled links and full policies and governance. Then select a stage and choose Read stage rules and requirements. Repeat for other stages as needed. All these reads stay pinned to the model release you selected.

This is a definition-reading walkthrough. It does not create a run, save inputs, read source records, call an AI provider or perform a business action. Your application can use this context to explain required inputs, responsibilities and choices; the example does not provide an AI conversation. A saved process is not proof its integrations are operational.

If the model has no processes, or a process has no stages, the example explains what is missing. Do not infer a successful process test from model discovery alone.

5. Reuse the authenticated session

The packaged example includes server.mjs for the OAuth session and walkthrough.mjs for the public SDK calls. Use the same server-side auth provider after the callback; no manual access-token copying is needed. The selected workspace, process and stage below come from the preceding discovery/model results.

const client = await NeuronClient.connect({endpoint, authProvider: session.provider});
try {
  const catalog = await discover(client);
  const release = await readModel(client, catalog, selectedWorkspace);
  const process = await readProcess(client, selectedWorkspace, release, selectedProcess);
  const stage = await readStage(client, selectedWorkspace, release, process, selectedStage);
} finally {
  await client.close();
}

Prefer a source checkout?

This alternative builds the SDK and runs the same browser walkthrough. npm run example:oauth belongs to the repository; it will not exist in a fresh project that only installed the release archive. For the account-free fictional sample, run npm run example:offline after npm ci.

git clone --branch v0.1.0-beta.3 https://github.com/nmarlar/neuron-sdk.git
cd neuron-sdk
npm ci
NEURON_MCP_ENDPOINT=https://neuron.patternlab.ai/api/published-mcp npm run example:oauth

Finish and troubleshoot

If the release changes during a read, rediscover and read the current model; partial context is not shown as complete. If the port is occupied, prefix the start command with PORT=8788 and use the printed URL.

Stop the server with Ctrl+C. Tokens are kept only in memory and discarded on restart. Local disconnect does not revoke the grant in Neuron. A production application needs protected per-user storage, refresh handling, origin checks and revocation. Process execution, model changes and computations require separate permissions and verified receipts.