@rubytech/create-maxy 1.0.629 → 1.0.630

package/payload/platform/plugins/memory/mcp/scripts/graph/accept.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# Task 557 acceptance harness for the graph MCP integration.
+#
+# Spawns the graph shim, drives it as a JSON-RPC client over stdio, runs
+# one query per acceptance class, prints PASS/FAIL per check, and exits
+# non-zero if any check fails. Assumes the brand's Neo4j is running and
+# the fixture in fixture.cypher has been seeded.
+#
+# Usage:
+#   PLATFORM_ROOT=~/.maxy/platform bash accept.sh           # infers NEO4J_URI from env
+#   PLATFORM_ROOT=~/.maxy/platform NEO4J_URI=bolt://localhost:7687 bash accept.sh
+#
+# Dependencies: node, python3 (for JSON-RPC framing), uvx (via the shim).
+#
+# Exit codes:
+#   0  all PASS
+#   1  one or more FAIL
+#   2  setup error (shim missing, uvx missing, etc.)
+
+set -euo pipefail
+
+PLATFORM_ROOT="${PLATFORM_ROOT:-$(cd "$(dirname "$0")/../../../../.." && pwd)}"
+SHIM="${PLATFORM_ROOT}/lib/graph-mcp/dist/index.js"
+
+if [[ ! -f "$SHIM" ]]; then
+  echo "FAIL: shim not built at $SHIM — run 'npm run build:lib' in $PLATFORM_ROOT" >&2
+  exit 2
+fi
+
+if ! command -v uvx >/dev/null 2>&1; then
+  echo "FAIL: uvx not on PATH — run: curl -LsSf https://astral.sh/uv/install.sh | sh -s -- -y" >&2
+  exit 2
+fi
+
+PASS=0
+FAIL=0
+TOTAL=0
+
+run_check() {
+  local label="$1"
+  local query="$2"
+  local tool="${3:-maxy-graph_read_neo4j_cypher}"
+  TOTAL=$(( TOTAL + 1 ))
+
+  # Drive the shim via a short Node inline client. Exits 0 with the response
+  # body on stdout when the tool call succeeds; exits 1 on any RPC error.
+  if out=$(
+    node -e "
+      const { spawn } = require('node:child_process');
+      const shim = process.env.SHIM;
+      const tool = process.env.TOOL;
+      const query = process.env.QUERY;
+      const proc = spawn('node', [shim], { stdio: ['pipe', 'pipe', 'inherit'] });
+      let buf = '';
+      proc.stdout.on('data', (chunk) => { buf += chunk.toString('utf8'); });
+      const send = (obj) => proc.stdin.write(JSON.stringify(obj) + '\n');
+      send({ jsonrpc: '2.0', id: 1, method: 'initialize',
+             params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'accept.sh', version: '1.0' } } });
+      setTimeout(() => {
+        send({ jsonrpc: '2.0', method: 'notifications/initialized' });
+        const params = tool === 'maxy-graph_get_neo4j_schema' ? {} : { query };
+        send({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: tool, arguments: params } });
+      }, 1500);
+      setTimeout(() => {
+        proc.kill('SIGTERM');
+        // Look for id:2 response in the buffer
+        const lines = buf.split('\n').filter(Boolean);
+        for (const line of lines) {
+          try { const m = JSON.parse(line); if (m.id === 2) {
+            if (m.error) { console.error('RPC_ERROR: ' + JSON.stringify(m.error)); process.exit(1); }
+            const text = m.result && m.result.content && m.result.content[0] && m.result.content[0].text || '';
+            process.stdout.write(text);
+            process.exit(0);
+          } } catch (_) {}
+        }
+        console.error('NO_RESPONSE');
+        process.exit(1);
+      }, 10000);
+    " 2>/dev/null
+  ); then
+    if [[ -n "$out" ]]; then
+      echo "PASS: ${label} (response ${#out}b)"
+      PASS=$(( PASS + 1 ))
+    else
+      echo "FAIL: ${label} (empty response)"
+      FAIL=$(( FAIL + 1 ))
+    fi
+  else
+    echo "FAIL: ${label} (RPC error or timeout)"
+    FAIL=$(( FAIL + 1 ))
+  fi
+}
+
+# Exported env used by the inline Node client above.
+export SHIM
+export PLATFORM_ROOT
+
+export TOOL="maxy-graph_get_neo4j_schema"
+export QUERY=""
+run_check "get_neo4j_schema returns labels" ""
+
+export TOOL="maxy-graph_read_neo4j_cypher"
+
+export QUERY="MATCH (n) RETURN labels(n)[0] AS type, count(*) AS n ORDER BY n DESC LIMIT 20"
+run_check "enumerate by label" "$QUERY"
+
+export QUERY="MATCH (n:Task) RETURN count(n) AS total"
+run_check "count Tasks" "$QUERY"
+
+export QUERY="MATCH (p:Person {email: 'graph-accept@test.maxy.local'}) RETURN elementId(p) AS id, p.givenName, p.email LIMIT 1"
+run_check "find person by email" "$QUERY"
+
+export QUERY="MATCH (p:Person {email: 'graph-accept@test.maxy.local'})-[r]-(m) RETURN type(r) AS rel, labels(m)[0] AS neighbourType LIMIT 10"
+run_check "neighbours of fixture person" "$QUERY"
+
+export QUERY="MATCH (n) WHERE n.createdAt IS NOT NULL RETURN labels(n)[0] AS type, toString(n.createdAt) AS createdAt ORDER BY n.createdAt DESC LIMIT 5"
+run_check "recent nodes projection" "$QUERY"
+
+export QUERY="CALL db.labels() YIELD label RETURN label ORDER BY label"
+run_check "db.labels() schema introspection" "$QUERY"
+
+echo ""
+if [[ $FAIL -eq 0 ]]; then
+  echo "ALL PASS — ${PASS}/${TOTAL}"
+  exit 0
+else
+  echo "FAIL — ${PASS}/${TOTAL} passed, ${FAIL} failed"
+  exit 1
+fi

