Uxxu MCP

uxxu-mcp is a local MCP server for Uxxu. It lets chat clients inspect Uxxu projects and create or update C4 diagrams through the existing Uxxu backend API.

It is designed for chat-first clients such as Codex, Claude Code, and OpenClaw.

What It Does

• lists projects in an organization
• reads project context before generation
• reads existing diagrams
• creates C4 system context, container, component, and deployment diagrams
• lays out full diagrams automatically before import
• chooses relationship connectors automatically
• matches element technologies against the Uxxu technology catalog

The main high-level tool is:

• uxxu_create_c4_diagram

Installation

Run Without Installing

npx -y uxxu-mcp

Install Globally

npm install -g uxxu-mcp
uxxu-mcp

Install Globally From This Repo

If you want to use npm before the public package publish is finalized:

cd /Users/guillermo/Development/HelveticForce/cfive/mcp
npm install -g .
uxxu-mcp

Run From This Repo

cd /Users/guillermo/Development/HelveticForce/cfive/mcp
npm start

Environment

The server loads mcp/.env automatically when it runs from this repo. These values can also be provided as shell environment variables:

• UXXU_API_URL Optional. Defaults to https://app.uxxu.io.
• UXXU_API_KEY Preferred for MCP and automation. Sends Authorization: ApiKey <key>.
• UXXU_API_TOKEN Optional fallback. Used only when UXXU_API_KEY is not provided.
• UXXU_USER_ID Optional. If omitted, the server tries to extract userId from the JWT payload.

Backward compatibility is still supported for:

• CFIVE_API_URL
• CFIVE_API_KEY
• CFIVE_API_TOKEN
• CFIVE_USER_ID

Example:

UXXU_API_KEY=your-api-key-here
# Optional fallback:
# UXXU_API_TOKEN=your-jwt-token-here

Client Setup

Codex

