AIsuru reporting MCP (@memori.ai/aisuru-reporting-mcp)

Read-only stdio MCP for AIsuru tenant limits, snapshots, and monthly consumption reporting. Built for the AIsuru MCP Gateway (npx -y @memori.ai/aisuru-reporting-mcp) and desktop clients (Claude, Cursor, LM Studio, Claude Code).

Based on the company aisuru-mcp-template: TypeScript, Bun for development, Node ≥24 / npx for Gateway, T3 Env + Zod, secrets only from environment.

Tools

| Tool | Purpose | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | aisuru_get_monthly_report | Full monthly record: limits, snapshot, reconstructed month-end counts, historical usage. One tenant or a paginated pass over all tenants. | | aisuru_get_monthly_usage | Historical usage only (chats, AI completions, imported pages). | | aisuru_get_tenant_snapshot | Live limits, add-ons, generative-AI flag, current admin/user/agent counts. | | aisuru_get_tenant_details | Full tenant configuration (credentials redacted) + optional month-end reconstruction. | | aisuru_list_tenants | Search/list platforms by customer name, short name, or domain. | | aisuru_calculate_pages | floor(characters / 3000) helper. Prefer reports that already include pages. |

Semantics worth remembering

• Month boundaries are UTC (YYYY-MM → compact [from, to) dates).
• Limit 0 means unlimited. Pages from characters: floor(n / 3000).
• snapshot = current API counts; monthEndCounts = reconstructed from objects that still exist + creationTimestamp (deleted objects cannot be recovered).
• Deep Thought / non-chargeable counters stay separate — do not assume they are additive with aiMessagesSent.

Requirements

| Use | Tooling | | -------------------------------------------- | -------------------------------------------------------------------------- | | Development (install, test, lint, build) | Bun ≥ 1.2 — package manager + local runtime | | Production (AIsuru Gateway) | Node ≥ 24 via npx -y @memori.ai/aisuru-reporting-mcp (required) | | Production (optional) | node build/cli.js or bun run build/cli.js / bunx … if you prefer |

Source must stay Node-compatible (tsc → build/, no Bun-only APIs in src/) so Gateway npx keeps working.

Quick start

bun install
bun run build
bun run test          # unit + in-memory MCP (no network)
bun run dev           # build + stdio (needs AISURU_* env)

# or manually:
bun run build/cli.js
# Node-compatible smoke (same artifact Gateway uses):
node build/cli.js

Commit bun.lock. npm install is optional for consumers who prefer npm.

Environment

Validated at process start by @t3-oss/env-core + Zod (src/lib/env.ts). Bad/missing required vars → clear stderr error and exit.

| Variable | Required | Default | Description | | --------------------------- | -------- | ------- | -------------------------------------------- | | AISURU_BACKEND_BASE_URL | yes | — | Backend API base (…/api/v2) | | AISURU_TRUSTED_APP_TOKEN | yes | — | Trusted App token (Gateway encrypts at rest) | | AISURU_LOGIN_TENANT | yes | — | Auth tenant for the service account | | AISURU_LOGIN_EMAIL | yes | — | Service account email | | AISURU_LOGIN_NAME | yes | — | Service account username | | AISURU_TIMEOUT_MS | no | 30000 | HTTP timeout (100–120000) | | AISURU_REPORT_CONCURRENCY | no | 4 | Parallelism for multi-tenant reports (1–10) |

Gateway maps each schema parameter to an env var of the same name. Never put tokens in tool arguments — only in Gateway parameters / client env.

AIsuru MCP Gateway — register a schema

Admin UI → MCP schemas (or seed via mcp_server_schemas.rake in the gateway repo).

| Field | Example | | ------------- | ----------------------------------------------- | | Schema id | aisuru-reporting-mcp | | Name | AIsuru reporting | | server_type | generic | | Command | npx -y @memori.ai/aisuru-reporting-mcp | | Node | Gateway must have Node ≥24 (engines.node) |

Gateway always uses npx + Node. Local Claude/Cursor configs may use bunx instead of npx if Bun is installed (see Client configs).

This MCP authenticates (Trusted App + service account) before the stdio handshake. If Gateway Fetch Tools only shows help / status, cold start may be too short — coordinate a longer spawn sleep for this package name (same class of issue as Solid).

Prompt lista

MCP read-only per rendicontazione tenant AIsuru: limiti, snapshot e consumi mensili.

Prompt esegui

Per una rendicontazione usa aisuru_get_monthly_report con mese YYYY-MM; non serve chiamare prima gli altri tool se il tenant è noto.
I report includono già le pagine calcolate; usa aisuru_calculate_pages solo per valori grezzi in caratteri.
Se il nome è incerto usa aisuru_list_tenants; per tutta la configurazione usa aisuru_get_tenant_details.
snapshot = conteggi API attuali; monthEndCounts ricostruisce admin/utenti/agenti a fine mese; usage = consumi storici.
Limite 0 = illimitato. Pagine = floor(caratteri / 3000). Non sommare aiMessagesSent con Deep Thought o non addebitabili.
Non richiedere mai token all’utente: sono nell’ambiente del server.

Parametri (JSON)

[
  {
    "name": "AISURU_BACKEND_BASE_URL",
    "type": "string",
    "required": true,
    "description_it": "Base URL API backend AIsuru (…/api/v2)",
    "description_en": "AIsuru backend API base URL (…/api/v2)"
  },
  {
    "name": "AISURU_TRUSTED_APP_TOKEN",
    "type": "password",
    "required": true,
    "description_it": "Trusted App token",
    "description_en": "Trusted App token"
  },
  {
    "name": "AISURU_LOGIN_TENANT",
    "type": "string",
    "required": true,
    "description_it": "Tenant di autenticazione del service account",
    "description_en": "Auth tenant for the service account"
  },
  {
    "name": "AISURU_LOGIN_EMAIL",
    "type": "string",
    "required": true,
    "description_it": "Email del service account",
    "description_en": "Service account email"
  },
  {
    "name": "AISURU_LOGIN_NAME",
    "type": "string",
    "required": true,
    "description_it": "Username del service account",
    "description_en": "Service account username"
  },
  {
    "name": "AISURU_TIMEOUT_MS",
    "type": "number",
    "required": false,
    "default": "30000",
    "description_it": "Timeout HTTP in ms",
    "description_en": "HTTP timeout in ms"
  },
  {
    "name": "AISURU_REPORT_CONCURRENCY",
    "type": "number",
    "required": false,
    "default": "4",
    "description_it": "Parallelismo report multi-tenant",
    "description_en": "Concurrency for multi-tenant reports"
  }
]

Secrets: use the Gateway type that encrypts at rest (password for AISURU_TRUSTED_APP_TOKEN). Never put secrets in tool arguments.

Gateway rake (optional)

Mirror Solid: add entries in mcp-aisuru-gateway → lib/tasks/mcp_server_schemas.rake + mcp_server_info.rake (prompt_lista / prompt_esegui, bilingual description).

After deploy: Fetch Tools must show the six aisuru_* names (not only help / status).

Client configs

This package is stdio. Full host-specific reference: docs/MCP_CLIENTS.md.

| Placeholder | Meaning | | --------------------------------- | ----------------------------------- | | @memori.ai/aisuru-reporting-mcp | npm package | | aisuru-reporting | short client id | | AISURU_* | env vars from the Environment table | | /ABSOLUTE/PATH/TO/repo | local clone (dev without publish) |

Claude Desktop (claude_desktop_config.json)

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Published package (npx — recommended for prod / Gateway parity):

{
  "mcpServers": {
    "aisuru-reporting": {
      "command": "npx",
      "args": ["-y", "@memori.ai/aisuru-reporting-mcp"],
      "env": {
        "AISURU_BACKEND_BASE_URL": "<BACKEND_API_BASE_URL>",
        "AISURU_TRUSTED_APP_TOKEN": "<TRUSTED_APP_TOKEN>",
        "AISURU_LOGIN_TENANT": "<AUTH_TENANT>",
        "AISURU_LOGIN_EMAIL": "<SERVICE_ACCOUNT_EMAIL>",
        "AISURU_LOGIN_NAME": "<SERVICE_ACCOUNT_NAME>"
      }
    }
  }
}

