Skip to content

MCP_EXAMPLES.md

Latest commit

 

History

History
548 lines (392 loc) · 13.1 KB

MCP_EXAMPLES.md

File metadata and controls

548 lines (392 loc) · 13.1 KB
Raw

HoloScript MCP Tools — Examples

MCP endpoint (shared/public tools — inline compile/parse, HoloMesh board, knowledge, protocol): https://mcp.holoscript.net/mcp MCP endpoint (filesystem/codebase tools — absorb, graph status/queries, semantic search, compile/parse/validate of local files): http://127.0.0.1:7411/mcp — the sovereign local MCP (R.027). Start it with node packages/mcp-server/dist/http-server.js (PORT=7411); always-on Jetson anchor: http://192.168.0.119:7411/mcp. The remote server cannot see your local paths, so the "Understand a codebase (Absorb)" section below must run against a local endpoint. Transport: HTTP (the SSE GET entry is not served — a 2026-07-06 probe returned 409 JSON; POST JSON-RPC over HTTP is the supported transport) Auth: None required for tool calls (tools enforce their own auth where needed)

This doc shows MCP tool calls organized by what you're trying to do. For REST endpoints, see REST_EXAMPLES.md.

Connect your agent

{
  "mcpServers": {
    "holoscript": {
      "url": "https://mcp.holoscript.net/mcp",
      "transport": "http"
    }
  }
}

Every tool below is available once connected. Call via tools/call:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "TOOL_NAME",
    "arguments": { ... }
  }
}

Parse, compile, and render

Parse .holo source

{ "name": "parse_hs", "arguments": { "code": "object Cube { position: [0,1,0] }" } }

Returns AST with objects, traits, imports, and diagnostics.

Compile to any target

{ "name": "compile_to_r3f", "arguments": { "code": "object Cube { @grabbable position: [0,1,0] }" } }
{ "name": "compile_to_unity", "arguments": { "code": "object Cube { @physics_body position: [0,1,0] }" } }
{ "name": "compile_to_webgpu", "arguments": { "code": "object Mesh { @wireframe vertices: [...] }" } }

Compile targets change with the deployed server. Discover the current compile_to_* tools with tools/list, or verify the deployed count from https://mcp.holoscript.net/health.

Validate a composition

{ "name": "validate_composition", "arguments": { "code": "object Orb { @glowing @physics_body }" } }

Compose traits onto an object

{
  "name": "holoscript_compose_traits",
  "arguments": { "objectType": "cube", "traits": ["grabbable", "physics_body", "glowing"] }
}

Import a glTF model

{ "name": "import_gltf", "arguments": { "url": "https://example.com/model.glb" } }

Understand a codebase (Absorb)

Check if graph is loaded

Always do this first — if the graph is stale, scan before querying.

{ "name": "holo_graph_status", "arguments": {} }

Scan a codebase into a knowledge graph

{ "name": "holo_absorb_repo", "arguments": { "directory": ".", "force": false } }

force: false uses cache (~21ms). force: true does a full re-scan (~3-10s).

Ask a question (Graph RAG)

{
  "name": "holo_ask_codebase",
  "arguments": {
    "question": "How does the compilation pipeline work from .holo source to target output?",
    "llmProvider": "anthropic",
    "topK": 30
  }
}

Returns a cited answer with file:line references. See the absorb-service README for maintained example questions.

Semantic search

{ "name": "holo_semantic_search", "arguments": { "query": "authentication handler", "topK": 10 } }
{ "name": "holo_semantic_search", "arguments": { "query": "compiler", "type": "class" } }
{ "name": "holo_semantic_search", "arguments": { "query": "shader", "file": "snn-webgpu" } }

Query the graph directly

{ "name": "holo_query_codebase", "arguments": { "query": "callers", "symbol": "CompilerBase" } }
{ "name": "holo_query_codebase", "arguments": { "query": "callees", "symbol": "resolveRequestingAgent" } }
{ "name": "holo_query_codebase", "arguments": { "query": "imports", "symbol": "auth-utils" } }
{ "name": "holo_query_codebase", "arguments": { "query": "communities" } }
{ "name": "holo_query_codebase", "arguments": { "query": "stats" } }

Impact analysis

{
  "name": "holo_impact_analysis",
  "arguments": { "files": ["packages/core/src/compilers/CompilerBase.ts"] }
}

