Agione MCP

This package exposes Agione admin operations as MCP tools.

Structure

• src/index.ts: aggregate entrypoint. Register all feature modules here.
• src/menu/index.ts: menu-only compatibility entrypoint.
• src/core/*: reusable runtime code shared by every module.
  • env.ts: env file loading, runtime config, masked context output.
  • http.ts: authenticated JSON requests, token refresh, API URL building.
  • server.ts: MCP stdio server wiring and module dispatch.
  • response.ts: common MCP text responses, error formatting, write confirmation guard.
• src/modules/<domain>/*: domain modules such as menu, later role or user.
  • types.ts: domain DTOs and backend response shapes.
  • schemas.ts: zod input validation and JSON schemas exposed to MCP clients.
  • service.ts: backend API calls and domain workflows.
  • tools.ts: MCP tool definitions and tool handlers.
  • index.ts: exports a ToolModule.

Adding A Module

Create src/modules/role or src/modules/user with the same file shape as menu, export a ToolModule, then add it to modules in src/index.ts.

Keep cross-domain behavior in src/core. Keep backend endpoint details and workflow rules inside the owning domain module.

Menu Identity

Read helpers such as menu_resolve, menu_get, and menu_export_json can use path, but path can be duplicated. Write tools intentionally reject path selectors and only accept menuId or permissionMenuId.

{
  "selector": {
    "by": "menuId",
    "value": "123456",
    "appId": "metis"
  }
}

The menu module resolves selectors into a normalized identity containing both menuId and permissionMenuId. Tools that need menuId or permissionMenuId choose the correct backend id internally, which avoids model confusion between those two fields.

Token Refresh Cache

When an access token expires, the client refreshes it with AGIONE_REFRESH_TOKEN and AGIONE_BASIC_AUTH or AGIONE_OAUTH2_PASSWORD_CLIENT. Refreshed access and refresh tokens are cached under ~/.agione-mcp/<profile>.tokens.json by default, scoped to the configured profile and API base. Override this with AGIONE_TOKEN_CACHE_FILE, or set AGIONE_TOKEN_CACHE_DISABLED=true to disable local token caching.