convez.ai
MCP Server
Vivek1106-04

asterixdb-mcp-server

Vivek1106-04/asterixdb-mcp-server

Ver no GitHub
InicialPluginScore · de 0 a 100

Model Context Protocol gateway for Apache AsterixDB — read-only SQL++ over MCP

Instalação

$npx convez-ai Vivek1106-04/asterixdb-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
1
Saúde
57%
Último commit
há 3 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

AsterixDB MCP Server

A Model Context Protocol gateway for Apache AsterixDB. It lets an LLM agent discover datasets, inspect schemas (including ROW vs COLUMNAR storage), and run read-only SQL++ queries against a live AsterixDB cluster.

Architecture invariant

The gateway is a standalone sidecar. It never parses SQL++, never holds Cluster Controller (CC) state, and never runs a mutation deny-list. The CC's readonly=true parameter is the single authority on mutation rejection — the gateway hardcodes it on every query. This keeps the database control plane stateless with respect to LLM sessions.

LLM client  ──MCP (stdio)──▶  AsterixDB MCP Gateway  ──HTTP──▶  AsterixDB CC
                                (this repo)                     /query/service
                                                                /admin/*

Capabilities

19 tools, 11 resources, 6 prompts. Tools perform actions; resources expose read-only context a client can attach to a session; prompts are guided multi-step workflows.

Tools

GroupToolPurpose
Queryexecute_querySynchronous read-only SQL++ with offset/limit windowing.
Querysubmit_async_querySubmit a long-running query; returns a handle.
Querywait_on_async_queryLong-poll an async handle to completion.
Queryfetch_query_resultPage through a completed async result set.
Querycancel_queryCancel an in-flight async query.
Analyzevalidate_syntaxCompile-only syntax check, no execution.
Analyzeexplain_queryOptimizer plan for a statement.
Analyzecheck_index_usageWhether a query's predicates hit an index.
Discoverlist_dataversesEnumerate dataverses on the cluster.
Discoverlist_datasetsPaginated dataset discovery, optionally scoped to a dataverse.
Discoverdescribe_dataverseDatasets, types, indexes, and functions in one dataverse.
Discoverget_schemaSingle-dataset schema incl. datasetFormatInfo (ROW/COLUMNAR).
Discoversample_datasetA small bounded row sample from a dataset.
Discoversearch_metadataCross-metadata search for datasets/types/indexes/functions.
Functionslist_functionsBuilt-in / user-defined functions, filtered by language.
Functionsget_functionOne function's signature, with near-name hints on a miss.
Clusterget_cluster_statusLive cluster state and node roster.
Clusterget_node_detailsPer-node diagnostics for a validated node id.
Docsget_referenceSQL++ reference docs by topic.

Resources

URIPurpose
asterixdb://versionAsterixDB + gateway version; liveness probe.
asterixdb://cluster/statusLive cluster state from /admin/cluster.
asterixdb://cluster/diagnosticsAggregated per-node health diagnostics.
asterixdb://config-parametersEffective gateway egress/timeout settings.
asterixdb://dataversesDataverse inventory.
asterixdb://reference/sqlpp-syntaxSQL++ syntax rules.
asterixdb://reference/builtin-functionsBuilt-in function catalog.
asterixdb://reference/index-typesSupported index types.
asterixdb://reference/type-systemSQL++ / ADM type system.
asterixdb://reference/error-codesGateway error taxonomy.
asterixdb://reference/query-examplesWorked SQL++ examples.

Prompts

PromptPurpose
analyze_dataverseBootstraps exploration with inventory + safety rules.
build_aggregation_queryGuides building a GROUP BY / aggregation query.
analyze_query_performanceWalks plan + index analysis for a slow query.
recommend_indexesSuggests indexes from a query workload.
explore_nested_dataNavigates nested / ROW vs COLUMNAR structures.
explain_errorTurns a gateway/CC error into a fix.

Every query carries a namespaced client_context_id ({agentSessionId}::{userTag}::{uuid}) for end-to-end auditability, and is bounded by layered egress controls: a wall-clock timeout, a buffered-response byte ceiling, and row/byte caps on what reaches the LLM.

Requirements

  • Python 3.10+
  • A reachable AsterixDB cluster (default http://localhost:19002)

Install

git clone https://github.com/<your-fork>/asterixdb-mcp-server.git
cd asterixdb-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Configure

All settings come from environment variables (prefix ASTERIXDB_MCP_):

VariableDefaultMeaning
ASTERIXDB_MCP_CC_BASE_URLhttp://localhost:19002CC REST base URL.
ASTERIXDB_MCP_CC_SHARED_SECRET(unset)Optional X-Gateway-Secret header on the CC hop.
ASTERIXDB_MCP_AGENT_SESSION_IDlocal-sessionLeading segment of the namespaced context id.
ASTERIXDB_MCP_MAX_TIME_MS30000Egress layer 1: per-query wall-clock ceiling.
ASTERIXDB_MCP_MAX_BYTES_PER_QUERY10485760Egress layer 2: max response bytes buffered.
ASTERIXDB_MCP_REQUEST_TIMEOUT_S35.0httpx transport timeout for the CC hop.

Run

asterixdb-mcp-server        # serves MCP over stdio

Connect Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "asterixdb": {
      "command": "/absolute/path/to/.venv/bin/asterixdb-mcp-server",
      "env": { "ASTERIXDB_MCP_CC_BASE_URL": "http://localhost:19002" }
    }
  }
}

Any MCP client

The server speaks MCP over stdio, so any MCP-capable client works: launch the asterixdb-mcp-server console script as the server command and set ASTERIXDB_MCP_CC_BASE_URL to your cluster. The model behind the client is your choice — the gateway is model-agnostic and holds no provider keys.

Develop

ruff check src tests        # lint
ruff format src tests       # format
mypy                        # strict type-check
coverage run -m pytest      # unit + contract tests
coverage report             # enforces 100% line+branch coverage (fail_under=100)

Coverage policy: 100% line and branch coverage is required. It is enforced by fail_under = 100 in pyproject.toml, so coverage report exits non-zero below it.

Project layout

src/asterixdb_mcp/
  config.py          # env-driven settings
  context_id.py      # {session}::{tag}::{uuid} namespace transform
  errors.py          # error taxonomy + CC-error classification
  egress.py          # layered egress controls (timeout, byte ceiling, row caps)
  cc_client.py       # async CC REST client (readonly=true hardcoded)
  permits.py         # non-blocking concurrency permit pools
  statement_guard.py # pre-flight read-only statement guard
  plan_guard.py      # plan-layer mutation backstop
  server.py          # FastMCP binding (19 tools, 11 resources, 6 prompts)
  tools/             # one module per tool (SDK-agnostic cores)
  resources/         # live cluster resources + SQL++ reference docs
  prompts/           # guided multi-step workflows
tests/
  unit/              # per-module unit tests
  contract/          # advertised MCP surface

License

Apache-2.0.

Ver o original no GitHub

Bom para

Relacionados