MCP: add vector_search tool

[robfrank]

Part of #4859.

Motivation

Models reliably fail to produce correct vector.neighbors/vector.sparseNeighbors SQL — argument order (index-name, key-or-vector, k, [efSearch|options-object]), dense-vs-sparse index selection, and filter/groupBy option shapes are all ArcadeDB-specific and undocumented in general training data. Justification: #1 ergonomic guardrail (see governing principle in #4859).

Proposed design

• Tool name: vector_search
• Input schema:

{
  "type": "object",
  "properties": {
    "database": {"type": "string"},
    "indexName": {"type": "string", "description": "LSM vector or sparse-vector index name"},
    "queryVector": {"type": "array", "items": {"type": "number"}},
    "k": {"type": "integer", "default": 10},
    "efSearch": {"type": "integer"},
    "filter": {"type": "string", "description": "optional SQL WHERE-style predicate string"},
    "sparse": {"type": "boolean", "default": false}
  },
  "required": ["database", "indexName", "queryVector", "k"]
}

• Output: {results: [{rid, score, properties?}]}
• Permission gating: requires config.isAllowReads() (mirrors QueryTool.java:69); internally builds a vector.neighbors(...)/vector.sparseNeighbors(...) SELECT and routes it through the query engine so the existing isIdempotent() gate still applies — do not bypass it with a raw execute path.
• queryText embedding generation is out of scope for v1 — document that callers must supply a pre-computed queryVector.
• Engine functions used: SQLFunctionVectorNeighbors, SQLFunctionVectorSparseNeighbors (engine/src/main/java/com/arcadedb/function/sql/vector/).

Acceptance criteria

• VectorSearchTool.getDefinition()/execute(server, user, args, config) follows the existing tool class pattern (Apache-2.0 header, @author tag, JSONObject/JSONArray builder style).
• Registered in MCPHttpHandler TOOLS_LIST + dispatch switch, and in MCPStdioServer.
• Rejects non-idempotent or malformed vector expressions with a clear SecurityException/IllegalArgumentException.
• Respects allowReads=false by returning a permission error, not a silent empty result.
• Dense and sparse index paths both covered by tests.
• Unit tests added mirroring MCPPermissionsTest patterns; MCPServerPluginTest extended for the new tool's tools/list entry.
• Docs updated in the MCP section of arcadedb-docs.

Files to touch

server/src/main/java/com/arcadedb/server/mcp/tools/VectorSearchTool.java (new), MCPHttpHandler.java, MCPStdioServer.java, server/src/test/java/com/arcadedb/server/mcp/ (new/updated tests).

Dependencies

None (foundational). #4861 (hybrid_search) reuses its vector-leg logic.

Effort estimate

M — new tool class, dimension/index validation, permission wiring, dense+sparse test coverage.