archgraph-argo 0.10.15 → 0.10.17

package/argo/scripts/argo-mcp-server.js

@@ -65,6 +65,7 @@ const SYSTEM_ARCHITECTURE_TOOL_NAMES = new Set([
   'updateArchitectureView',
   'removeArchitectureView',
   'generateArchitectureDiffPlantuml',
+  'queryNeo4jGraph',
 ]);
 
 const TOOLS = [

package/argo/scripts/neo4j-system-architecture-store.js

@@ -781,9 +781,255 @@ function toNumber(value) {
   return Number(value);
 }
 
+// --- Read-only Cypher query + structural projection schema -------------------
+
+const FORBIDDEN_CYPHER_CLAUSES = Object.freeze([
+  'CREATE',
+  'MERGE',
+  'DELETE',
+  'SET',
+  'REMOVE',
+  'DROP',
+  'LOAD CSV',
+  'FOREACH',
+  'IN TRANSACTIONS',
+]);
+
+function stripCypherNoise(cypher) {
+  let result = String(cypher);
+  // Block comments.
+  result = result.replace(/\/\*[\s\S]*?\*\//g, ' ');
+  // Line comments.
+  result = result.replace(/\/\/[^\r\n]*/g, ' ');
+  // Single-quoted string literals.
+  result = result.replace(/'(?:[^'\\]|\\.)*'/g, ' ');
+  // Double-quoted identifiers/literals.
+  result = result.replace(/"(?:[^"\\]|\\.)*"/g, ' ');
+  // Backtick-escaped identifiers.
+  result = result.replace(/`(?:[^`\\]|\\.)*`/g, ' ');
+  return result;
+}
+
+function assertReadOnlyCypher(cypher) {
+  if (typeof cypher !== 'string' || cypher.trim().length === 0) {
+    const error = new Error('cypher must be a non-empty string');
+    error.category = 'CYPHER_QUERY_REQUIRED';
+    throw error;
+  }
+  if (cypher.length > 20000) {
+    const error = new Error('cypher exceeds the 20000 character limit');
+    error.category = 'CYPHER_QUERY_TOO_LONG';
+    throw error;
+  }
+
+  const normalized = stripCypherNoise(cypher).toUpperCase();
+  const found = FORBIDDEN_CYPHER_CLAUSES.find(clause => {
+    const escaped = clause.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`\\b${escaped}\\b`).test(normalized);
+  });
+  if (found) {
+    const error = new Error(`Cypher write clause '${found}' is not allowed; the Neo4j graph query interface is read-only`);
+    error.category = 'READ_ONLY_CYPHER_REQUIRED';
+    error.clause = found;
+    throw error;
+  }
+  return true;
+}
+
+function serializeNeo4jValue(value) {
+  if (value === null || value === undefined) {
+    return value === undefined ? null : value;
+  }
+  if (typeof value === 'number' || typeof value === 'string' || typeof value === 'boolean') {
+    return value;
+  }
+
+  let neo4j = null;
+  try {
+    neo4j = requireNeo4jDriver();
+  } catch {
+    neo4j = null;
+  }
+
+  if (neo4j && typeof neo4j.isInt === 'function' && neo4j.isInt(value)) {
+    if (typeof value.inSafeRange === 'function' && value.inSafeRange()) {
+      return value.toNumber();
+    }
+    return value.toString();
+  }
+  if (neo4j && typeof neo4j.isNode === 'function' && neo4j.isNode(value)) {
+    return {
+      $node: {
+        identity: value.identity ? String(value.identity) : null,
+        labels: Array.isArray(value.labels) ? value.labels : [],
+        properties: serializeNeo4jValue(value.properties),
+      },
+    };
+  }
+  if (neo4j && typeof neo4j.isRelationship === 'function' && neo4j.isRelationship(value)) {
+    return {
+      $relationship: {
+        identity: value.identity ? String(value.identity) : null,
+        type: value.type,
+        start: value.start ? String(value.start) : null,
+        end: value.end ? String(value.end) : null,
+        properties: serializeNeo4jValue(value.properties),
+      },
+    };
+  }
+  if (neo4j && typeof neo4j.isPath === 'function' && neo4j.isPath(value)) {
+    return {
+      $path: {
+        start: serializeNeo4jValue(value.start),
+        end: serializeNeo4jValue(value.end),
+        length: serializeNeo4jValue(value.length),
+        segments: Array.isArray(value.segments) ? value.segments.map(serializeNeo4jValue) : [],
+      },
+    };
+  }
+  if (Array.isArray(value)) {
+    return value.map(serializeNeo4jValue);
+  }
+  if (typeof value === 'object') {
+    const result = {};
+    for (const [key, item] of Object.entries(value)) {
+      result[key] = serializeNeo4jValue(item);
+    }
+    return result;
+  }
+  return String(value);
+}
+
+function buildNeo4jGraphSchema(architecturePath = DEFAULT_GRAPH_PATH) {
+  return {
+    graphKey: buildGraphKey(architecturePath),
+    nodeLabels: {
+      ArchitectureGraph: {
+        description: 'One node per canonical graph document; identified by graphKey.',
+        properties: [
+          'graphKey',
+          'source_path',
+          'name',
+          'description',
+          'attributes_json',
+          'raw_json',
+          'element_count',
+          'relationship_count',
+          'view_count',
+        ],
+      },
+      Element: {
+        description: 'Canonical architecture elements. Element.type holds the ArchiMate element type.',
+        properties: [
+          'graphKey',
+          'id',
+          'name',
+          'type',
+          'parent',
+          'alias',
+          'classifier',
+          'description',
+          'attributes_json',
+          'subdiagram_views_json',
+          'testcases_json',
+          'raw_json',
+        ],
+      },
+      ArchitectureRelationship: {
+        description: 'Canonical architecture relationships. type holds the ArchiMate relationship type; source_id/target_id reference Element.id.',
+        properties: [
+          'graphKey',
+          'id',
+          'name',
+          'type',
+          'statement',
+          'description',
+          'document',
+          'attributes_json',
+          'source_id',
+          'source_name',
+          'target_id',
+          'target_name',
+          'raw_json',
+        ],
+      },
+      View: {
+        description: 'Canonical views; identified by view_id.',
+        properties: [
+          'graphKey',
+          'view_id',
+          'view_name',
+          'parent_element_id',
+          'parent_element_name',
+          'description',
+          'included_elements_json',
+          'included_relationships_json',
+          'raw_json',
+        ],
+      },
+    },
+    relationshipTypes: {
+      OWNS_ELEMENT: { from: 'ArchitectureGraph', to: 'Element' },
+      OWNS_RELATIONSHIP: { from: 'ArchitectureGraph', to: 'ArchitectureRelationship' },
+      OWNS_VIEW: { from: 'ArchitectureGraph', to: 'View' },
+      RELATIONSHIP_SOURCE: { from: 'ArchitectureRelationship', to: 'Element', description: 'Source endpoint element of a relationship record.' },
+      RELATIONSHIP_TARGET: { from: 'ArchitectureRelationship', to: 'Element', description: 'Target endpoint element of a relationship record.' },
+      ARCHIMATE_RELATES: { from: 'Element', to: 'Element', properties: ['graphKey', 'relationship_id'], description: 'Direct ArchiMate semantic edge between two elements.' },
+      VIEW_OF: { from: 'View', to: 'Element', description: 'Parent element of a sub-view.' },
+      INCLUDES_ELEMENT: { from: 'View', to: 'Element', properties: ['order'] },
+      INCLUDES_RELATIONSHIP: { from: 'View', to: 'ArchitectureRelationship', properties: ['order'] },
+      HAS_SUBDIAGRAM: { from: 'Element', to: 'View' },
+    },
+  };
+}
+
+async function runNeo4jCypherQuery(options = {}) {
+  const architecturePath = options.architecturePath || DEFAULT_GRAPH_PATH;
+  const cypher = options.cypher;
+  assertReadOnlyCypher(cypher);
+
+  const graphKey = buildGraphKey(architecturePath);
+  const config = getNeo4jConfig(options);
+  const driver = options.driver || createDriver(config);
+  const ownDriver = !options.driver;
+  const session = driver.session({ database: config.database });
+
+  try {
+    const result = await session.executeRead(tx => tx.run(cypher, { graphKey }));
+    const records = result.records.map(record => {
+      const entry = {};
+      for (const key of record.keys) {
+        entry[key] = serializeNeo4jValue(record.get(key));
+      }
+      return entry;
+    });
+
+    const summary = result.summary;
+    return {
+      architecturePath,
+      graphKey,
+      records,
+      summary: {
+        queryType: summary ? summary.queryType : null,
+        database: summary && summary.database ? summary.database.name : null,
+        containsUpdates: summary && summary.counters && typeof summary.counters.containsUpdates === 'function'
+          ? summary.counters.containsUpdates()
+          : null,
+      },
+    };
+  } finally {
+    await session.close();
+    if (ownDriver) {
+      await driver.close();
+    }
+  }
+}
+
 module.exports = {
   DEFAULT_GRAPH_PATH,
+  assertReadOnlyCypher,
   buildGraphKey,
+  buildNeo4jGraphSchema,
   createDriver,
   digestCanonicalArchitecture,
   ensureDatabaseExists,
@@ -797,6 +1043,8 @@ module.exports = {
   readNeo4jSyncState,
   recoverNeo4jSyncIfNeeded,
   resolveArchitecturePath,
+  runNeo4jCypherQuery,
+  serializeNeo4jValue,
   syncArchitectureToNeo4j,
   verifyArchitectureSync,
   waitForDatabaseOnline,

package/argo/scripts/systemarchitecture-mcp-server.js

@@ -164,7 +164,10 @@ const {
 } = require('./graph-rag/mutationEmbeddingVectorLifecycle.js');
 const {
   DEFAULT_GRAPH_PATH: NEO4J_DEFAULT_GRAPH_PATH,
+  buildGraphKey,
+  buildNeo4jGraphSchema,
   recoverNeo4jSyncIfNeeded,
+  runNeo4jCypherQuery,
   syncArchitectureToNeo4j,
   verifyArchitectureSync,
 } = require('./neo4j-system-architecture-store.js');
@@ -379,6 +382,19 @@ const TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: 'queryNeo4jGraph',
+    description: 'Run a read-only Cypher query against the Neo4j structural projection of the intent architecture, or request the projection schema so an agent can construct its own Cypher. Pass {schema: true} to return node labels, relationship types, property keys, and the legal ArchiMate element/relationship type enums. Pass {cypher: "..."} to execute a read-only query; scope it with {graphKey: $graphKey}. Write clauses (CREATE/MERGE/DELETE/SET/REMOVE/DROP/LOAD CSV/FOREACH/IN TRANSACTIONS) are rejected.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        architecturePath: { type: 'string', description: `Default: ${DEFAULT_GRAPH_PATH}` },
+        cypher: { type: 'string', description: 'Read-only Cypher query to execute. Use $graphKey to scope to the current architecture graph, e.g. MATCH (e:Element {graphKey: $graphKey}) RETURN e.id, e.name.' },
+        schema: { type: 'boolean', description: 'When true, return the Neo4j projection schema instead of running a Cypher query.' },
+      },
+      additionalProperties: false,
+    },
+  },
 ];
 
 // Every tool accepts an optional per-call `workspaceRoot` (absolute path,
@@ -2154,9 +2170,80 @@ async function callTool(name, args = {}, dependencies = undefined) {
     return mutationToolResult(attachContextWarnings(await buildMutationResult(context, [{ type: 'removeView', view_id: args.view_id }], write), context), write);
   }
 
+  if (name === 'queryNeo4jGraph') {
+    return queryNeo4jGraphTool(args);
+  }
+
   throw new Error(`Unknown tool: ${name}`);
 }
 
+async function queryNeo4jGraphTool(args = {}) {
+  const architecturePath = args.architecturePath || DEFAULT_GRAPH_PATH;
+
+  if (args.schema === true) {
+    return queryNeo4jGraphSchemaResult(architecturePath);
+  }
+
+  try {
+    const result = await runNeo4jCypherQuery({
+      architecturePath,
+      cypher: args.cypher,
+    });
+    return toolResult({
+      status: 'passed',
+      architecturePath: result.architecturePath,
+      graphKey: result.graphKey,
+      records: result.records,
+      summary: result.summary,
+    });
+  } catch (error) {
+    return toolResult(queryError(
+      error && error.category ? error.category : 'NEO4J_QUERY_FAILED',
+      String(error && error.message ? error.message : error),
+      {
+        architecturePath,
+        graphKey: buildGraphKey(architecturePath),
+        ...(error && error.clause ? { clause: error.clause } : {}),
+      },
+    ));
+  }
+}
+
+function queryNeo4jGraphSchemaResult(architecturePath) {
+  const schema = buildNeo4jGraphSchema(architecturePath);
+  let typeEnums = {};
+  try {
+    const workspaceRoot = resolveWorkspaceRoot({ architecturePath });
+    const schemaPath = resolveSchemaPath(workspaceRoot);
+    const jsonSchema = readJson(schemaPath.absolutePath, schemaPath.relativePath);
+    typeEnums = {
+      archimateElementTypes: (jsonSchema.$defs.archimateElementType || {}).enum || [],
+      archimateRelationshipTypes: (jsonSchema.$defs.archimateRelationshipType || {}).enum || [],
+    };
+  } catch (error) {
+    typeEnums = {
+      archimateElementTypes: [],
+      archimateRelationshipTypes: [],
+      schemaEnumError: String(error && error.message ? error.message : error),
+    };
+  }
+
+  return toolResult({
+    status: 'passed',
+    architecturePath,
+    graphKey: buildGraphKey(architecturePath),
+    schema: {
+      ...schema,
+      ...typeEnums,
+    },
+    usage: {
+      scopeGraph: 'MATCH (e:Element {graphKey: $graphKey}) ...',
+      exampleAllBusinessActors: "MATCH (e:Element {graphKey: $graphKey}) WHERE e.type = 'Business Actor' RETURN e.id, e.name, e.description",
+      exampleAssignments: "MATCH (a:Element {graphKey: $graphKey, type: 'Business Actor'})-[r:ARCHIMATE_RELATES]->(b:Element {graphKey: $graphKey}) WHERE r.relationship_id IS NOT NULL RETURN a.name, type(r), b.name, r.relationship_id",
+    },
+  });
+}
+
 async function resolveSemanticOperatorJourney(dependencies) {
   return dependencies && dependencies.semanticOperatorJourney
     ? dependencies.semanticOperatorJourney

package/install-argo.ps1

@@ -726,7 +726,7 @@ if ($SkipDsh) {
         Write-DshManagedBlock -Path $patchPath -Block $block -MarkerStart '# BEGIN ArchGraph ARGO deployment' -MarkerEnd '# END ArchGraph ARGO deployment'
     }
 
-    Write-Host "[19/19] argo\agents5 -> $DshHome\.agent-presets\<id> (DeepSeek Harness agent presets)"
+    Write-Host "[19/19] argo\agents6 -> $DshHome\.agent-presets\<id> (DeepSeek Harness agent presets)"
     New-DshAgentPresets -DshHome $DshHome -AgentsSrc (Join-Path $argoDir 'agents')
 
     Write-Host '  Restart `dsh web` to activate the MCP bridge and the wakeup plugin;'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgraph-argo",
-  "version": "0.10.15",
+  "version": "0.10.17",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {