mzizi-sdk

The Mzizi SDK. Under the hood it's an AI agent — Fundi.

Fundi is the agent identity. The SDK is the package consumers install. When a consumer's tool calls createFundi(), the SDK spawns Fundi to:

1. Read Mzizi's skills + guidelines (bundled mzizi-skills + live mzizi-mcp server).
2. Explore the consumer's project to discover what's already wired (globals.css, mdx-components.tsx, harness wiring, tokens…).
3. Plan and apply the missing pieces — tokens, primitives, brand components, MDX styling, harness, resilience, etc.

It reasons about each project's state and acts within the Mzizi doctrine.

CLI

The package ships a thin CLI (fundi) over the agent. The SDK stays env-agnostic; the CLI is the layer that reads env and wires it into FundiOptions.

fundi --help                              # usage + all commands
fundi explore                             # snapshot the project (offline, no key)
fundi plan "add the Mzizi token layer"    # dry-run plan (needs ANTHROPIC_API_KEY)
fundi chat "what is the nyuchi palette?"  # one-shot chat (needs ANTHROPIC_API_KEY)

Env: ANTHROPIC_API_KEY (required for plan/chat), MZIZI_MCP_URL (default https://mcp.mzizi.dev), MZIZI_MODEL (default claude-sonnet-4-6).

Status

Scaffold. Public types and createFundi() are stubbed; the agent loop, tool registry, and planner are next.

Install (when published)

npm install mzizi-sdk

Usage (when implemented)

import { createFundi } from "mzizi-sdk"

const fundi = await createFundi({
  anthropicApiKey: process.env.ANTHROPIC_API_KEY!,
})

// Future:
// await fundi.explore()
// const plan = await fundi.plan({ goal: "set up Mzizi tokens" })
// await plan.apply()

Auth

mzizi-sdk integrates with WorkOS AuthKit. Outbound calls to mzizi-mcp and the upcoming Fundi worker are gated by a WorkOS access token; the SDK resolves that token from one of three places, in order:

1. options.auth.accessToken — explicit token wins. Use this when your host app already drove a WorkOS flow and has the token in hand.
2. process.env.WORKOS_ACCESS_TOKEN — the canonical env var.
3. process.env.MZIZI_AUTH_TOKEN — ecosystem-wide alias, shared with the Fundi worker and other Mzizi tooling so a single env var can power the whole toolchain.

When requireAuth: true is passed (recommended in production wiring), a missing token throws an AuthError at construction time. With the default requireAuth: false, the SDK stays usable for local exploration — the identity getter just returns null.

import { createFundi, getIdentity, type Identity } from "mzizi-sdk"

// Library-consumer flow: token already in hand
const fundi = await createFundi({
  anthropicApiKey: process.env.ANTHROPIC_API_KEY!,
  auth: { accessToken: myWorkOsAccessToken },
  requireAuth: true,
})

console.log(fundi.identity?.email)        // -> "[email protected]"
console.log(fundi.identity?.permissions)  // -> ["mzizi:read", "fundi:plan"]

// CLI / first-run flow: env-var fallback
process.env.WORKOS_ACCESS_TOKEN = "ey..."  // set by your shell / dotenv
const fundi2 = await createFundi({ anthropicApiKey: "..." })

// Standalone helper for callers that just want to decode an access token:
const identity: Identity = getIdentity(myWorkOsAccessToken)

Identity mirrors WorkOS's AccessToken claims:

interface Identity {
  sub: string              // WorkOS user id
  email?: string
  organizationId?: string
  permissions: string[]
  exp: number              // expiry, seconds since epoch
}

The SDK uses jose.decodeJwt to read claims — it does not verify the signature. Signature verification is the job of the resource server (mzizi-mcp, the Fundi worker, etc.). The SDK does enforce exp, so an expired token raises AuthError immediately.

License

Apache-2.0.