Returns all transitively affected files — use before refactoring.

Detect drift

{ "name": "holo_detect_drift", "arguments": {} }

Fast content-hash check without re-scanning.

Team coordination (HoloMesh)

Read the task board

{ "name": "holomesh_board_list", "arguments": {} }

Read the done log

{ "name": "holomesh_board_done_log", "arguments": { "team_id": "team_abc123", "limit": 10, "offset": 0 } }

Claim a task

{ "name": "holomesh_board_claim", "arguments": { "taskId": "task_abc123" } }

Complete a task

{
  "name": "holomesh_board_complete",
  "arguments": { "taskId": "task_abc123", "summary": "Fixed the auth bug", "commit": "abc123" }
}

Add a task to the board

{
  "name": "holomesh_board_add",
  "arguments": { "title": "Fix SSE transport on Railway", "priority": "high", "tags": ["infra"] }
}

Send heartbeat

{ "name": "holomesh_heartbeat", "arguments": {} }

Call every 60 seconds to stay visible to the team.

Set team mode

{ "name": "holomesh_mode_set", "arguments": { "mode": "build", "objective": "Ship v6.2" } }

Modes: audit (fix bugs), build (ship features), research (synthesize knowledge), review (quality gate).

Scout for tasks (AI-powered)

{ "name": "holomesh_scout", "arguments": { "context": "Looking for security-related work" } }

Share knowledge

Contribute wisdom/pattern/gotcha

{
  "name": "holomesh_contribute",
  "arguments": {
    "type": "wisdom",
    "content": "CompilerBase RBAC mock is required in all compiler tests",
    "domain": "testing"
  }
}

Types: wisdom (things that work), pattern (reusable approaches), gotcha (things that bite you).

Query team knowledge

{ "name": "holomesh_knowledge_read", "arguments": {} }

Query the knowledge store (orchestrator)

{ "name": "holo_query_wisdom", "arguments": { "search": "railway deployment", "limit": 5 } }

Oracle consultation

{
  "name": "holo_oracle_consult",
  "arguments": { "question": "Should I use a branch or commit to main?" }
}

Publishing & protocol

Publish a composition

{
  "name": "holo_protocol_publish",
  "arguments": {
    "code": "object Orb { @glowing @interactive position: [0,2,0] }",
    "author": "my-agent",
    "license": "cc-by-4.0"
  }
}

Look up a published composition

{ "name": "holo_protocol_lookup", "arguments": { "contentHash": "sha256..." } }

Collect (mint) a composition

{ "name": "holo_protocol_collect", "arguments": { "contentHash": "sha256...", "quantity": 1 } }

Preview revenue distribution

{ "name": "holo_protocol_revenue", "arguments": { "contentHash": "sha256..." } }

IDE support

Autocomplete

{
  "name": "hs_autocomplete",
  "arguments": { "code": "object Cube { @", "position": { "line": 1, "character": 17 } }
}

Hover info

{
  "name": "hs_hover",
  "arguments": { "code": "object Cube { @grabbable }", "position": { "line": 1, "character": 15 } }
}

Diagnostics

{ "name": "hs_diagnostics", "arguments": { "code": "object Cube { position: invalid }" } }

Go to definition

{ "name": "hs_go_to_definition", "arguments": { "symbol": "CompilerBase" } }

Find references

{ "name": "hs_find_references", "arguments": { "symbol": "grabbable" } }

Self-improvement

Diagnose code health

{ "name": "holoscript_code_health", "arguments": {} }

Read a file

{ "name": "holo_read_file", "arguments": { "path": "packages/core/src/compilers/CompilerBase.ts" } }

Edit a file

{
  "name": "holo_edit_file",
  "arguments": { "path": "src/index.ts", "search": "old code", "replace": "new code" }
}

Verify before commit

{ "name": "holo_verify_before_commit", "arguments": {} }

Git commit

{
  "name": "holo_git_commit",
  "arguments": {
    "message": "fix(core): resolve trait composition conflict",
    "files": ["src/traits/resolver.ts"]
  }
}

Simulation

Simulation tools are developer-facing. Supply explicit meshes, materials, loads, constraints, units, and validation evidence before treating a result as engineering or scientific support.

Structural FEA solver

{ "name": "solve_structural", "arguments": { "mesh": "...", "constraints": "...", "loads": "..." } }

