mcp-client

Driving CEL from a Raw MCP Client

This page shows how to drive CEL from a framework-less MCP client using the standard MCP SDKs.

Read docs/adapters-cel-agents.md first if you haven't.

Purpose

This is the reference integration. It proves the claim that CEL is agent-agnostic: any MCP-speaking process can drive CEL with no bespoke glue. Use this page when:

• You are writing a custom agent and want to call CEL tools directly.
• You are debugging whether a problem is in your agent framework or in CEL.
• You want a minimal, copy-pasteable example for a new language binding.
• You are bringing up a framework that is not in the cookbook set (Gemini CLI, GPT custom tool callers, bespoke in-house runtimes, etc.).

In this setup:

• Your code owns the LLM, the loop, and the stop condition.
• CEL provides cel_see, cel_act, cel_perceive, cel_think over stdio MCP. cel_act returns receipts.
• You call tools using the standard MCP client API for your language.

Setup

1. Build CEL

cd /path/to/cellar
pnpm install && pnpm -r build

2. Install an MCP SDK

Node.js:

pnpm add @modelcontextprotocol/sdk

Python:

pip install mcp

3. Grant macOS Accessibility permission

The process that spawns CEL (your script) will need Accessibility permission in System Settings → Privacy & Security → Accessibility. Easiest is to grant it to the terminal / Node / Python binary used to run your script.

Minimal Example (Node.js, ~40 lines)

A minimal client that spawns CEL, lists tools, and executes one task: open Numbers, write "BTC" into A1, read it back.

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["/absolute/path/to/cellar/mcp-server/dist/index.js"],
});

const client = new Client({ name: "cel-reference-client", version: "0.1.0" }, { capabilities: {} });
await client.connect(transport);

// 1. Confirm CEL's tools are exposed.
const tools = await client.listTools();
console.log("CEL tools:", tools.tools.map((t) => t.name));
// → cel_see, cel_act, cel_perceive, cel_think

// 2. See the current screen.
const ctx = await client.callTool({
  name: "cel_see",
  arguments: { mode: "context" },
});
console.log("Elements:", JSON.parse(ctx.content[0].text).elements.length);

// 3. Write a value into Numbers A1 via the Numbers adapter.
const write = await client.callTool({
  name: "cel_act",
  arguments: {
    action: "write_cells",
    app: "Numbers",
    writes: [{ cell_ref: "A1", value: "BTC" }],
    verify: true,
  },
});
const writePayload = JSON.parse(write.content[0].text);
console.log("write receipt:", writePayload.receipt.id, writePayload.receipt.dispatch_path);

// 4. Read it back deterministically.
const read = await client.callTool({
  name: "cel_act",
  arguments: { action: "read_cells", app: "Numbers", cell_refs: ["A1"] },
});
const readPayload = JSON.parse(read.content[0].text);
console.log("A1 =", readPayload.result);

await client.close();