Published package (bunx — if the host has Bun):

{
  "mcpServers": {
    "aisuru-reporting": {
      "command": "bunx",
      "args": ["@memori.ai/aisuru-reporting-mcp"],
      "env": {
        "AISURU_BACKEND_BASE_URL": "<BACKEND_API_BASE_URL>",
        "AISURU_TRUSTED_APP_TOKEN": "<TRUSTED_APP_TOKEN>",
        "AISURU_LOGIN_TENANT": "<AUTH_TENANT>",
        "AISURU_LOGIN_EMAIL": "<SERVICE_ACCOUNT_EMAIL>",
        "AISURU_LOGIN_NAME": "<SERVICE_ACCOUNT_NAME>"
      }
    }
  }
}

Local clone (Bun or Node):

{
  "mcpServers": {
    "aisuru-reporting": {
      "command": "bun",
      "args": ["/ABSOLUTE/PATH/TO/repo/build/cli.js"],
      "env": {
        "AISURU_BACKEND_BASE_URL": "<BACKEND_API_BASE_URL>",
        "AISURU_TRUSTED_APP_TOKEN": "<TRUSTED_APP_TOKEN>",
        "AISURU_LOGIN_TENANT": "<AUTH_TENANT>",
        "AISURU_LOGIN_EMAIL": "<SERVICE_ACCOUNT_EMAIL>",
        "AISURU_LOGIN_NAME": "<SERVICE_ACCOUNT_NAME>"
      }
    }
  }
}

(command: node works the same with the same args.) Fully quit and reopen Claude after editing.

Cursor / LM Studio (mcp.json)

Same Cursor-style mcpServers object (LM Studio: Program → Install → Edit mcp.json → ~/.lmstudio/mcp.json). Use npx for Gateway parity, or bunx / local bun as above.

Claude Code

claude mcp add aisuru-reporting -- npx -y @memori.ai/aisuru-reporting-mcp
# or: claude mcp add aisuru-reporting -- bunx @memori.ai/aisuru-reporting-mcp

Then set the AISURU_* env vars in the generated config.

Development

bun install
bun run build
bun run test              # Vitest: unit + mocked MCP (CI)
bun run test:live         # real backend; needs AISURU_* + AISURU_SMOKE_TENANT
bun run test:live:all     # same + AISURU_SMOKE_ALL_TENANTS=1 (every tenant)
bun run lint
bun run format
bun run release           # conventional commits → CHANGELOG (configure npm publish)

Equivalents with npm work if you prefer (npm run build, etc.), but Bun is the team default.

| Suite | Command | Network | | -------------------- | ----------------------- | ---------- | | Unit + in-memory MCP | bun run test | no | | Live API + stdio MCP | bun run test:live | yes | | Live all tenants | bun run test:live:all | yes (slow) |

Live tests also accept optional AISURU_SMOKE_MONTH (YYYY-MM, default previous UTC month).

Server tests use @modelcontextprotocol/sdk InMemoryTransport (same pattern as Solid / the template). See test/server.test.ts and test/mcp-test-utils.ts.

Hooks: lefthook + commitlint (conventional commits) via bunx.

CI: GitHub Actions (.github/workflows/check.yml) — Bun lint / typecheck / test / format / build + Node CLI smoke.

Layout

| Path | Role | | -------------------------- | ----------------------------------------------- | | src/cli.ts | Stdio entry (bin) — Gateway spawn target | | src/server.ts | Tool registration | | src/lib/env.ts | T3 Env + Zod (env, zEnvBool, zEnvInt) | | src/lib/aisuru-client.ts | Backend HTTP client | | src/lib/reporting.ts | Domain logic (pages, aggregates, month-end) | | src/lib/tools.ts | toolText / toolJson / toolError envelopes | | src/lib/limits.ts | Output truncation helpers | | AGENTS.md | Instructions for humans & coding agents | | docs/MCP_CLIENTS.md | Gateway / Claude / Cursor / LM Studio snippets | | test/*.test.ts | Default Vitest suite | | test/live/*.test.ts | Optional live suite |