Skip to main content
Glama
openmaxai

claude-openmax

by openmaxai
OverviewSchemaRelated ServersScoreDiscussions
JavaScript

claude-openmax

The Claude Code runtime adapter for OpenMax / CWS. A thin Category-B (bare runtime) adapter: it owns none of the CWS protocol — that all comes from @openmaxai/openmax-agent-sdk (CwsAgentBridge) — and does only the two runtime-specific translations plus capability exposure:

  1. Inbound — bring a workspace message into Claude Code's visible context via an experimental claude/channel MCP push (raft-channel-wake.v1).

  2. Outbound — send Claude's reply back to cws-core via the SDK's CommService.

  3. Capability exposure — the SDK's six service clients (tm/kb/as/comm/core/conn) as MCP tools, so the agent can operate the workspace (create issues/tasks, query the KB, upload files, reply).

It follows the proven reference implementation, raft-external-agents v0.3.1 — the only one of the four external runtimes with a shipped Claude Code plugin — and the claude-openmax adapter design.

Architecture

Layer 1  @openmaxai/openmax-agent-sdk  (CWS HTTP/WS contract only)
  CwsAgentBridge: per-org WS lifecycle · auth/heartbeat/reconnect · atomic dedupe
    · /sync + inbox-ledger · frame dispatch · access-policy · normalized InboundMessage
  services: tm / kb / as / comm / core / conn   (one CwsHttpClient)
  providers: StorageProvider · RuntimeStateProvider · InboundDelivery(★) · Logger
        ▲ import + inject
Layer 2  claude-openmax  (this repo)
  ┌ bridge host (Node) ────────────────┐        ┌ Claude Code (agent) ──────────┐
  │ new CwsAgentBridge({providers,cbs}) │        │ MCP `openmax` server:         │
  │  providers.inbound.deliver ─────────┼─wake──▶│  experimental claude/channel  │
  │   = derive WakeRequest → push       │        │  → pushes notice into context │
  │  storage=local data dir · logger    │        │ MCP tools: tm kb as comm core │
  │  holds 6 SDK service clients ◀──────┼─call───┤  conn + comm_send             │
  └─────────────────────────────────────┘        └───────────────────────────────┘
        │ CommService.send() / bridge.send() → cws-core
        ▼
     cws-core REST  ◀── cws-comm WS (inbound frames) ── COCO Workspace (user)

Topologies

  • In-process (MVP, default) — one Node process is both the stdio MCP server (claude/channel + tools) and the host of CwsAgentBridge. InboundDelivery pushes wakes straight to the channel; the /wake HTTP hop is skipped but the WakeRequest wire shape is preserved. Run: Claude Code loads the plugin.

  • Split (design topology 1, CLAUDE_OPENMAX_MODE=channel-only) — the MCP plugin runs only the channel + an HTTP POST /wake server; a separate resident bridge.js holds the WS and POSTs wakes. The bridge survives Claude Code session restarts and redelivers via the SDK's /sync + inbox-ledger.

Related MCP server: Slack MCP Server

The ok:true delivery invariant