Thermal solver

{ "name": "solve_thermal", "arguments": { "mesh": "...", "boundaryConditions": "..." } }

Observability

Query traces

{ "name": "query_traces", "arguments": { "service": "mcp-server", "limit": 10 } }

Get Prometheus metrics

{ "name": "get_metrics_prometheus", "arguments": {} }

Export traces (OTLP)

{ "name": "export_traces_otlp", "arguments": { "endpoint": "http://localhost:4318" } }

Economy

Check agent budget

{ "name": "check_agent_budget", "arguments": {} }

Get creator earnings

{ "name": "get_creator_earnings", "arguments": {} }

Get usage summary

{ "name": "get_usage_summary", "arguments": {} }

MCP client config generation

Write MCP client connection config once in .holo, then compile the same mcpServers connection entries to any IDE format. This target does not emit an MCP server manifest with tools, input schemas, or resources.

Compile to Claude config

{
  "name": "compile_to_mcp_config",
  "arguments": {
    "code": "mcp_servers { server holoscript { @connector(holoscript, transport: \"http\") url: \"https://mcp.holoscript.net/mcp\" @env(HOLOSCRIPT_API_KEY, header: \"Authorization: Bearer\") } }",
    "target": "claude"
  }
}

Returns ~/.mcp/config.json format with ${HOLOSCRIPT_API_KEY} interpolation.

Compile to Antigravity/Gemini config (literal keys)

{
  "name": "compile_to_mcp_config",
  "arguments": {
    "code": "mcp_servers { server holoscript { @connector(holoscript, transport: \"http\") url: \"https://mcp.holoscript.net/mcp\" @env(HOLOSCRIPT_API_KEY, header: \"Authorization: Bearer\") } }",
    "target": "antigravity",
    "envValues": { "HOLOSCRIPT_API_KEY": "your-actual-key-here" }
  }
}

Returns .gemini/antigravity/mcp_config.json format with literal key values injected (Antigravity doesn't interpolate ${VAR}).

Available targets

Target Output format Credential handling
claude ~/.mcp/config.json ${VAR} interpolation
vscode .vscode/mcp.json ${env:VAR} syntax
cursor .cursor/mcp.json ${VAR} interpolation
antigravity .gemini/.../mcp_config.json Literal key injection
generic mcp.json ${VAR} default

Full .holo example

mcp_servers {
  server holoscript_remote {
    @connector(holoscript, transport: "http")
    url: "https://mcp.holoscript.net/mcp"
    @env(HOLOSCRIPT_API_KEY, header: "Authorization: Bearer")
    description: "HoloScript MCP — compile, parse, team board"
  }

  server orchestrator {
    @connector(orchestrator, transport: "http")
    url: "https://mcp-orchestrator-production-45f9.up.railway.app/mcp"
    @env(HOLOSCRIPT_API_KEY, header: "x-mcp-api-key")
    description: "Tool discovery, knowledge federation"
  }

  server brave_search {
    @connector(brave, transport: "stdio")
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-brave-search"]
    @env(BRAVE_API_KEY)
  }

  server holoscript_local {
    @connector(holoscript, transport: "stdio")
    command: "node"
    args: ["scripts/holoscript-mcp-stdio.mjs"]
    cwd: "C:/Users/Josep/Documents/GitHub/HoloScript"
    @env(HOLOSCRIPT_API_KEY)
  }
}

Tool discovery

List all available tools

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

Find tools for a goal

{ "name": "suggest_tools_for_goal", "arguments": { "goal": "I want to deploy my scene to VR" } }

Get the full tool manifest

{ "name": "get_tool_manifest", "arguments": {} }

Tips

  • Always holo_graph_status before absorb queries — if stale, call holo_absorb_repo first
  • Omit llmProvider for holo_ask_codebase — the default synthesis path is HoloLlama; pass a cloud provider only as explicit BYOK opt-in
  • Heartbeat every 60s — holomesh_heartbeat keeps you visible on the team board
  • Compile targets are separate tools — compile_to_r3f, not compile({ target: "r3f" })
  • Knowledge types matter — wisdom = what works, pattern = reusable approach, gotcha = what bites you
  • Tool inventory is live — use suggest_tools_for_goal, tools/list, or the relevant /health endpoint instead of copying a tool count