{
  "mcpServers": {
    "uxxu": {
      "command": "npx",
      "args": ["-y", "uxxu-mcp"],
      "env": {
        "UXXU_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

If you are working from this repo, you can also use:

cd /Users/guillermo/Development/HelveticForce/cfive/mcp
npm install -g .
./register-codex-mcp.sh

Claude Code

Claude Code supports local stdio MCP servers.

This repo now includes a project-scoped config at .mcp.json, so if you open this repository in Claude Code it should detect the uxxu MCP server and ask you to approve it.

That project config uses the local repo entrypoint:

{
  "mcpServers": {
    "uxxu": {
      "type": "stdio",
      "command": "node",
      "args": ["./mcp/src/index.js"],
      "env": {
        "UXXU_API_URL": "${UXXU_API_URL:-https://app.uxxu.io}",
        "UXXU_API_KEY": "${UXXU_API_KEY}"
      }
    }
  }
}

If you prefer registering it explicitly in Claude Code, use:

cd /Users/guillermo/Development/HelveticForce/cfive/mcp
export UXXU_API_KEY=your-api-key
npm install -g .
./register-claude-mcp.sh

Or use the Claude CLI directly:

claude mcp add --transport stdio uxxu --scope local \
  --env UXXU_API_URL=https://app.uxxu.io \
  --env UXXU_API_KEY=YOUR_API_KEY \
  -- node /Users/guillermo/Development/HelveticForce/cfive/mcp/src/index.js

You can verify it with:

claude mcp list
claude mcp get uxxu

OpenClaw

The easiest OpenClaw flow is:

npm install -g uxxu-mcp
export UXXU_API_KEY=YOUR_API_KEY
uxxu-install-openclaw

That installer:

• registers the uxxu MCP server with OpenClaw
• installs the bundled uxxu-mcp-diagrams skill into ~/.openclaw/skills

If you are working from this repo before public publish is finalized:

cd /Users/guillermo/Development/HelveticForce/cfive/mcp
npm install -g .
export UXXU_API_KEY=YOUR_API_KEY
./register-openclaw-mcp.sh

You can verify it with:

openclaw mcp show uxxu

Tool Overview

Project Tools

• uxxu_list_projects
• uxxu_get_project
• uxxu_create_project
• uxxu_update_project

Project Context Tools

• uxxu_get_project_object_model
• uxxu_get_project_context

Diagram Tools

• uxxu_list_diagrams
• uxxu_get_diagram
• uxxu_create_diagram
• uxxu_update_diagram

Diagram Content Tools

• uxxu_add_diagram_content
• uxxu_update_diagram_elements
• uxxu_update_diagram_links

High-Level C4 Tool

• uxxu_create_c4_diagram

Recommended Chat Flow

When using Codex, Claude, or OpenClaw, the best sequence is:

1. uxxu_list_projects
2. uxxu_get_project_context
3. optionally uxxu_get_diagram
4. uxxu_create_c4_diagram

That gives the model enough context to create diagrams without guessing.

High-Level C4 Input

uxxu_create_c4_diagram accepts:

• diagramType: SYSTEM_CONTEXT, CONTAINER, COMPONENT, or numeric ids
• elements: objects with
  • key
  • type: ACTOR, SYSTEM, APPLICATION, STORE, COMPONENT, GROUP, or NOTE
  • name
  • optional description, technology, external, parentKey, x, y, w, h
• relationships: objects with
  • from
  • to
  • optional note, fromConnector, toConnector, position
• autoLayout: optional boolean, defaults to true

The server creates the diagram first, then converts the model into the existing backend element and link payloads.

Diagram-oriented responses include:

• viewerUrl
• layout metadata
• technology sync metadata

Registry Publishing

uxxu-mcp is now prepared for the official MCP Registry path.

Included in this repo:

• mcp/package.json with mcpName
• mcp/server.json
• .github/workflows/publish-uxxu-mcp-registry.yml

Local checks:

cd /Users/guillermo/Development/HelveticForce/cfive/mcp
npm run registry:check

Manual local publish to the official MCP Registry:

cd /Users/guillermo/Development/HelveticForce/cfive/mcp
mcp-publisher login github
npm run registry:publish

Automated publish:

• publish the npm package successfully
• add NPM_TOKEN to the GitHub repository secrets
• push a tag like uxxu-mcp-v0.1.2

The GitHub Actions workflow will:

1. publish the npm package
2. authenticate to the official MCP Registry using GitHub OIDC
3. publish server.json

Registry coverage notes are tracked in:

• REGISTRIES.md

Exact Release Flow

For the current release:

cd /Users/guillermo/Development/HelveticForce/cfive/mcp
npm run release:check
export NPM_TOKEN=your-publish-token
./publish-npm.sh

Then publish the official MCP Registry metadata:

cd /Users/guillermo/Development/HelveticForce/cfive/mcp
mcp-publisher login github
npm run registry:publish

If you want GitHub Actions to handle the official path on the repo side, push this tag from the repository root:

cd /Users/guillermo/Development/HelveticForce/cfive
git tag uxxu-mcp-v0.1.2
git push origin uxxu-mcp-v0.1.2

Example Prompt

In the Uxxu project "Architecture Demo", create a C4 container diagram for an e-commerce platform with a web app, mobile apps, API gateway, order service, payment service, PostgreSQL databases, Kafka, Stripe, Auth0, and SendGrid.

The model should:

1. find the project
2. inspect project context if needed
3. call uxxu_create_c4_diagram

Publishing Checklist

Before publishing to npm:

1. bump the version in package.json
2. verify the README install snippets
3. confirm UXXU_API_* environment handling
4. test npx -y uxxu-mcp
5. inspect the package contents with:

npm run pack:dry-run

6. publish with:

export NPM_TOKEN=your-npm-token
npm run publish:npm

If you prefer, you can also run the helper directly:

export NPM_TOKEN=your-npm-token
./publish-npm.sh

If your npm account enforces publish 2FA and your token does not bypass it, provide the one-time password too:

export NPM_TOKEN=your-npm-token
export NPM_OTP=123456
./publish-npm.sh

Backward Compatibility

• the server still accepts older cfive_* tool names
• new integrations should use the uxxu_* names

Scope

This MCP is intentionally deterministic. It does not run its own LLM. The chat client provides the reasoning, and the MCP provides the Uxxu operations.