Documentació

Integració MCP

El servidor MCP (Model Context Protocol) permet que models d’IA com Claude interactuïn amb Asset Core mitjançant la crida d’eines a través de JSON-RPC.

Requisits previs

  • Daemons d’Asset Core en funcionament (escriptura i lectura)
  • Eina de Rust per construir el servidor MCP
  • Client compatible amb MCP (Claude Desktop, etc.)

Pas 1 - Construir el servidor MCP

Des del repositori d’Asset Core:

cargo build --release --bin mcp-server

El binari es troba a target/release/mcp-server.

Pas 2 - Configurar les URL dels daemons

El servidor MCP es connecta als teus daemons d’Asset Core. Configura a través de variables d’entorn:

export ASSETCORE_WRITE_URL=http://localhost:8080
export ASSETCORE_READ_URL=http://localhost:8081

Els valors per defecte són localhost:8080 (escriptura) i localhost:8081 (lectura).

Pas 3 - Trieu el transport

El servidor MCP admet dos transports:

STDIO (per defecte)

Per a la integració directa amb Claude Desktop i clients similars:

./target/release/mcp-server

El servidor llegeix sol·licituds JSON-RPC des de stdin i escriu respostes a stdout.

SSE (Server-Sent Events)

Per a les integracions basades en web:

MCP_TRANSPORT=sse MCP_PORT=9000 ./target/release/mcp-server
VariableDescripció
MCP_TRANSPORTstdio (per defecte) o sse
MCP_PORTPort d’escolta SSE (requerit per SSE)

Pas 4 - Prova la connexió

Llista d’eines disponibles:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | ./target/release/mcp-server

Comproveu la salut del daemon d’escriptura:

echo '{"jsonrpc":"2.0","id":2,"method":"assetcore_write_health"}' | ./target/release/mcp-server

Pas 5 - Enviar una transacció

Creeu un contenidor a través del servidor MCP:

Orientació addicional:

echo '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "assetcore_commit",
  "params": {
    "operations": [
      {
        "op": "CreateContainer",
        "args": {
          "container_id": 1001,
          "kind": "Standard",
          "owner": null
        }
      }
    ],
    "idempotency_key": "mcp-create-1001"
  }
}' | ./target/release/mcp-server

La resposta inclou el resultat del commit amb números de seqüència.

Pas 6 - Configurar Claude Desktop

Afegiu el servidor MCP a la vostra configuració de Claude Desktop:

{
  "mcpServers": {
    "assetcore": {
      "command": "/path/to/mcp-server",
      "env": {
        "ASSETCORE_WRITE_URL": "http://localhost:8080",
        "ASSETCORE_READ_URL": "http://localhost:8081"
      }
    }
  }
}

Claude ara pot utilitzar les eines d’Asset Core en les converses.

Resolució de problemes

Errors de “Connexió refusada”

Els daemons no s’estan executant o les URL són incorrectes. Verifiqueu:

curl http://localhost:8080/v1/health
curl http://localhost:8081/v1/health

Errors “JSON-RPC no vàlid”

Assegureu-vos que cada sol·licitud sigui un JSON vàlid en una sola línia. El protocol MCP utilitza JSON delimitat per nova línia.

Eina no trobada

El nom del mètode ha de coincidir exactament. Eines disponibles:

  • tools/list
  • assetcore_commit
  • assetcore_write_health
  • assetcore_read_health
  • assetcore_read_freshness

Utilitzant acctl

També podeu llançar el servidor MCP a través de acctl:

acctl adapters --transport stdio

Això utilitza la descoberta de configuració i respecta les variables d’entorn ASSETCORE_*.

Properes passes