Cork Model Context Protocol server

cork-mcp gives agents and applications a typed interface to Cork Protocol market data and transaction construction.

It exposes tools for:

• discovering Cork pools, flows, whitelists, limit-order markets, orders, and fills;
• verifying market and deployment evidence;
• inspecting and preparing token authority changes;
• preparing, finalizing, simulating, and reconciling Cork actions;
• constructing caller-owned Safe transactions without collecting confirmations;
• preparing limit orders and market deployments; and
• reporting which capabilities are currently callable.

Read results preserve the upstream response bytes and label them as untrusted source observations. Write tools construct artifacts only. The server does not hold signing keys, confirm Safe transactions, or broadcast on behalf of the caller.

Requirements

• Node.js 22
• npm 10.9

The packages are currently consumed from this repository rather than a public package release.

The runnable server has two explicit modes: a no-network fixture mode for transaction construction tests and an opt-in live read-only mode for Phoenix market data. Production write activation requires operator-supplied evidence, policy, credentials, and chain infrastructure; it is not enabled by this repository alone.

Install

git clone https://github.com/Cork-Technology/cork-mcp.git
cd cork-mcp
npm ci
npm run build

Confirm the runtime and repository are healthy:

npm run check:runtime
npm run ci

Try it locally

Run a complete local client/server handshake:

npm run mcp:smoke

This starts the server over standard input/output, discovers its tools, and constructs a deterministic non-broadcast Safe transaction for a synthetic market.

List the synthetic markets available to the Safe demo:

npm run mcp:safe-demo -- --list

Construct a Safe transaction:

npm run mcp:safe-demo

Construct one proposal for each of the six supported Cork action profiles:

npm run mcp:safe-coverage

The coverage command produces sequential, unsigned Safe proposals for safeUnwindMint, safeDeposit, safeMint, safeUnwindSwap, safeUnwindDeposit, and safeRedeem. It is a deterministic local encoding test, not a chain simulation.

Add -- --json to mcp:safe-coverage to inspect all six complete artifacts.

Select a market and inspect the complete artifacts:

npm run mcp:safe-demo -- \
  --market synthetic-wsteth-usdc-2027 \
  --shares 5000000000000 \
  --min-collateral 2000000 \
  --nonce 8 \
  --json

The Safe demo is fully local. Its chain, markets, addresses, balances, evidence, and Permit2 signatures are fixtures and must not be submitted to a real chain.

Read live Cork market data

Run the opt-in read-only integration test:

npm run mcp:live-read

The command calls https://api-phoenix.cork.tech through the Model Context Protocol server and canonical Node adapter. It tests:

• all, current, and expired pools;
• pool flows and whitelist entries;
• limit-order markets;
• the orderbook; and
• fills.

Live-read mode exposes only capability and read tools. It permits HTTP GET requests to the configured Phoenix origin and does not expose preparation, signing, submission, or broadcast tools. Add --json for a machine-readable result.

Connect a Model Context Protocol client

Build once, then configure the client to start the server directly with Node.js 22:

{
  "mcpServers": {
    "cork": {
      "command": "/absolute/path/to/node-22",
      "args": [
        "/absolute/path/to/cork-mcp/packages/gateway/dist/dev-server.js",
        "--quiet"
      ],
      "cwd": "/absolute/path/to/cork-mcp"
    }
  }
}

The default server is fixture-only and performs no network requests. Add --live-read before --quiet to enable the public read-only Phoenix tools.

Run the server manually when debugging a client connection:

npm run mcp:dev

The process waits for a client on standard input/output. This is expected. Server diagnostics use standard error so they do not corrupt the protocol stream.

Tool behavior

Every tool has a closed input schema: unknown fields are rejected. The gateway also enforces credential scopes, capability maturity, bounded work, cancellation, and deadlines before invoking a handler.

The main tool groups are:

Group	Examples	Effect
Capabilities	cork.capabilities.v1	Read
Phoenix data	cork.phoenix.pools.list.v1, cork.phoenix.flows.list.v1	Read
Limit orders	market, orderbook, fill, maker, taker, cancellation tools	Read or construct
Authority	inspect, onboard preparation, revocation preparation	Read or construct
Cork actions	mint, unwind, repurchase, redeem lifecycles	Construct, simulate, reconcile
Market deployment	quote, prepare, simulate, reconcile	Construct, simulate, reconcile
Local demos	market list, Safe unwind, six-profile Safe coverage	Fixture only

A tool being discoverable does not mean that a production capability is active. cork.capabilities.v1 is the source for the current callable state.

Safe boundary

The server may construct calldata, Safe transaction fields, and the Safe transaction hash. Safe message signatures and Safe transaction confirmations remain separate. The caller owns confirmation, submission, receipt storage, and retries.

For a real Safe proposal, the caller must supply current verified market evidence, the exact Safe configuration and nonce, caller-owned authorization artifacts, and a simulation against pinned chain state. The local demo does not substitute fixture values for those inputs.

Packages

Package	Purpose
@corkprotocol/operations	Browser-safe canonical encoders, validators, hashes, and operation state machines
@corkprotocol/operations-node	Phoenix, Market Registry, provider, and inventory observation adapters
@corkprotocol/gateway	Model Context Protocol transport, routing, controls, local server, and demos
@corkprotocol/conformance	Cross-package and public-artifact conformance tests

The Rust signing gate is under crates/signing-gate and remains independent from the TypeScript operation core.

Development

npm run format:check
npm run build
npm run typecheck
npm run test
npm run ci

Useful focused commands:

npm test --workspace @corkprotocol/operations
npm test --workspace @corkprotocol/operations-node
npm test --workspace @corkprotocol/gateway
npm test --workspace @corkprotocol/conformance

See docs/local-development.md for local modes and troubleshooting, docs/integration.md for integration contracts, and docs/security.md for trust and custody boundaries.

License

This repository is currently unlicensed for external redistribution. See package.json for the recorded package license state.