🌟 AstroVisor MCP Server (OpenAPI Synced)

AstroVisor MCP server that syncs to the AstroVisor OpenAPI schema.

That means when the backend adds new systems/endpoints, this MCP server picks them up automatically (no manual tool mapping).

Install

npm install astrovisor-mcp

Claude Desktop Config

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "astrovisor": {
      "command": "npx",
      "args": ["astrovisor-mcp"],
      "env": {
        "ASTROVISOR_API_KEY": "pk-...",
        "ASTROVISOR_URL": "https://astrovisor.io"
      }
    }
  }
}

Environment Variables

• ASTROVISOR_API_KEY (required): your AstroVisor API key
• ASTROVISOR_URL (optional): API base URL (default: https://astrovisor.io)
• ASTROVISOR_OPENAPI_URL (optional): override OpenAPI URL (default: ${ASTROVISOR_URL}/openapi.json)
• ASTROVISOR_TOOL_MODE (optional): compact (default) or full
• ASTROVISOR_RESPONSE_VIEW (optional): default response serialization view (summary, compact, full; default compact)
• ASTROVISOR_DEFAULT_TOKEN_BUDGET (optional): default max serialized response size in bytes when request does not specify response.tokenBudget (default 250000)
• ASTROVISOR_RESULT_TTL_MS (optional): in-memory result cache TTL (default 1800000)
• ASTROVISOR_RESULT_MAX_ENTRIES (optional): max cached results (default 128)

Tool Mode

Compact (default)

Claude Desktop has a limited context window. Sending hundreds of tool definitions can cause:

• Context size exceeds the limit
• tool definition validation errors

So the default mode exposes a tiny toolset:

• astrovisor_openapi_search (find operationIds)
• astrovisor_openapi_list (get endpoint list with filters/pagination)
• astrovisor_openapi_get (inspect one operation)
• astrovisor_conventions (global interop conventions for any LLM client)
• astrovisor_request (call any operation by operationId with serialization controls)
• astrovisor_result_get (load stored full response by resultId and request only needed fragment)

Search also supports common Russian keywords mapping (for example таро -> tarot, ленорман -> lenormand).

Full (advanced)

Set ASTROVISOR_TOOL_MODE=full to generate one MCP tool per OpenAPI operationId.

Note: this can be too large for Claude Desktop depending on your schema size.

Full mode also accepts legacy aliases in tool calls (for better compatibility with non-Claude clients), for example:

• short operation aliases (calculate_current_transits)
• old verb variants (create_* <-> calculate_*)
• names with or without astrovisor_ prefix

Calling The API (Compact Mode)

1. Find the operation you want:

{
  "q": "gene keys",
  "limit": 10
}

Or list all Tarot endpoints directly:

{
  "pathPrefix": "/api/tarot",
  "limit": 200
}

1. Call it by operationId:

{
  "operationId": "SomeOperationId",
  "path": { "paramName": "..." },
  "query": { "q": "..." },
  "body": { "any": "json" },
  "response": {
    "view": "compact",
    "responsePath": "data.items",
    "responseOffset": 0,
    "responseLimit": 20,
    "select": ["id", "date", "strength", "system", "theme"],
    "where": {
      "strength_gte": 0.75,
      "theme_contains": "career"
    },
    "sort": ["-strength", "date"],
    "include": ["items", "meta"],
    "exclude": ["items.0.debug"],
    "maxItems": 50,
    "tokenBudget": 120000,
    "store": true
  }
}

• path: values for URL templates like /api/users/{user_id}
• query: URL query string parameters
• body: JSON request body for POST/PUT/PATCH (object preferred; valid JSON string is auto-parsed)
• body field profiles are auto-normalized across common aliases:
  • core profile: datetime/latitude/longitude/location/timezone
  • birth profile: birth_datetime/birth_latitude/birth_longitude/birth_location/birth_timezone
• response: output shaping for token efficiency

Use astrovisor_openapi_get before calling an operation. It now returns:

• requestBodySchema
• aliases
• llmHints with:
  • requiredBodyFields
  • exampleBody
  • quick parameter instructions

Every astrovisor_request response includes metadata and, by default, resultId. Use it to fetch only what you need later:

{
  "resultId": "abc123...",
  "response": {
    "responsePath": "data.items",
    "cursor": "eyJvZmZzZXQiOjEwMH0",
    "responseLimit": 20,
    "select": ["id", "date", "strength", "system"],
    "where": { "strength_gte": 0.8 },
    "sort": "-strength",
    "view": "compact"
  }
}

Precision Retrieval (Universal For All LLMs)

Large AstroVisor payloads are now handled with a consistent envelope:

• format: serialization version marker (astrovisor.serialized.v2)
• meta.query.totalBefore/totalMatched/offset/limit/nextCursor
• meta.availablePaths: discoverable paths for targeted follow-up reads
• summary.source + summary.selected: shape before/after query shaping
• data: token-optimized result chunk

response supports both flat and nested (response.query) selectors:

• responsePath: select subtree first
• select: field projection
• where: filtering with operator suffixes
• sort: deterministic ordering (-field for desc)
• cursor / responseOffset / responseLimit: pagination
• tokenBudget: auto-compact output under byte budget

Compatibility notes:

• responsePath/responseOffset/responseLimit are accepted both at response.* and response.query.*
• where accepts either:
  • object form: { "tension_score_gte": 19.8 }
  • clause array form: [{"path":"tension_score","op":"gte","value":19.8}]
• always check meta.pathFound; if false, your responsePath is wrong.

Supported where suffix operators:

• _eq, _ne, _gt, _gte, _lt, _lte
• _in, _nin
• _contains, _startswith, _endswith
• _exists, _regex

Universal LLM Prompt

Use this prompt for any AI client (Claude, ChatGPT, Gemini, Perplexity, etc.) to work with AstroVisor MCP reliably:

You are an MCP integration assistant for AstroVisor. Work deterministically, minimize token usage, and never guess endpoint shapes.

Goal:
- Resolve user intent to the correct AstroVisor API operation.
- Execute calls via MCP reliably.
- Handle very large responses (especially transits) without context overflow.

Rules:
1. Always start with tools discovery (tools/list) and adapt to available tools.
2. If present, call astrovisor_conventions first and follow it.
3. In compact mode, always resolve operations in this order:
   - astrovisor_openapi_search or astrovisor_openapi_list
   - astrovisor_openapi_get
   - astrovisor_request
4. Never call an operation before reading astrovisor_openapi_get output.
5. Build request body from llmHints.requiredBodyFields and llmHints.exampleBody.
6. Prefer exact required field names. If only alias fields are available, still send them (MCP may normalize), then report normalization.
7. For large responses, default to compact retrieval:
   - view: "compact"
   - store: true
   - tokenBudget: 12000 (or lower if needed)
8. For targeted extraction, use:
   - response.query.responsePath (or responsePath)
   - query.select
   - query.where
   - query.sort
   - query.limit / query.cursor
9. Always inspect metadata:
   - If meta.pathFound=false, stop and retry with a valid path from meta.availablePaths.
   - If meta.truncated=true, continue via astrovisor_result_get with tighter selectors.
10. For transit/yearly analytics, do not pull raw full timeline first:
    - first summary/statistics
    - then paged timeline windows with filters
11. If operation/tool name is unknown, retry with aliases from openapi_get.aliases or search/list again.
12. If an API error occurs, report exact status + message and propose one minimal corrective call.

Default compact call template:
{
  "operationId": "<from openapi_get>",
  "body": { "<required fields only>": "..." },
  "response": {
    "view": "compact",
    "query": {
      "responsePath": "<target path>",
      "select": ["<field1>", "<field2>"],
      "where": { "<field_op>": "<value>" },
      "sort": ["-<field>"],
      "limit": 20
    },
    "tokenBudget": 12000,
    "store": true
  }
}

Result follow-up template:
{
  "resultId": "<meta.resultId>",
  "response": {
    "view": "compact",
    "query": {
      "responsePath": "<narrower path>",
      "cursor": "<meta.query.nextCursor>",
      "select": ["<fields>"],
      "where": { "<field_op>": "<value>" },
      "limit": 20
    },
    "tokenBudget": 12000
  }
}

Output policy:
- Be concise and factual.
- Show what was called, what matched, and why.
- Never claim "endpoint does not exist" before openapi_list/openapi_search verification.

Local Smoke Test

ASTROVISOR_URL=https://astrovisor.io npm test

Notes

• The server fetches OpenAPI once at startup and generates the tool list from it.
• You need a valid dashboard-generated API key (pk-...) to call most /api/... endpoints.