feat(cortex): MCP stdio server (--mcp) exposing the semantic graph to LLMs

README.md

@@ -395,6 +395,46 @@ aingle-minimal run --rest-port 19080
 
 ---
 
+## MCP Server
+
+The Cortex exposes the AIngle semantic graph to MCP clients like Claude Code and Claude Desktop over the Model Context Protocol (stdio), letting agents query, write, and verify graph data through tool calls.
+
+### Build
+
+```bash
+cargo build -p aingle_cortex --features "mcp dag" --release
+```
+
+### Client configuration
+
+Add to `claude_desktop_config.json` (Claude Desktop) or `.mcp.json` (Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "aingle": {
+      "command": "aingle-cortex",
+      "args": ["--mcp", "--db", "./data/graph.sled"]
+    }
+  }
+}
+```
+
+Replace `--db <path>` with `--memory` for an ephemeral, in-memory graph.
+
+### Available tools
+
+- `aingle_ping` — liveness check
+- `aingle_query_pattern` — query the semantic graph by triple pattern
+- `aingle_graph_stats` — graph statistics
+- `aingle_create_triple` — insert a triple (write)
+- `aingle_verify_proof` — verify a zero-knowledge proof (returns `valid: false` for invalid proofs)
+- `aingle_dag_history` — signed DAG provenance history of a subject (requires the `dag` feature)
+
+> stdout is reserved for the JSON-RPC stream; logs are written to stderr.
+
+---
+
 ## Contributing
 
 We welcome contributions from the community.

crates/aingle_cortex/Cargo.toml

@@ -22,6 +22,7 @@ p2p = ["dep:quinn", "dep:rustls", "dep:rcgen", "dep:ed25519-dalek", "dep:hex"]
 p2p-mdns = ["p2p", "dep:mdns-sd", "dep:if-addrs"]
 cluster = ["p2p", "dep:aingle_wal", "dep:aingle_raft", "dep:openraft", "dep:tokio-rustls", "dep:rustls-pemfile"]
 dag = ["cluster", "aingle_graph/dag", "aingle_graph/dag-sign", "aingle_raft/dag"]
+mcp = ["dep:rmcp", "dep:schemars"]
 full = ["rest", "graphql", "sparql", "auth", "dag"]
 
 [[bin]]
@@ -47,6 +48,10 @@ async-graphql-axum = { version = "8.0.0-rc", optional = true }
 # SPARQL (optional)
 spargebra = { version = "0.4", optional = true }
 
+# MCP server (optional) — Model Context Protocol over stdio
+rmcp = { version = "1.7", features = ["server", "transport-io", "macros"], optional = true }
+schemars = { version = "1.0", optional = true }
+
 # Authentication (optional)
 jsonwebtoken = { version = "10", features = ["rust_crypto"], optional = true }
 argon2 = { version = "0.5", optional = true }
@@ -111,3 +116,6 @@ if-addrs = { version = "0.13", optional = true }
 tempfile = "3.26"
 reqwest = { version = "0.12", features = ["json"] }
 tokio-test = "0.4"
+# Enable the rmcp `client` feature for the in-process MCP integration test.
+# This is dev-only; the production `mcp` feature uses the server side only.
+rmcp = { version = "1.7", features = ["client", "transport-io"] }

crates/aingle_cortex/src/lib.rs

@@ -164,21 +164,24 @@
 #[cfg(feature = "auth")]
 pub mod auth;
 pub mod client;
+#[cfg(feature = "cluster")]
+pub mod cluster_init;
 pub mod error;
-pub mod wasm_types;
 #[cfg(feature = "graphql")]
 pub mod graphql;
+#[cfg(feature = "mcp")]
+pub mod mcp;
 pub mod middleware;
+#[cfg(feature = "p2p")]
+pub mod p2p;
 pub mod proofs;
 pub mod rest;
 pub mod server;
+pub mod service;
 #[cfg(feature = "sparql")]
 pub mod sparql;
 pub mod state;
-#[cfg(feature = "p2p")]
-pub mod p2p;
-#[cfg(feature = "cluster")]
-pub mod cluster_init;
+pub mod wasm_types;
 
 pub use client::{CortexClientConfig, CortexInternalClient};
 pub use error::{Error, Result};

crates/aingle_cortex/src/main.rs

@@ -6,17 +6,27 @@
 //! REST/GraphQL/SPARQL interface for AIngle semantic graphs.
 
 use aingle_cortex::{CortexConfig, CortexServer};
-use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};
+use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt, Layer};
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // In MCP mode, stdout is reserved for the JSON-RPC stream, so all logging
+    // must be redirected to stderr. Detect the flag before subscriber init.
+    let mcp_mode = std::env::args().any(|a| a == "--mcp");
+
     // Initialize logging
+    let filter = tracing_subscriber::EnvFilter::try_from_default_env()
+        .unwrap_or_else(|_| "aingle_cortex=info,tower_http=debug".into());
+    let fmt_layer = if mcp_mode {
+        tracing_subscriber::fmt::layer()
+            .with_writer(std::io::stderr)
+            .boxed()
+    } else {
+        tracing_subscriber::fmt::layer().boxed()
+    };
     tracing_subscriber::registry()
-        .with(
-            tracing_subscriber::EnvFilter::try_from_default_env()
-                .unwrap_or_else(|_| "aingle_cortex=info,tower_http=debug".into()),
-        )
-        .with(tracing_subscriber::fmt::layer())
+        .with(filter)
+        .with(fmt_layer)
         .init();
 
     // Parse command line arguments
@@ -61,6 +71,9 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
             "--memory" => {
                 config.db_path = Some(":memory:".to_string());
             }
+            "--mcp" => {
+                config.mcp_mode = true;
+            }
             "--flush-interval" => {
                 if i + 1 < args.len() {
                     config.flush_interval_secs = args[i + 1].parse().unwrap_or(300);
@@ -76,6 +89,14 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         i += 1;
     }
 
+    // If --mcp was requested but the binary was built without the `mcp` feature,
+    // fail loudly instead of silently falling through to the TCP REST server.
+    #[cfg(not(feature = "mcp"))]
+    if config.mcp_mode {
+        eprintln!("error: --mcp requires building with the `mcp` feature: cargo build -p aingle_cortex --features mcp");
+        std::process::exit(2);
+    }
+
     // Parse P2P flags (feature-gated at compile time).
     #[cfg(feature = "p2p")]
     let p2p_config = {
@@ -159,6 +180,14 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         aingle_cortex::cluster_init::ensure_dag_ready(server.state_mut(), db_path.as_deref()).await;
     }
 
+    // MCP mode: serve over stdio instead of binding a TCP listener.
+    #[cfg(feature = "mcp")]
+    if server.config().mcp_mode {
+        let state = server.state().clone();
+        aingle_cortex::mcp::serve_stdio(state).await?;
+        return Ok(());
+    }
+
     // Spawn periodic flush task if enabled
     if flush_interval_secs > 0 {
         let flush_state = server.state().clone();
@@ -269,6 +298,7 @@ fn print_help() {
     );
     println!("    --memory             Use volatile in-memory storage (no persistence)");
     println!("    --flush-interval <S> Periodic flush interval in seconds (default: 300, 0=off)");
+    println!("    --mcp                Serve MCP over stdio (requires --features mcp)");
     println!("    -V, --version        Print version and exit");
     println!("    --help               Print this help message");
     println!();

crates/aingle_cortex/src/mcp/convert.rs

@@ -0,0 +1,35 @@
+// Copyright 2019-2026 Apilium Technologies OÜ. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0 OR Commercial
+
+//! Map cortex errors into MCP tool errors.
+
+use crate::error::Error;
+use rmcp::model::ErrorData as McpError;
+
+/// Convert a cortex `Error` into an MCP error suitable for a failed tool result.
+///
+/// `InvalidInput` maps to the JSON-RPC `invalid_params` code; every other
+/// variant falls through to `internal_error` carrying the error's display text.
+pub fn to_mcp_error(err: Error) -> McpError {
+    match err {
+        Error::InvalidInput(msg) => McpError::invalid_params(msg, None),
+        other => McpError::internal_error(other.to_string(), None),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn invalid_input_maps_to_invalid_params() {
+        let e = to_mcp_error(Error::InvalidInput("bad".into()));
+        assert_eq!(e.message.as_ref(), "bad");
+    }
+
+    #[test]
+    fn other_maps_to_internal_error() {
+        let e = to_mcp_error(Error::Internal("boom".into()));
+        assert!(e.message.contains("boom"));
+    }
+}

crates/aingle_cortex/src/mcp/mod.rs

@@ -0,0 +1,38 @@
+// Copyright 2019-2026 Apilium Technologies OÜ. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0 OR Commercial
+
+//! Model Context Protocol (MCP) server for AIngle Córtex.
+//!
+//! Exposes the Córtex business-logic layer over MCP via a stdio transport,
+//! so that MCP-capable clients (e.g. Claude Desktop, IDE agents) can interact
+//! with AIngle semantic graphs as tools.
+//!
+//! stdout is reserved for the JSON-RPC stream; all logging must go to stderr.
+
+mod convert;
+mod server;
+
+pub use server::AingleMcp;
+
+use crate::state::AppState;
+
+/// Serves the MCP server over stdio until the client disconnects.
+///
+/// stdout carries the JSON-RPC message stream; logging is expected to be
+/// redirected to stderr by the caller before this is invoked.
+pub async fn serve_stdio(state: AppState) -> crate::error::Result<()> {
+    use rmcp::transport::stdio;
+    use rmcp::ServiceExt;
+
+    let service = AingleMcp::new(state)
+        .serve(stdio())
+        .await
+        .map_err(|e| crate::error::Error::Internal(format!("MCP serve error: {e}")))?;
+
+    service
+        .waiting()
+        .await
+        .map_err(|e| crate::error::Error::Internal(format!("MCP wait error: {e}")))?;
+
+    Ok(())
+}