Servidor MCP de Arkiv

Un servidor de Model Context Protocol (MCP) que expone las capacidades de consulta de la cadena de bases de datos de Arkiv a agentes y aplicaciones de IA.

Inicio rápido

1. Compilar

cd arkiv-mcp
npm install
npm run build

2. Añadir a Claude Code

Ejecuta esto desde el directorio arkiv-mcp:

claude mcp add arkiv -- node $(pwd)/dist/index.js

O añádelo manualmente a ~/.claude/settings.json:

{
  "mcpServers": {
    "arkiv": {
      "command": "node",
      "args": ["/absolute/path/to/arkiv-mcp/dist/index.js"]
    }
  }
}

Para Claude Desktop, añade el mismo bloque a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows).

3. Consultar la red de pruebas (testnet) de Kaolin

Una vez conectado, la herramienta query_entities estará disponible. Ejemplos de prompts:

• "Query all entities on Arkiv"

• "Find all Arkiv entities where type = "post" and score > 10"

• "Show me entities owned by 0x1234... on the Arkiv testnet"

• "Get the first 5 entities matching status = "active", then paginate"

Related MCP server: TextQL MCP Server

Características

• Consulta entidades de las cadenas de bases de datos de Arkiv usando una expresión de filtro similar a SQL

• Sintaxis completa de arkiv_query: comparaciones, operadores lógicos, coincidencia de glob, atributos sintéticos

• Soporte de paginación con cursor

• Campos de retorno configurables (atributos, metadatos, carga útil)

• Predeterminado a la red de pruebas de Kaolin

Instalación

cd arkiv-mcp
npm install
npm run build

# Or use tsx for development
npm run dev

Uso

Iniciar el servidor

# Using default Kaolin testnet
npm start

# With custom node URL
npm start -- --node-url https://your-arkiv-node.rpc

# Or with tsx for development
npm run dev -- --node-url https://your-arkiv-node.rpc

Variables de entorno

Opciones de línea de comandos

Herramienta MCP

query_entities

Consulta entidades de una cadena de base de datos de Arkiv.

Parámetros

Sintaxis de filtro

El parámetro filter utiliza el lenguaje de expresión arkiv_query:

Atributos sintéticos (prefijados con $) :

Ejemplos de filtros

# All entities
$all

# By entity key
$key = "0xabc123..."

# By owner or creator
$owner = "0x1234567890abcdef..."
$creator = "0x1234567890abcdef..."

# Attribute equality
status = "active"
type = "post"

# Numeric range
score > 100
price >= 50 && price <= 200

# Compound
project = "myapp" && type = "post" && score > 10

# Glob matching
name ~ "draft*"
!(status = "deleted")

Formato de respuesta

{
  "entities": [
    {
      "key": "0x...",
      "owner": "0x...",
      "creator": "0x...",
      "createdAtBlock": "12345",
      "lastModifiedAtBlock": "12350",
      "expiresAtBlock": "99999",
      "contentType": "application/json",
      "payload": "<base64-encoded bytes>",
      "attributes": [
        { "key": "type", "value": "post" },
        { "key": "score", "value": 42 }
      ]
    }
  ],
  "cursor": "0x2a",
  "blockNumber": "12350",
  "count": 1
}

Pagina pasando el cursor devuelto como el parámetro cursor en la siguiente llamada. Cuando el cursor está ausente, no hay más resultados.

Desarrollo

El servidor utiliza:

• @arkiv-network/sdk — SDK de TypeScript de Arkiv

• @modelcontextprotocol/sdk — SDK del servidor MCP

Estructura del proyecto

arkiv-mcp/
├── src/
│   └── index.ts          # Main server implementation
├── package.json
├── tsconfig.json
└── README.md

Licencia

MIT