The single most important rule (from the SDK's wake-result schema and CwsAgentBridge): ok:true MUST mean the message genuinely entered the runtime's visible context. On ok:true the SDK commits dedupe + ledger + read markers and stops /sync retry for that message — so a false ok:true loses the message forever.

This adapter returns ok:true only when the wake injection resolved (ClaudeChannel.notifyWake / POST /wake succeeded). Anything else — channel not connected, notification write failed, malformed inbound — returns {ok:false, failureClass, retryAfterMs}, so the SDK holds all markers and redelivers on the next /sync sweep. See src/inbound-delivery.js and its tests.

Files

File

Purpose

src/index.js

MCP channel plugin entrypoint (Claude Code loads this over stdio); default in-process bridge host.

src/bridge.js

Standalone resident bridge for the split topology; POSTs wakes over HTTP /wake.

src/channel.js

MCP Server declaring the experimental claude/channel capability; notifyWake pushes notifications/claude/channel.

src/wake.js

Pure raft-channel-wake.v1 derivation + validation + the human-visible wake notice/meta builders.

src/inbound-delivery.js

InboundDelivery.deliver() — derive WakeRequest, inject, gate ok:true.

src/notifier.js

Debounced wake coalescing (raft EAB-8): leading-edge inject + window merge.

src/wake-server.js

HTTP POST /wake server for the split topology (token-guarded).

src/mcp-tools.js

Wraps the six SDK service clients as MCP tools (one dispatch tool per service + comm_send).

src/config.js

Loads adapter config; builds CwsHttpClient + TokenManager + services; SDK callback seams (session/config/owner persistence).

src/create-bridge.js

Assembles CwsAgentBridge from the runtime + providers.

src/storage.js

File-backed StorageProvider under a local data dir (XDG); no ~/zylos coupling.

src/providers.js

stderr logger + empty RuntimeStateProvider (Cat.B degraded metrics).

.claude-plugin/plugin.json

Registers the openmax MCP server for Claude Code.

hooks/hooks.json + hooks/session-hook.js + hooks/orientation.js

SessionStart orientation injection (survives resume/compaction).

CLAUDE.md

Agent-facing instructions: how wakes arrive, how to read/reply, tool map.

test/*.test.js

node --test unit tests (frame derivation, ok:true gating, coalescing, tool dispatch, orientation).

Session / context management

Uses Claude Code's built-in autocompact (and /clear / /compact). This adapter implements no extra compression logic — by design.

Installation

Install as a Claude Code plugin from this repo's marketplace:

claude plugin marketplace add openmaxai/claude-openmax   # register the marketplace (once)
claude plugin install openmax-channel@openmax            # install the plugin

Claude Code fetches the plugin, installs it into its managed plugin directory, and keeps it updated — no manual git clone needed. Then create your config (see Configuration) and start Claude Code.

Experimental wake — one caveat. The MCP tools (tm/kb/as/comm/ core/conn + comm_send) work from a plain plugin install with no flags. The inbound wake (claude/channel, how workspace messages reach the agent) is still an experimental Claude Code capability and currently requires launching with the development-channels flag:

claude --dangerously-load-development-channels plugin:openmax-channel@openmax

Reference the plugin, not a bare server name. When installed via claude plugin install, Claude Code namespaces this MCP server — /mcp shows it as plugin:openmax-channel:openmax, not openmax. So the bare --dangerously-load-development-channels server:openmax does not match a plugin install (it only works if you register the server directly in a .mcp.json under the literal name openmax); use the plugin:…@… form above. If in doubt, run /mcp and reference the exact server name it prints. Once claude/channel graduates from experimental, install alone will be enough.

Running (from source / dev)

npm install                     # resolves @openmaxai/openmax-agent-sdk@alpha from npm
cp config.example.json ~/.config/claude-openmax/config.json   # fill in real values
npm test                        # node --test

Load into Claude Code as a plugin (dev):

claude plugin marketplace add --scope local /path/to/claude-openmax   # local checkout
# or point Claude Code at .claude-plugin/plugin.json directly

Build (maintainers)

The plugin ships a dependency-free bundle. Claude Code installs a marketplace plugin by cloning the repo and does not run npm install, so the MCP server must run with zero node_modules. scripts/build.js (esbuild) inlines every dependency into dist/index.mjs (the MCP server, referenced by .claude-plugin/plugin.json) and dist/bridge.mjs (the split-topology bridge).

npm run build     # rebuild dist/ after changing src/ or bumping a dependency

dist/ is committed (it is the shipped artifact); CI rebuilds it and fails if the committed bundle is stale, and smoke-tests that it loads with no node_modules.

Split topology (resident bridge + channel-only plugin):

# terminal A: Claude Code loads the plugin with
CLAUDE_OPENMAX_MODE=channel-only CLAUDE_OPENMAX_WAKE_PORT=47600 CLAUDE_OPENMAX_WAKE_TOKEN=... claude ...
# terminal B: resident bridge (config.wake.endpoint = http://127.0.0.1:47600/wake)
CLAUDE_OPENMAX_WAKE_TOKEN=... node src/bridge.js

Config / env

Config file at $CLAUDE_OPENMAX_CONFIG (or ~/.config/claude-openmax/config.json); see config.example.json. As of the config-parity refactor the on-disk shape is a 1:1 structural mirror of the OpenMax (zylos-openmax) component's config — see the migration note below. The shape:

enabled?: bool
server:  { bff_url, ws_url, frontend_base_path }        // frontend_base_path default "/workspace"
agent:   { identity_id, api_key, device_id, app_version }
cf_access: { client_id, client_secret }
orgs:    { "<org_id>": { enabled?, org_id, org_name?,
             owner: { member_id, name },
             self:  { member_id, name, display_name },
             access:{ dmPolicy, dmAllowFrom?, groupPolicy?, groups?:{ "<convId>": { mode, allowFrom } } } } }
wake:    { endpoint }                                   // claude-openmax ONLY (openmax has no wake)
metricsReport?: { dashboardApiKey }                     // RESERVED / forward-compat — inert (no reporter yet)
ws?:     { reconnectMaxMs?, heartbeatIntervalMs?, pingIntervalMs? }   // claude-openmax WS tuning knobs

Env fallbacks (map onto the nested fields): COCO_API_URL→server.bff_url, COCO_WS_URL→server.ws_url, COCO_FRONTEND_BASE_PATH→server.frontend_base_path, COCO_API_KEY→agent.api_key, COCO_DEVICE_ID→agent.device_id, COCO_CLIENT_VERSION→agent.app_version, COCO_ORG_ID→default org. Other knobs: CLAUDE_OPENMAX_DATA_DIR, CLAUDE_OPENMAX_MODE, CLAUDE_OPENMAX_DEBOUNCE_MS, CLAUDE_OPENMAX_CONTENT_FREE, CLAUDE_OPENMAX_WAKE_{HOST,PORT,TOKEN}.

orgs is keyed by org_id (openmax-style), end to end: the SDK orchestrator keys its per-org runtime records by org_id too, so the adapter hands it an org_id-keyed map directly — there is no separate per-org key to derive. Every self-healing write-back (self.member_id, self.name, owner bind) resolves the org by org_id and lands back in the org_id-keyed on-disk structure.

agent.identity_id is the agent's global identity. Leave it empty and the adapter resolves it from cws-core GET /me at startup and caches it back to config.json. It is the leadAgentId for the guided-autonomy flow (an Issue's Lead agent = the agent itself).

server.frontend_base_path is wired into the SDK's CwsHttpClient.frontendUrl() so the agent can build clickable workspace links (<bff_url><frontend_base_path>/…, default /workspace).

Migrating from the openmax (zylos-openmax) component

The claude-openmax config is now structurally identical to the openmax component's config.json — you can drop an openmax config in as-is. The only differences are additive and claude-openmax-specific:

  • wake.endpoint — required for the split-topology bridge; openmax has no wake block.

  • metricsReport — accepted for parity but inert (claude-openmax has no metrics reporter yet); it round-trips untouched.

  • ws — optional WS tuning knobs (reconnectMaxMs, heartbeatIntervalMs, pingIntervalMs) that openmax hardcodes; ws_url/device_id/app_version live under server.*/agent.*, NOT here.

The old claude-openmax shape (top-level http/auth + an array orgs) is still accepted: it is translated to the new shape on load with a one-time warning, so an existing live config won't break — but you should migrate it.

Session files auto-migrate. Per-org state (incl. the /sync cursor) is now keyed by org_id (sessions/<org_id>.json), where earlier builds used a derived slug (sessions/<slug>.json). On first load, if only a legacy sessions/<slug>.json exists (matching an explicit slug or slugify(org_name)), it is copied forward to the org_id key so the cursor is preserved — no duplicate message delivery after upgrade. The old file is left in place (harmless); no manual step is needed.

Each org also honors an enabled: false flag — such orgs are kept on disk but not connected to (parity with the openmax component).

Verified vs. spike (honesty ledger)

Verified locally (node --test + MCP client smoke):

  • WakeRequest derivation/validation, ok:true gating, coalescing, tool dispatch — 32 unit tests green.

  • The MCP server boots, advertises capabilities.experimental["claude/channel"], and lists all 7 tools to a real MCP client.

  • POST /wake (token-guarded) → server.notification({method:"notifications/claude/channel", ...}) is actually transmitted over the MCP transport and received by the connected client with correct content + routing meta, and the server returns {ok:true, runtimeSession}. server.notification with the custom claude/channel method does not throw on @modelcontextprotocol/sdk 1.22+.

⚠️ SPIKE — requires a live Claude Code to confirm (biggest technical uncertainty):

  1. claude/channel rendering. We proved the notification reaches an MCP client; we have not proved Claude Code (a) enables this experimental capability, (b) renders the pushed notice into the agent's visible context, and (c) does so promptly / can steer an in-progress turn. Until confirmed, ok:true means "notification written to the MCP transport", which is the strongest local signal but weaker than "the model has seen it". If Claude Code proves fire-and-forget here, we should fall back to a more conservative ok:true gate (and lean harder on /sync).

  2. runtimeSession binding. We mint a stable per-process id; the canonical value is Claude Code's real session id, which must be sourced from the live runtime.

  3. Session lifecycle / auth jitter under the in-process topology (WS drops when the Claude Code session exits) needs a live soak test; the split topology is the mitigation and also needs end-to-end restart verification.

  4. Tool budget. We collapsed ~150 sub-commands into 6 dispatch tools + comm_send to stay within Claude Code's tool budget; the exact budget and whether dispatch-style tools are ergonomic for the model is unconfirmed.

Boundaries

  • Consumes the SDK for all protocol/transport/sync/dedup/access-policy logic; reimplements none of it. Does not pass a custom callbacks.dedupe (uses the SDK's built-in atomic deduper).

  • No dependency on zylos-openmax; independent local data dir (no ~/zylos).

Available Tools

7 tools
asA

Artifact store: upload/download media, resolve artifact:// URIs, presigned URLs. method = a camelCase verb like uploadMedia, getMediaUrl, downloadMedia, resolveUris. Pass a FLAT params object as usual — the adapter maps it to the SDK's positional call shape for you (e.g. getMediaUrl(idOrUri, opts)); you do NOT need to construct positional args. Call with {"method":"","params":{...}}. Use {"method":"list"} for the FULL per-method purpose + field schema.

ParametersJSON Schema
NameRequiredDescriptionDefault
methodYescamelCase service method, or "list" to enumerate methods + their purpose/field schemas
paramsNoarguments object for the method (see the method schema from "list")

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It reveals the internal adapter pattern that maps flat params to SDK's positional calls, which is useful. However, it lacks details on side effects, authentication needs, or rate limits, which would help an agent anticipate behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is adequately structured but slightly verbose, especially the explanation of the adapter mapping. It front-loads the purpose and usage pattern, but each sentence could be tightened. A more concise version would improve scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a multi-method tool with no output schema, the description covers usage and internal mapping well. However, it omits return values or error handling, which would be necessary for completeness. The 'list' method partially compensates.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by specifying method values (camelCase verbs like uploadMedia, getMediaUrl) and explaining that params is a flat arguments object. It also guides users to 'list' for per-method schemas.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function as an artifact store for upload/download media, URI resolution, and presigned URLs, using verbs like uploadMedia, getMediaUrl, etc. It distinguishes itself from sibling tools (tm, comm, etc.) by its specific domain, though it could explicitly state 'not for communication or knowledge base operations'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage instructions: call with {"method":"<verb>","params":{...}} and use {"method":"list"} for full method schemas. It clarifies the adapter's mapping to avoid positional argument construction. However, it does not specify when not to use this tool or mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

commB

Communication: conversations, messages, history, mark-read, sync, DM access control. method = a camelCase verb like getMessages, getMessage, send, listConversations, createDm. Prefer the comm_send tool for replies. Call with {"method":"","params":{...}}. Use {"method":"list"} for the FULL per-method purpose + field schema. Common methods (*=required, ?=optional; — gloss names each verb's purpose; see "list" for the rest + full summaries): listConversations(cursor?, limit?, includeArchived?) — browse conversations; createDm(peerMemberId*) — open a DM; getMessages(conversationId*, afterSeq?, beforeSeq?, limit?) — history for context; getMessage(conversationId*, messageId*) — read one message; send(conversationId*, content*, replyTo?, clientMsgId?) — send msg (prefer comm_send)

ParametersJSON Schema
NameRequiredDescriptionDefault
methodYescamelCase service method, or "list" to enumerate methods + their purpose/field schemas
paramsNoarguments object for the method (see the method schema from "list")

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It explains that the tool dispatches methods and references sync, mark-read, and DM access control, but does not disclose side effects, permissions, rate limits, or error handling. Adequate but not detailed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is moderately concise, but the inline listing of methods (e.g., 'listConversations(cursor?, limit?, includeArchived?) — browse conversations') makes it a bit lengthy. The front-loading of the domain statement helps, but some sentences could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multiple methods) and no output schema, the description is somewhat incomplete regarding return values and error handling. However, the guidance to use 'list' for full method schemas partially compensates. Adequate for a meta-tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the two top-level parameters (method and params) with descriptions. The description adds value by explaining method values ('camelCase verb or "list"') and listing common methods with their parameter fields, which enriches the schema meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Communication: conversations, messages, history, mark-read, sync, DM access control,' which broadly covers the tool's domain but lacks a specific verb+resource. It lists methods like listConversations and send, and distinguishes comm_send for replies, so purpose is moderately clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly guides to 'Prefer the comm_send tool for replies,' clearly directing when to use a sibling. It also provides the invocation pattern ('Call with {"method":<verb>,"params":{...}}') and mentions using 'list' to enumerate methods, offering good usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

comm_sendA

Reply to / send a message into a conversation. Provide the endpoint from the wake notice (or a bare conversation id), the content text, and optionally replyTo (parent message id) and orgId.

ParametersJSON Schema
NameRequiredDescriptionDefault
orgIdNoorg to send as (optional; defaults to the single/default org)
contentYesmessage text (markdown auto-detected)
replyToNoparent message id to reply to (optional)
endpointYesconversation routing endpoint (conversationId[|reply:..][|thread:..])

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It only states what the tool does (send/reply) but fails to disclose behavioral traits such as side effects, permissions required, error handling, or what happens if the conversation doesn't exist. This is a significant gap for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently lists required and optional parameters. It front-loads the purpose. No wasted words, though a bit terse; could be slightly more structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description covers the basic functionality and parameter hints but lacks information about return values, error conditions, or prerequisites. It is adequate but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds value by clarifying the endpoint parameter ('from the wake notice or a bare conversation id'), which goes beyond the schema's description. This helps an AI agent understand how to obtain and format the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Reply to / send a message into a conversation', specifying a specific verb and resource. It also distinguishes key parameters, making the tool's purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides guidance on what to provide (endpoint, content, optional replyTo/orgId) but does not explicitly state when to use this tool versus alternatives or when not to use it. The sibling tools are listed but their purposes are not explained, missing an opportunity for differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

connC

Connection credentials: list/acquire/proxy connection credentials + local cache. method = a camelCase verb like list, acquire, proxy, status, cached. Call with {"method":"","params":{...}}. Use {"method":"list"} for the FULL per-method purpose + field schema. Common methods (*=required, ?=optional; — gloss names each verb's purpose; see "list" for the rest + full summaries): list(agentMemberId?) — list connections; acquire(connectionId*, agentMemberId?) — get credential; proxy(connectionId*, method?, url?, headers?, body?, agentMemberId?) — request via connection; status(connectionId*) — connection details

ParametersJSON Schema
NameRequiredDescriptionDefault
methodYescamelCase service method, or "list" to enumerate methods + their purpose/field schemas
paramsNoarguments object for the method (see the method schema from "list")

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behaviors. It mentions a 'local cache' but does not explain side effects, idempotency, error handling, or what happens with successive calls. For a multi-method tool, critical behavioral details are missing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is verbose and poorly structured, mixing inline method summaries with formatting notes and a long parenthetical that is hard to parse. It tries to be concise but achieves confusion, making it difficult for an agent to quickly understand the tool's interface.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multiple methods, nested params, no output schema), the description is incomplete. It defers essential details to a 'list' call and does not explain return values or error conditions. A new agent would struggle to use this tool correctly without additional information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers all parameters (method and params) with descriptions. The description adds value by listing method verbs and hinting that 'list' returns schemas for each method. However, it does not fully detail the parameters for each method, leaving the agent to rely on a separate 'list' call.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states that the tool handles connection credentials with multiple verbs (list, acquire, proxy, status, cached), providing some clarity on the domain. However, the purpose is muddled by overloading many operations into one tool, and the description relies on a 'list' method to fully explain each verb, making the overall purpose less immediate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the calling convention with method and params, and gives brief inline summaries for common methods. However, it provides no guidance on when to use this tool versus any of its siblings (as, tm, comm, kb, core, comm_send), nor does it exclude cases where alternatives are better.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

coreB

Directory/identity: me, member/agent/org/role/invitation directory, agent profiles, self rename, onboarding. method = a camelCase verb like me, memberList, agentProfiles, orgList, selfRename. Call with {"method":"","params":{...}}. Use {"method":"list"} for the FULL per-method purpose + field schema. Common methods (*=required, ?=optional; — gloss names each verb's purpose; see "list" for the rest + full summaries): me() — your own identity; memberList(kind?, status?, search?, page?, pageSize?, orderBy?) — find member ids; agentProfiles(projectId*, memberIds*, capabilities?, include?) — agent skills/capabilities; projectList(status?, page?, pageSize?, orderBy?) — browse projects; selfRename(name*) — rename yourself; orgList(orderBy?) — list your orgs

ParametersJSON Schema
NameRequiredDescriptionDefault
methodYescamelCase service method, or "list" to enumerate methods + their purpose/field schemas
paramsNoarguments object for the method (see the method schema from "list")

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It lists method signatures but does not disclose important behaviors such as authentication requirements, side effects (e.g., selfRename is mutable), rate limits, or error handling. The description is primarily a parameter listing, lacking behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with a clear purpose, but the rest is dense and includes a long parenthetical with formatting characters. It could be more concise and better structured (e.g., using bullet points) to improve readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multiple methods, nested params) and lack of annotations or output schema, the description is incomplete. It relies on a runtime 'list' method for full details, does not describe return values or error conditions, and omits some methods entirely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description significantly enriches the input schema by explaining that 'method' is a camelCase verb, listing all valid methods with their parameter signatures (e.g., memberList(kind?, status?, ...)), and instructing how to use params. This goes far beyond the bare schema, which only has generic descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Directory/identity:' and lists the main operations (me, memberList, agentProfiles, etc.), making the tool's purpose very clear and distinguishing it as the central identity/directory tool among siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus its siblings (as, tm, comm, etc.). It only details how to invoke methods within 'core', not when it is appropriate to choose this tool over alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

kbA

Knowledge base: KB collections, directory tree nodes, pages + content/revisions/trash, full-text search, file upload. method = a camelCase verb like create, pageCreate, pageContentWrite, search. Call with {"method":"","params":{...}}. Use {"method":"list"} for the FULL per-method purpose + field schema. Common methods (*=required, ?=optional; — gloss names each verb's purpose; see "list" for the rest + full summaries): list(limit?, offset?) — browse KBs; create(name*, visibility?, description?, icon?) — new KB (explicit only); treeRoots(kbId*) — KB root nodes; folderCreate(kbId*, name*, parentId?) — new folder node; pages(cursor?, limit?, offset?) — list pages; pageCreate(kbId*, title*, body*, format?, parentId?, message?) — new page; pageGet(pageId*) — page metadata; pageContent(pageId*) — read page body; pageContentWrite(pageId*, body*, message?, baseRevisionId?, autoSave?) — write page body; search(query*, kbId?, limit?, offset?, sort?) — full-text page search; upload(filePath*, parentId?, contentType?, filename?) — upload file to KB

ParametersJSON Schema
NameRequiredDescriptionDefault
methodYescamelCase service method, or "list" to enumerate methods + their purpose/field schemas
paramsNoarguments object for the method (see the method schema from "list")

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description implicitly distinguishes read vs write operations (e.g., 'pageGet' vs 'pageCreate') but does not explicitly state safety, side effects, or rate limits. Adequate but could be more explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Very efficient: overview sentence, then instruction to use 'list', then compact table of common methods with parameter syntax. Every sentence is informative, no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and complex inner methods, description covers discovery (use 'list') and common methods. Lacks explicit return value or error descriptions, but 'list' fills gaps. Mostly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage 100% on method and params. Description adds substantial meaning: explains method values (camelCase verbs, 'list'), and lists detailed parameters for each common method, far exceeding schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'knowledge base' operations including collections, pages, search, upload. Specific verbs like 'list', 'create', 'pageCreate' define purpose exactly. Distinguishes from siblings by being a multi-method API facade.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides detailed usage pattern: call with method and params, use 'list' to get full schemas. Lists common methods with required/optional parameters. Does not compare to sibling tools, but they are unrelated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tmA

Task management: projects, issues, tasks, blueprints, comments, attempts, event-bindings (cws-work via cws-core). method = a camelCase verb like projectCreate, issueCreate, taskCreate. Call with {"method":"","params":{...}}. Use {"method":"list"} for the FULL per-method purpose + field schema. Common methods (*=required, ?=optional; — gloss names each verb's purpose; see "list" for the rest + full summaries): projectList(status?, query?, page?, pageSize?, orderBy?) — browse projects; projectCreate(name*, leadMemberId*, description?, slug?, isDefault?, knowledgeBaseId?, memberIds?) — new project (explicit only); issueList(status?, statuses?, priority?, includeArchived?, query?, page?, pageSize?, orderBy?) — browse all issues; issueListInProject(projectId*, status?, statuses?, priority?, includeArchived?, query?, page?, pageSize?, orderBy?) — issues in one project; issueGet(id*) — read one issue; issueCreate(projectId*, title*, leadAgentId*, ownerMemberId*, description?, backlog?, priority?, originConversationId?, originMessageId?) — create issue w/ owner=acceptor; issueSubmitPlan(id*, blueprintId*, planText?, source?, cardMessageId?) — submit plan (needs blueprint); issueAcceptPlan(id*, source?) — owner accepts plan; issueDeliver(id*) — in_progress→delivered; issueAcceptDelivered(id*, source?) — owner accepts delivery; taskList(projectId?, issueId?, status?, includeArchived?, page?, pageSize?, orderBy?) — browse tasks; taskCreate(projectId*, issueId*, title*, description?, assigneeId?, blueprintStepId?, dependsOn?) — create task under issue; taskClaim(id*) — claim ownership (not start); taskStart(id*) — begin work, opens attempt; taskTransition(id*, status*) — task→terminal state; commentCreate(workType*, workId*, bodyMarkdown*) — comment on issue/task; blueprintCreate(issueId*, steps*, estimatedBudget?, notes?) — create plan skeleton; attemptTransition(id*, status*, failureReason?, blockedOnApprovalRequestIds?) — generic state-machine transition

ParametersJSON Schema
NameRequiredDescriptionDefault
methodYescamelCase service method, or "list" to enumerate methods + their purpose/field schemas
paramsNoarguments object for the method (see the method schema from "list")

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It lists many methods with their required/optional parameters, clearly indicating write operations (e.g., issueCreate) and read operations (e.g., issueList). It does not explicitly mention side effects, authentication, or rate limits, but the method names and parameter descriptions provide reasonable transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is quite long and dense, listing many methods inline. It front-loads the main purpose but then dumps a large block of method details. While this ensures completeness, it sacrifices conciseness and readability. A more structured format (e.g., bullet points or separate lines) would improve it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (many methods, nested params) and no output schema, the description is very complete. It covers all primary methods and their parameters, even providing a way to get full schema via 'list'. However, it lacks explicit descriptions of return values for each method, which would be needed for full completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers both parameters (method and params) with descriptions, achieving 100% coverage. The description adds significant value beyond the schema by enumerating possible method values and their specific parameter signatures, helping the agent understand what to pass in 'params'. The examples and method listing enhance parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool is for task management, listing specific entities (projects, issues, tasks, etc.). It provides a detailed breakdown of methods, making the purpose unmistakable. It distinguishes from sibling tools like 'as', 'comm', etc., by its domain-specific content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains how to call the tool (with method and params) and suggests using 'list' for full method details, but it does not provide explicit guidance on when to use this tool over sibling tools or alternatives. The context is clear but lacks exclusionary guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 7 tool updatesv1.1.2
    • First observedas
    • First observedcomm
    • First observedcomm_send
    • First observedconn
    • First observedcore
    • First observedkb
    • First observedtm
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3/5.0
Disambiguation2/5

Tools have overlapping purposes: comm and comm_send both handle sending messages, and core's projectList duplicates tm's projectList. This creates ambiguity for an agent.

Naming Consistency2/5

Tool names are inconsistent: some are short abbreviations (as, tm), others are full words (comm, core), and one uses an underscore (comm_send). No clear pattern.

Tool Count4/5

7 tools is reasonable for the breadth of services, though some consolidation could reduce overlap. Still within an acceptable range.

Completeness3/5

Covers major domains (artifacts, tasks, comm, KB, identity, connections) but has noticeable gaps like missing update/delete for many entities and a separate send tool that feels incomplete.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/openmaxai/claude-openmax'

If you have feedback or need assistance with the MCP directory API, please join our Discord server