package/payload/platform/plugins/memory/mcp/scripts/graph/fixture.cypher

@@ -0,0 +1,59 @@
+// Task 557 — acceptance fixture for the graph MCP integration.
+// Seeds one node per primary label so accept.sh can verify enumerate,
+// count, find, neighbours, recent, and schema queries end-to-end.
+// Safe to re-run: MERGE on a synthetic accountId prefix + deterministic ids.
+
+MERGE (p:Person {email: 'graph-accept@test.maxy.local'})
+  ON CREATE SET p.givenName = 'Graph',
+                p.familyName = 'Accept',
+                p.telephone = '+440000557001',
+                p.status = 'active',
+                p.accountId = 'accept-557',
+                p.createdAt = datetime()
+MERGE (b:LocalBusiness {accountId: 'accept-557'})
+  ON CREATE SET b.name = 'Accept Corp',
+                b.businessType = 'test-fixture',
+                b.createdAt = datetime()
+MERGE (s:Service {serviceId: 'accept-557-service-1'})
+  ON CREATE SET s.name = 'Test Service',
+                s.accountId = 'accept-557',
+                s.createdAt = datetime()
+MERGE (t:Task {taskId: 'accept-557-task-1'})
+  ON CREATE SET t.title = 'Acceptance task',
+                t.status = 'open',
+                t.priority = 'P2',
+                t.accountId = 'accept-557',
+                t.createdAt = datetime()
+MERGE (e:Event {eventId: 'accept-557-event-1'})
+  ON CREATE SET e.name = 'Acceptance event',
+                e.status = 'scheduled',
+                e.startDate = datetime(),
+                e.accountId = 'accept-557',
+                e.createdAt = datetime()
+MERGE (c:Conversation {conversationId: 'accept-557-conv-1'})
+  ON CREATE SET c.name = 'Acceptance conversation',
+                c.agentType = 'admin',
+                c.accountId = 'accept-557',
+                c.createdAt = datetime()
+MERGE (m:Message {messageId: 'accept-557-msg-1'})
+  ON CREATE SET m.role = 'user',
+                m.content = 'Acceptance test message',
+                m.accountId = 'accept-557',
+                m.createdAt = datetime()
+MERGE (kd:KnowledgeDocument {attachmentId: 'accept-557-doc-1'})
+  ON CREATE SET kd.name = 'Acceptance document',
+                kd.accountId = 'accept-557',
+                kd.createdAt = datetime()
+MERGE (sec:Section {sectionId: 'accept-557-sec-1'})
+  ON CREATE SET sec.title = 'Section one',
+                sec.accountId = 'accept-557',
+                sec.createdAt = datetime()
+MERGE (ch:Chunk {chunkId: 'accept-557-chk-1'})
+  ON CREATE SET ch.text = 'Chunk text for acceptance.',
+                ch.accountId = 'accept-557',
+                ch.createdAt = datetime()
+MERGE (p)-[:WORKS_FOR]->(b)
+MERGE (b)-[:OFFERS]->(s)
+MERGE (kd)-[:HAS_SECTION]->(sec)
+MERGE (sec)-[:HAS_CHUNK]->(ch)
+MERGE (c)-[:HAS_MESSAGE]->(m);

package/payload/platform/plugins/memory/references/graph-primitives.md

@@ -0,0 +1,195 @@
+<!-- Injected into admin system prompt by claude-agent.ts when agentType === "admin". -->
+<!-- Consumed by the upstream mcp-neo4j-cypher server via `maxy-graph_read_neo4j_cypher`. -->
+<!-- Source of truth for node labels and properties: platform/neo4j/schema.cypher + plugins/memory/references/schema-*.md. -->
+
+# Graph interrogation (read-only Cypher cookbook)
+
+When a user asks a relational question about their own graph — *"list all my
+people", "how many tasks do I have", "find the person with email X", "what's
+linked to this business", "show me the 20 most recently created nodes" — use
+`maxy-graph_read_neo4j_cypher` or `maxy-graph_get_neo4j_schema`, not
+`memory-search`. Vector search is for "things like this"; Cypher is for "the
+exact set where".
+
+The connected Neo4j instance contains only this brand's data (per-brand
+instance architecture — see `.docs/neo4j.md`). You never need an account
+filter in the query.
+
+## Non-negotiable: never return raw nodes
+
+`RETURN n` dumps every property, including the 768-dim `embedding` float
+array. This blows the context budget on the first row. **Always enumerate the
+properties you want.**
+
+  Wrong: `MATCH (n:Person) RETURN n LIMIT 20`
+  Right: `MATCH (n:Person) RETURN elementId(n) AS id, n.givenName, n.familyName, n.email, n.telephone LIMIT 20`
+
+Apply this convention to every query. Only project the fields you need to
+answer the question. When in doubt, exclude `embedding`, `embeddingText`, and
+any property whose name ends in `_vector`.
+
+## Cookbook
+
+Parameterise results with `ORDER BY` and `LIMIT` every time — even an
+"inventory" query should bound itself. Default limit: 50.
+
+### Enumerate
+
+All nodes, grouped by label, with a human-readable name:
+
+```cypher
+MATCH (n)
+RETURN labels(n)[0] AS type,
+       coalesce(n.name, n.title, n.givenName + ' ' + n.familyName, n.email, '(unnamed)') AS name,
+       elementId(n) AS id
+ORDER BY type, name
+LIMIT 200
+```
+
+One label only:
+
+```cypher
+MATCH (n:Person)
+RETURN elementId(n) AS id, n.givenName, n.familyName, n.email, n.telephone
+ORDER BY n.familyName, n.givenName
+LIMIT 100
+```
+
+### Count
+
+Total across the graph:
+
+```cypher
+MATCH (n)
+RETURN count(n) AS total
+```
+
+By label:
+
+```cypher
+MATCH (n)
+RETURN labels(n)[0] AS type, count(*) AS n
+ORDER BY n DESC
+```
+
+### Find
+
+By exact email:
+
+```cypher
+MATCH (p:Person {email: $email})
+RETURN elementId(p) AS id, p.givenName, p.familyName, p.telephone, p.status
+```
+
+Partial name, case-insensitive:
+
+```cypher
+MATCH (p:Person)
+WHERE toLower(p.givenName) CONTAINS toLower($q)
+   OR toLower(p.familyName) CONTAINS toLower($q)
+RETURN elementId(p) AS id, p.givenName, p.familyName, p.email
+LIMIT 20
+```
+
+### Neighbours
+
+What is linked to a node (1 hop out, undirected):
+
+```cypher
+MATCH (n)-[r]-(m)
+WHERE elementId(n) = $id
+RETURN type(r) AS rel,
+       labels(m)[0] AS neighbourType,
+       coalesce(m.name, m.title, m.email, '(unnamed)') AS neighbour,
+       elementId(m) AS neighbourId
+LIMIT 50
+```
+
+### Recent
+
+Most recently created nodes (any label):
+
+```cypher
+MATCH (n)
+WHERE n.createdAt IS NOT NULL
+RETURN labels(n)[0] AS type,
+       coalesce(n.name, n.title, n.givenName + ' ' + n.familyName, n.email, '(unnamed)') AS name,
+       toString(n.createdAt) AS createdAt,
+       elementId(n) AS id
+ORDER BY n.createdAt DESC
+LIMIT 20
+```
+
+Most recently updated:
+
+```cypher
+MATCH (n)
+WHERE n.updatedAt IS NOT NULL
+RETURN labels(n)[0] AS type,
+       coalesce(n.name, n.title, n.email, '(unnamed)') AS name,
+       toString(n.updatedAt) AS updatedAt,
+       elementId(n) AS id
+ORDER BY n.updatedAt DESC
+LIMIT 20
+```
+
+### Schema
+
+All labels present in the graph:
+
+```cypher
+CALL db.labels() YIELD label RETURN label ORDER BY label
+```
+
+All relationship types:
+
+```cypher
+CALL db.relationshipTypes() YIELD relationshipType RETURN relationshipType ORDER BY relationshipType
+```
+
+Or use `maxy-graph_get_neo4j_schema` for a richer one-shot structural summary.
+
+### Fulltext
+
+Use the `knowledge_fulltext` index for keyword-style search across
+KnowledgeDocument / Section / Chunk content:
+
+```cypher
+CALL db.index.fulltext.queryNodes('knowledge_fulltext', $query)
+YIELD node, score
+WHERE score > 0.5
+RETURN labels(node)[0] AS type,
+       coalesce(node.name, node.title, node.heading, '(unnamed)') AS name,
+       score,
+       elementId(node) AS id
+LIMIT 20
+```
+
+### Filter by status or category
+
+Events that are cancelled:
+
+```cypher
+MATCH (e:Event {status: 'cancelled'})
+RETURN elementId(e) AS id, e.name, toString(e.startDate) AS start
+ORDER BY e.startDate DESC
+LIMIT 50
+```
+
+Tasks by status:
+
+```cypher
+MATCH (t:Task {status: $status})
+RETURN elementId(t) AS id, t.title, toString(t.createdAt) AS created, t.priority
+ORDER BY t.createdAt DESC
+LIMIT 50
+```
+
+## When to switch back to memory-search
+
+- "Things similar to X" → `memory-search` (vector + BM25 hybrid)
+- "Candidates to rank by criterion Y" → `memory-rank`
+- "Conversations where we discussed Z" → `conversation-search`
+
+Cypher is for relational certainty. Vector search is for similarity. They
+answer different questions; don't use one to fake the other.