feat(mcp): AD4M MCP Server — AI Agent Integration with Dynamic SHACL Tools

.circleci/config.yml

@@ -72,6 +72,9 @@ jobs:
           name: Build deno snapshot
           command: pnpm run build-deno-snapshot
           no_output_timeout: 30m
+      - run:
+          name: Remove stale binaries (self-hosted runner incremental cache)
+          command: rm -f target/release/ad4m target/release/ad4m-executor
       - run:
           name: Build ADAM (without bootstrap languages)
           command: pnpm run build-libs
@@ -138,6 +141,24 @@ jobs:
           command: cd ./tests/js && ./email-verification-test-with-setup.sh
           no_output_timeout: 30m
 
+  integration-tests-mcp:
+    machine: true
+    resource_class: coasys/marvin
+    steps:
+      - setup_integration_test_environment
+      - run:
+          name: Kill any orphaned executors from previous runs
+          command: |
+            # MCP tests use ports 16000-16002 (mcp-http) and 16010-16012 (mcp-auth)
+            # plus port 3001 (MCP HTTP server). Clear all before starting.
+            for port in 16000 16001 16002 16010 16011 16012 3001; do
+              lsof -ti:$port | xargs -r kill -9 2>/dev/null || true
+            done
+      - run:
+          name: Run MCP integration tests
+          command: cd ./tests/js && pnpm run test-mcp
+          no_output_timeout: 30m
+
   integration-tests-cli:
     machine: true
     resource_class: coasys/marvin
@@ -174,3 +195,6 @@ workflows:
       - integration-tests-email-verification:
           requires:
             - build-and-test
+      - integration-tests-mcp:
+          requires:
+            - build-and-test

.gitignore

@@ -67,3 +67,5 @@ rust-executor/test_data
 .npmrc
 docs-src/
 .worktrees/
+CUSTOM_DENO_SNAPSHOT.bin
+waker-bridge/package-lock.json

cli/src/ad4m_executor.rs

@@ -132,6 +132,10 @@ enum Domain {
         log_holochain_metrics: Option<bool>,
         #[arg(long, action)]
         enable_multi_user: Option<bool>,
+        #[arg(long, action)]
+        enable_mcp: Option<bool>,
+        #[arg(long, action)]
+        mcp_port: Option<u16>,
     },
     RunLocalHcServices {},
 }
@@ -183,6 +187,8 @@ async fn main() -> Result<()> {
         tls_port,
         log_holochain_metrics,
         enable_multi_user,
+        enable_mcp,
+        mcp_port,
     } = args.domain
     {
         let tls = if tls_cert_file.is_some() && tls_key_file.is_some() {
@@ -221,6 +227,8 @@ async fn main() -> Result<()> {
                 log_holochain_metrics,
                 enable_multi_user,
                 smtp_config: None,
+                enable_mcp,
+                mcp_port,
             })
             .await;
         })

cli/src/dev.rs

@@ -57,6 +57,8 @@ pub async fn run(command: DevFunctions) -> Result<()> {
                     tls: None,
                     log_holochain_metrics: None,
                     enable_multi_user: None,
+                    enable_mcp: None,
+                    mcp_port: None,
                     smtp_config: None,
                 })
                 .await
@@ -211,6 +213,8 @@ pub async fn run(command: DevFunctions) -> Result<()> {
                     tls: None,
                     log_holochain_metrics: None,
                     enable_multi_user: None,
+                    enable_mcp: None,
+                    mcp_port: None,
                     smtp_config: None,
                 })
                 .await

cli/src/main.rs

@@ -158,7 +158,11 @@ enum Domain {
         #[arg(long, action)]
         admin_credential: Option<String>,
         #[arg(long, action)]
-        enable_multi_user: bool
+        enable_multi_user: bool,
+        #[arg(long, action)]
+        enable_mcp: Option<bool>,
+        #[arg(long, action)]
+        mcp_port: Option<u16>,
     },
     RunLocalHcServices {},
     Eve {
@@ -236,7 +240,9 @@ async fn main() -> Result<()> {
         hc_bootstrap_url,
         connect_holochain,
         admin_credential,
-        enable_multi_user
+        enable_multi_user,
+        enable_mcp,
+        mcp_port,
     } = args.domain
     {
         let _ = tokio::spawn(async move {
@@ -257,6 +263,8 @@ async fn main() -> Result<()> {
                 connect_holochain,
                 admin_credential,
                 enable_multi_user,
+                enable_mcp,
+                mcp_port,
                 localhost: None,
                 auto_permit_cap_requests: None,
                 tls: None,

docs-src/pages/_meta.json

@@ -9,6 +9,7 @@
     "type": "separator",
     "title": "Core Concepts"
   },
+  "spanning-layer": "The Spanning Layer",
   "auth": "Authentication",
   "agents": "Agents",
   "languages": "Languages",

docs-src/pages/developer-guides/_meta.json

@@ -4,5 +4,6 @@
     "hooks": "Hooking up models to the UI",
     "batch-operations": "Using Batch Operations",
     "ai": "Local AI inference with AD4M",
+    "mcp": "MCP Server (AI Agent Integration)",
     "cli": "Using the AD4M CLI"
 }

docs-src/pages/developer-guides/ai.mdx

@@ -1,5 +1,11 @@
+import { Callout } from "nextra-theme-docs";
+
 # AI in AD4M
 
+<Callout type="info">
+**Looking for AI agent integration?** This page covers running AI models *inside* AD4M. If you want AI agents to *use* AD4M — creating perspectives, managing data, joining neighbourhoods — see the [MCP Server guide](/developer-guides/mcp).
+</Callout>
+
 AD4M provides powerful AI capabilities through both local and remote model inference. This allows you to integrate various AI models into your applications, from language models to embedding models and speech recognition.
 
 ## Overview