archgraph-argo 0.10.50 → 0.10.52

package/README.md

@@ -43,11 +43,30 @@ argo-deploy
 
 Done — the ARGO toolchain, skills, and rules are deployed, and the `argo` MCP server is registered automatically in **GitHub Copilot**, **Cursor**, **OpenCode**, **DeepSeek Harness** (dsh), and **OpenClaw**.
 
-> Semantic (Graph RAG) queries also need **Neo4j** and a **vector engine** configured in
-> `~/.argo/.env`; everything else works out of the box.
+### Prerequisites and configuration
+
+Everything works out of the box except **semantic (Graph RAG) queries**, which need:
+
+- **Neo4j graph database** — stores the structural projection of your architecture graph. During
+  `argo-deploy` you configure `ARGO_NEO4J_DATABASE_URL`, `ARGO_NEO4J_DATABASE_USERNAME`, and
+  `ARGO_NEO4J_DATABASE_PASSWORD` in `~/.argo/.env`.
+- **Embedding / vector engine** — powers semantic Graph RAG retrieval. Configure
+  `ARGO_EMBEDDING_BASE_URL`, `ARGO_EMBEDDING_MODEL`, `ARGO_EMBEDDING_PROVIDER`,
+  `ARGO_EMBEDDING_MODEL_VERSION`, `ARGO_EMBEDDING_DIMENSIONS`, plus the API key `QWEN_KEY`.
+
+Where do the values come from? The Neo4j credentials come from the Neo4j instance you own or
+provision (URI, username, password). The embedding configuration and `QWEN_KEY` come from your
+embedding provider's dashboard — for example Alibaba DashScope. `argo-deploy` walks you through the
+prompt (existing non-empty values in `~/.argo/.env` are kept); you can also edit the file afterwards
+and re-run.
 
 ## How to use
 
+**Step 0 — initialize the workspace.** In a fresh project, ask your coding agent to run `argo init`
+(the `initializeWorkspace` MCP call). It creates a starter `design/KG/SystemArchitecture.json` when
+missing, performs the first JSON → Neo4j sync, initializes the semantic (Graph RAG) lifecycle, and
+verifies the architecture. From then on, the intent graph is the source of truth for the project.
+
 After installing, open your project and start a coding agent. It will:
 
 1. locate the architecture element behind the task before changing anything,
@@ -56,6 +75,15 @@ After installing, open your project and start a coding agent. It will:
 
 The intent architecture graph — modelled in **ArchiMate 3.2** — is the single source of truth.
 
+## Community
+
+ArchGraph runs on open co-building. Join the community hub to share, browse and reuse **architecture
+subgraphs** across projects, and follow the governance & contribution guides:
+
+- **Community site** — https://argo.derekworkspacev5.com/archgraph/ (subgraph library, docs, blog)
+- **graph-wiki repository** — https://github.com/derekhu0002/graph-wiki (graph-asset home: contribute
+  a subgraph from your project, or pull one back to reuse)
+
 ## License
 
 [Apache License 2.0](LICENSE)

package/argo/mcp-bridges/graph-mcp-stdio.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+'use strict';
+
+// graph-mcp stdio bridge for hosts that dial remote MCP servers over SSE GET
+// and fail on Streamable HTTP-only endpoints (CURSOR remote url entries GET
+// /mcp -> 404). This bridge translates stdio JSON-RPC lines into POST
+// Streamable HTTP requests against GRAPH_MCP_URL so the remote graph-mcp
+// server loads as an ordinary stdio MCP server.
+//
+// Deployed by install-argo.ps1 to ~/.cursor/mcp-bridges/graph-mcp-stdio.js
+// and registered as:
+//   "graph-mcp": { type: stdio, command: node,
+//                  args: [<bridge path>],
+//                  env: { GRAPH_MCP_URL: "https://.../mcp" } }
+
+const readline = require('node:readline');
+
+const endpoint = process.env.GRAPH_MCP_URL;
+if (!endpoint) {
+  console.error('GRAPH_MCP_URL is required');
+  process.exit(1);
+}
+
+function emit(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function parseSse(body) {
+  const messages = [];
+  // SSE frames are separated by a blank line (\r\n\r\n or \n\n).
+  for (const block of body.split(/\r?\n\r?\n/)) {
+    const data = block
+      .split(/\r?\n/)
+      .filter((line) => line.startsWith('data:'))
+      .map((line) => line.slice(5).trimStart())
+      .join('\n');
+    if (data) {
+      messages.push(JSON.parse(data));
+    }
+  }
+  return messages;
+}
+
+async function forward(message) {
+  const response = await fetch(endpoint, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/json, text/event-stream',
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(message),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Remote MCP returned HTTP ${response.status}`);
+  }
+
+  // 202 Accepted means the server will stream the result over a separate SSE
+  // connection; there is nothing to return on this POST. Notifications
+  // (id === undefined) carry no response either.
+  if (response.status === 202 || message.id === undefined) return;
+
+  const body = await response.text();
+  const contentType = response.headers.get('content-type') || '';
+  if (contentType.includes('text/event-stream')) {
+    for (const item of parseSse(body)) emit(item);
+    return;
+  }
+  if (body.trim()) emit(JSON.parse(body));
+}
+
+const input = readline.createInterface({
+  input: process.stdin,
+  crlfDelay: Infinity,
+});
+
+input.on('line', (line) => {
+  if (!line.trim()) return;
+  let message;
+  try {
+    message = JSON.parse(line);
+  } catch (error) {
+    console.error(`Invalid JSON-RPC input: ${error.message}`);
+    return;
+  }
+
+  forward(message).catch((error) => {
+    if (message.id !== undefined) {
+      emit({
+        jsonrpc: '2.0',
+        id: message.id,
+        error: { code: -32000, message: error.message },
+      });
+    } else {
+      console.error(error.message);
+    }
+  });
+});

package/argo/scripts/ensureArgoHarnessEnvironment.js

@@ -160,7 +160,7 @@ async function ensureCanonicalSemanticLifecycle({ checkOnly, workspaceRoot, neo4
 
   try {
     const semanticLifecycle = await runCanonicalSemanticInit(
-      systemArchitectureMcp.createDefaultCanonicalSemanticInitComposition(),
+      systemArchitectureMcp.createDefaultCanonicalSemanticInitComposition({ repositoryRoot: workspaceRoot }),
       {
         repositoryRoot: workspaceRoot,
         neo4j,

package/install-argo.ps1

@@ -5,6 +5,7 @@ param(
     [string]$PromptsRoot = "$env:APPDATA\Code\User\prompts",
     [string]$CursorSkillsRoot = "$env:USERPROFILE\.cursor\skills",
     [string]$CursorMcpPath = "$env:USERPROFILE\.cursor\mcp.json",
+    [string]$CursorMcpBridgesRoot = "$env:USERPROFILE\.cursor\mcp-bridges",
     [string]$OpenCodeSkillsRoot = "$env:USERPROFILE\.config\opencode\skills",
     [string]$OpenCodeAgentsPath = "$env:USERPROFILE\.config\opencode\AGENTS.md",
     [string]$OpenCodeConfigPath = "$env:USERPROFILE\.config\opencode\opencode.json",
@@ -769,6 +770,11 @@ $cursorSkillDest = Join-Path $CursorSkillsRoot 'argo-init'
 Write-Host "[7/22] argo\skills\argo-init -> $cursorSkillDest (Cursor)"
 Copy-Tree -Source $skillSrc -Destination $cursorSkillDest
 
+$mcpBridgeSrc = Join-Path $argoDir 'mcp-bridges'
+$mcpBridgeDest = Join-Path $CursorMcpBridgesRoot ''
+Write-Host "  argo\mcp-bridges -> $mcpBridgeDest (Cursor graph-mcp stdio bridge)"
+Copy-Tree -Source $mcpBridgeSrc -Destination $mcpBridgeDest
+
 $openCodeSkillDest = Join-Path $OpenCodeSkillsRoot 'argo-init'
 Write-Host "[8/22] argo\skills\argo-init -> $openCodeSkillDest (OpenCode)"
 Copy-Tree -Source $skillSrc -Destination $openCodeSkillDest
@@ -973,9 +979,10 @@ if ($SkipMcp) {
     # graph-mcp is a Streamable HTTP remote MCP endpoint. Its config shape is
     # HOST-SPECIFIC (each host's mcp.json schema is different):
     #   - OpenCode  (opencode.json mcp.<name>): {type: remote, url, enabled}
-    #   - Cursor    (mcp.json mcpServers.<name>): {url} — official remote
-    #     entries carry no `type` (type only means "stdio" for local servers);
-    #     Cursor dials url servers over Streamable HTTP.
+    #   - Cursor    (mcp.json mcpServers.<name>): stdio bridge — Cursor dials
+    #     remote url servers over SSE GET /mcp, which the Streamable HTTP
+    #     endpoint answers with 404, so graph-mcp is exposed as a local stdio
+    #     bridge (graph-mcp-stdio.js) that forwards to the remote over POST.
     #   - VS Code   (mcp.json servers.<name>): {type: http, url}
     #   - OpenClaw  (openclaw.json mcp.servers.<name>): {url, transport:
     #     streamable-http} — keyed by transport, not by a type alias.
@@ -986,8 +993,14 @@ if ($SkipMcp) {
         url     = $GraphMcpUrl
         enabled = $true
     }
+    $graphMcpBridgePath = (Join-Path $CursorMcpBridgesRoot 'graph-mcp-stdio.js').Replace('\', '/')
     $graphMcpCursor = [ordered]@{
-        url = $GraphMcpUrl
+        type    = 'stdio'
+        command = 'node'
+        args    = @($graphMcpBridgePath)
+        env     = [ordered]@{
+            GRAPH_MCP_URL = $GraphMcpUrl
+        }
     }
     $graphMcpVSCode = [ordered]@{
         type = 'http'
@@ -1015,6 +1028,7 @@ if ($SkipMcp) {
         args    = @($argoServer)
     }) -ExtraServers ([ordered]@{ 'graph-mcp' = $graphMcpCursor })
     Write-Host "argo MCP config written -> $CursorMcpPath"
+    Write-Host "  graph-mcp registered as stdio bridge -> $graphMcpBridgePath"
 
     Write-Host '==> Registering argo MCP server in OpenCode'
     Write-McpConfig -Path $OpenCodeConfigPath -ServersKey 'mcp' -ServerConfig ([ordered]@{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgraph-argo",
-  "version": "0.10.50",
+  "version": "0.10.52",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {
@@ -12,6 +12,7 @@
     "argo/defaults",
     "argo/agents",
     "argo/plugins",
+    "argo/mcp-bridges",
     "argo/skills/argo-init",
     "argo/rules",
     "argo/package.json",