Skip to main content
Glama
deenesjakoruzh
arrivets

Arkiv MCP Server

by arrivets
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

Arkiv MCP 服务器

一个 模型上下文协议 (MCP) 服务器，向 AI 代理和应用程序公开 Arkiv 数据库链查询功能。

快速入门

1. 构建

cd arkiv-mcp
npm install
npm run build

2. 添加到 Claude Code

在 arkiv-mcp 目录下运行此命令：

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

或者手动添加到 ~/.claude/settings.json：

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

对于 Claude Desktop，将相同的代码块添加到 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows)。

3. 查询 Kaolin 测试网

连接后，即可使用 query_entities 工具。示例提示词：

  • "查询 Arkiv 上的所有实体"

  • "查找 Arkiv 中所有 type = "post" 且 score > 10 的实体"

  • "显示 Arkiv 测试网上由 0x1234... 拥有的实体"

  • "获取匹配 status = "active" 的前 5 个实体，然后进行分页"

Related MCP server: TextQL MCP Server

功能特性

  • 使用类似 SQL 的过滤表达式查询 Arkiv 数据库链中的实体

  • 完整的 arkiv_query 语法：比较、逻辑运算符、Glob 匹配、合成属性

  • 支持带游标的分页

  • 可配置的返回字段（属性、元数据、负载）

  • 默认连接到 Kaolin 测试网

安装

cd arkiv-mcp
npm install
npm run build

# Or use tsx for development
npm run dev

使用方法

启动服务器

# 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

环境变量

变量

描述

是否必须

ARKIV_NODE_URL

Arkiv 节点 RPC URL

否（默认为 Kaolin 测试网）

命令行选项

选项

描述

默认值

--node-url <url>

Arkiv 节点 RPC URL

Kaolin 测试网

--help, -h

显示帮助

-

MCP 工具

query_entities

查询 Arkiv 数据库链中的实体。

参数

参数

类型

描述

默认值

filter

string

过滤表达式（见下文语法）

$all

limit

number

返回实体的最大数量（最大 200）

-

cursor

string

来自上一次响应的分页游标

-

withAttributes

boolean

在结果中包含属性

true

withMetadata

boolean

在结果中包含元数据（所有者、创建者、过期时间）

true

withPayload

boolean

在结果中包含负载（Base64 编码）

true

validAtBlock

number

查询特定区块高度的状态

-

过滤语法

filter 参数使用 arkiv_query 表达式语言：

运算符

描述

示例

=

相等

status = "active"

!=

不相等

status != "deleted"

>, >=, <, <=

数值范围

score > 100

&&

逻辑与

type = "post" && score > 50

||

逻辑或

status = "active" || status = "pending"

!

取反

!(status = "deleted")

~

Glob 匹配

name ~ "test*"

!~

取反 Glob 匹配

name !~ "draft*"

合成属性（以 $ 为前缀）：

属性

描述

$all

匹配所有实体

$owner

当前所有者地址

$creator

原始创建者地址（不可变）

$key

实体键

过滤示例

# 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")

响应格式

{
  "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
}

通过将返回的 cursor 作为下一次调用的 cursor 参数传入来进行分页。当 cursor 为空时，表示没有更多结果。

开发

服务器使用：

项目结构

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

许可证

MIT

Available Tools

1 tool
query_entitiesA

Query entities from an Arkiv database chain using a filter expression. The filter uses a SQL-like syntax: comparisons (=, !=, <, >, <=, >=), logical operators (&& and ||), negation (!), and glob matching (~). Special attributes: $all (match everything), $owner (current owner address), $creator (original creator address, immutable), $key (entity key). Examples: '$all', 'status = "active"', 'score > 100', 'project = "myapp" && status = "active"', '$owner = "0x1234..."', 'name ~ "test*"'

ParametersJSON Schema
NameRequiredDescriptionDefault
filterNoFilter expression. Defaults to "$all" if omitted. Examples: 'status = "active"', 'score > 100 && type = "post"', '$owner = "0xAbc..."', '$creator = "0xDef..."', 'name ~ "prefix*"'
limitNoMaximum number of entities to return (max 200)
cursorNoPagination cursor returned by a previous query
withAttributesNoInclude attributes in results (default: true)
withMetadataNoInclude metadata (owner, creator, expiry) in results (default: true)
withPayloadNoInclude payload in results as base64 (default: true)
validAtBlockNoQuery state at a specific block number

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It explains the filter syntax and special attributes but does not disclose performance implications, rate limits, or confirm that it is read-only. Schema covers some aspects (e.g., limit), but behavioral context is lacking.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured paragraph that front-loads the core purpose, then details the filter syntax, special attributes, and examples. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description does not explain return values explicitly, but the tool name and parameters imply entities with requested fields. Pagination cursor is mentioned in schema but not explained in description. Overall, it is fairly complete for a query tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds meaningful context for the 'filter' parameter by detailing the syntax and special attributes ($all, $owner, etc.), which goes beyond the schema. Other parameters are not enhanced, but the main parameter benefits significantly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool queries entities from an Arkiv database chain using a filter expression, with specific SQL-like syntax and special attributes. It is a specific verb-resource pair, and there are no sibling tools to distinguish against.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides examples and syntax details that imply when to use the tool, but does not explicitly state when not to use or mention alternatives. Since there are no sibling tools, the lack of exclusion is less critical.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.0.0
    • First observedquery_entities
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 1 tool

Disambiguation5/5

Only one tool exists, so there is no risk of confusion between tools. Perfect disambiguation.

Naming Consistency5/5

With a single tool, there are no naming inconsistencies. The name 'query_entities' follows a clear verb_noun pattern.

Tool Count1/5

A single tool is insufficient for a database server; even if it's query-only, missing CRUD operations severely limits functionality. Extreme mismatch.

Completeness2/5

The server only offers query functionality, omitting essential operations like create, update, or delete. Significant gaps for typical database interaction.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers