Loading ToolBench
MCP tools for graph databases: Neo4j (Bolt) and Apache AGE (PostgreSQL). Query Cypher read/write, schema inspection, statistics. Provides infrastructure, authentication, operations, and networking tools.
This is a well-organized Java library for querying graph databases (Neo4j and Apache AGE) with 22 tools spanning authentication, infrastructure, operations, networking, and graph queries. Strengths: all tools have descriptions (10-300 chars, well within baseline), tool names follow verb_noun convention consistently (auth_*, infra_*, graph_*, ops_*, net_*), clear domain organization, and input schemas are present with type definitions. Weaknesses: descriptions are functional but often generic ('List all...', 'Details for...') rather than LLM-optimized; many descriptions lack discovery hints or 'when to use' context; output schemas are not documented in the visible code (only input schemas shown); error handling guidance is minimal; parameters generally lack format/constraint details in descriptions; no tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk classifications. The server appears to be a Spring Boot library component (not a full MCP server with transport), so tool registration may occur elsewhere. Tools are read-only focused (21 of 22 are READ_ONLY except graph_write), which simplifies error handling but also means no confirmation patterns needed.
Full details for a Keycloak client: protocol, redirect URIs, defined roles, services using it, protected routes. Replaces the SSO section of CLAUDE.md. Known clients: gitea, oauth2-proxy, go-filemanager, dashboard-chat, wiki, grafana, knowledge-graph, minio, jenkins, server-api, nvidia_client, claude_client, codex_client.
Complete authentication flow for an auth type: involved services, Keycloak clients, protected routes, configuration. Types: 'oidc' (native OIDC), 'saml', 'oauth2-proxy' (OAuth2 Proxy), 'jwt' (JWT Bearer).
Details for a Keycloak/Gitea user: email, admin status, login source, assigned roles, associated clients. Known users: sol_root, root, massimiliano, visitor.
List all Keycloak clients in the SOL realm with protocol and short description.
Execute a read-only Cypher query on the graph database. Use for MATCH, RETURN, COUNT, path traversal. Supports neo4j and age (Apache AGE on PostgreSQL) backends. IMPORTANT: pass pure Cypher only (e.g. MATCH (n) RETURN n) — the SQL wrapper is added automatically. Do not use // comments in Cypher. For AGE use RETURN {k: v} map syntax.
Output schemas not documented. Visible code shows input schemas only; return types and response field structures are not specified in the provided source. This prevents LLMs from predicting what fields downstream tools need (e.g., does auth_get_client return a roles array? does infra_get_service return a port field for use in net_get_endpoint?).
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 52 | <=2025-11-25 | v2 |
| 2026-03-09 | D | 51 | - | v1 |
Show the graph database schema: node labels, relationship types, and properties for each. Useful for understanding the graph structure.
Graph database statistics: total node and relationship counts, breakdown by label/type.
Execute a mutating Cypher query on the graph database. Use for CREATE, MERGE, SET, DELETE, DETACH DELETE. WARNING: this operation modifies data. IMPORTANT: pass pure Cypher only — the SQL wrapper is added automatically. Do not use // comments. Complex queries with multiple MERGE+MATCH must be split into separate calls.
List all routes and services using a given authentication type. Valid types: 'JWT Bearer', 'OIDC nativo', 'OAuth2 Proxy', 'SAML', 'Nessuna', 'Keycloak nativo'. Replaces the Authentication and SSO section of CLAUDE.md.
List Docker services consuming a specific database. Valid databases: postgres, redis, mongodb, neo4j, libsql, age.
Direct dependencies of a Docker service (depends_on in docker-compose). Shows both the service's dependencies and services that depend on it.
Details for an nginx route: backend, auth type, linked Docker service. Replaces the path-based routing table in CLAUDE.md.
Full details for a Docker service: image, port, directory, exposed nginx routes (with auth), databases used, dependencies. Replaces the 'Services and Ports' table in CLAUDE.md.
Complete nginx path -> service -> auth mapping. Equivalent to the full routing table in CLAUDE.md. Use to answer questions like 'which path exposes X?' or 'which services are public?'.
Full-text search across all infrastructure nodes (DockerService, NginxRoute, Database, AuthPattern). Searches all string property values.
Access URLs for a service: Tailscale, public, Tor. Searches by Docker service name and returns all associated endpoints. Replaces the 'Tailscale URLs' and 'Cloudflare Tunnel' tables in CLAUDE.md.
Nginx architectural pattern: lazy_dns, prefix_stripping, auth_request_oauth2, auth_request_jwt. Includes description, type, configuration example. Replaces the 'Nginx — Architectural patterns' section of CLAUDE.md.
Subpath configuration for a Docker service: parameter, value, effect. Explains how the service handles the nginx subpath (Pattern A: prefix stripping, Pattern B: internal handling with SCRIPT_NAME/--base-url, BASE_PATH). Replaces the 'Subpath configurations' table in CLAUDE.md.
Search operational commands by name or category. Categories: docker, systemd, maintenance, emergenza, query, cicd, sso, ssh, network, wiki. If the parameter matches an exact name, returns that command. Otherwise searches by category and returns all commands in that category. Replaces the 'Common Operations' section of CLAUDE.md.
Operational conventions by category. Categories: git, docker, workflow, documentation, communication, security, operations. Without parameter, returns all conventions. Replaces conventions scattered across CLAUDE.md and MEMORY.md.
List all user-level and system-level systemd services registered in the graph. Includes: dashboard-api, ttyd, ssh-agent, claude-cleanup, wiki-embargo, infra-graph-sync, tailscale-watchdog. Returns unit_file, type, exec_start, description. Replaces the systemd services sections of CLAUDE.md.
Search solutions for a problem or service. Searches the 'problem' and 'cause' fields of Troubleshooting nodes. If the parameter is a service name, returns all related troubleshooting entries. Known issues: SSO Gitea, OAuth2 Proxy 500, nginx 500/502, Gitea 404, Keycloak discovery, disconnected containers, WikiJS SAML double login. Replaces the 'Troubleshooting' section of CLAUDE.md.
Descriptions are generic and lack LLM-optimized context. Most descriptions follow a simple 'List/Get/Query X' template without explaining when to use the tool, what unique insight it provides, or how it relates to other tools. Example: 'Graph database statistics: total node and relationship counts, breakdown by label/type.' (graph_stats), missing hints like 'Use before graph_write to understand cardinality' or 'Compare with previous stats to detect data drift.'
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). The Risk column clearly marks most tools as READ_ONLY and graph_write as WRITE, but these are not expressed in the tool schema using MCP 2026-07-28 tool annotations. This forces LLMs to infer safety from descriptions rather than relying on machine-readable hints. graph_write in particular should carry destructiveHint=true and idempotentHint=false.
Parameters lack constraint descriptions. Many parameters (e.g., flowType, authType, backend) accept a fixed set of values but are not described with explicit enums or constraints in the visible schema. Example: flowType says 'Flow type: oidc, saml, oauth2-proxy, jwt' in the description, but this should be in a formal enum constraint or JSONSchema pattern. Descriptions also don't include format, length, or pattern constraints (e.g., 'clientId must be lowercase alphanumeric, 1-50 chars').
Error handling and recovery guidance missing. No visible error categorization (retryable vs user-fixable vs fatal), no recovery hints in tool descriptions, and no guidance on what to do if a query fails or a resource is not found. Example: ops_troubleshoot description mentions 'Known issues: ...' but doesn't explain what happens if no match is found or how to broaden a search.
graph_write lacks confirmation/dry-run pattern. This is the only destructive tool in the set, yet there is no mention of dry-run, preview, or confirmation steps in the description. An LLM could accidentally issue 'DELETE (n) DETACH DELETE n' without safeguards. A confirmation_before_execute pattern or dry-run mode would be prudent.
Transport mechanism not visible in provided source. The pom.xml shows Spring Boot and Spring AI dependencies but no explicit MCP transport binding (HTTP, STDIO, SSE). The 'TRANSPORT: UNKNOWN' flag indicates this is likely a library component without a complete MCP server implementation. This limits remote accessibility and testability.
No pagination for list tools. Tools like auth_list_clients, ops_list_systemd, infra_port_map (which could return many results) lack limit, offset, page_size, or cursor parameters. Large result sets will bloat context windows and degrade LLM reasoning.