Skip to main content

qualia_mcp/tools/
graph.rs

1//! MCP tools for Knowledge Graph, SPARQL, Ontologies, and Identifiers.
2//!
3//! Migrated from legacy `mcp_stub_impls.rs` to full working library module.
4//! Designed according to `AGENTS.md` §0-B (<500 lines).
5
6use crate::types::{parse_tool_args, qualia_storage_path, McpSystemError};
7use qualia_core_db::NQuin;
8use serde_json::{json, Value};
9
10/// Helper to serialize quins to N-Triples text without runtime allocations in inner loop.
11pub fn quins_to_ntriples(quins: &[NQuin]) -> String {
12    let mut buf = Vec::new();
13    let _ = qualia_core_db::resolver::format_ntriples_to(quins, &mut buf);
14    String::from_utf8(buf).unwrap_or_default()
15}
16
17/// Serialize a single `NQuin` to JSON.
18pub fn quin_to_json(q: &NQuin) -> Value {
19    json!({
20        "subject": q.subject,
21        "predicate": q.predicate,
22        "object": q.object,
23        "context": q.context,
24        "metadata": q.metadata,
25        "parity": q.parity,
26    })
27}
28
29/// Helper to resolve codebase audit path.
30pub fn resolve_audit_path(path_str: Option<&str>) -> std::path::PathBuf {
31    if let Some(p) = path_str {
32        if p == "audit" || p == "codebase" {
33            let direct = std::path::PathBuf::from(r"C:\github\qualiaDB\.audit\codebase.q42");
34            if direct.exists() {
35                return direct;
36            }
37            let local = std::path::PathBuf::from(".audit").join("codebase.q42");
38            if local.exists() {
39                return local;
40            }
41        }
42        return std::path::PathBuf::from(p);
43    }
44    std::path::PathBuf::from(r"C:\github\qualiaDB\.audit\codebase.q42")
45}
46
47/// Execute SPARQL range query on a .q42 vault (such as codebase.q42).
48pub fn query_q42_vault(
49    vault: &std::path::Path,
50    query_str: &str,
51    limit: usize,
52) -> Result<Value, McpSystemError> {
53    use qualia_core_db::q42_volume::{
54        LocalFileRangeSource, Q42RangeVolume, MAX_COMPRESSED_SUPERBLOCK_SIZE, SUPERBLOCK_SIZE,
55    };
56    use qualia_core_db::sparql_ast::BindingRow;
57    use qualia_core_db::sparql_executor::{
58        execute_range_triple_select_page_into, Q42RangeTripleSelectCursor,
59        Q42RangeTripleSelectPlan,
60    };
61
62    let (query, ctx) = qualia_core_db::sparql_parser::parse_sparql(query_str)
63        .map_err(|_| McpSystemError::InvalidParameters)?;
64    let plan = qualia_core_db::sparql_planner::QueryPlanner::plan(&query, &ctx)
65        .map_err(|_| McpSystemError::InvalidParameters)?;
66
67    let source = LocalFileRangeSource::open(vault).map_err(|_| McpSystemError::InvalidParameters)?;
68    let root = Q42RangeVolume::open(source).map_err(|_| McpSystemError::InvalidParameters)?;
69    let lexicon = qualia_core_db::q42_lex::Q42Lexicon::load_for_q42(vault).ok();
70
71    let range_plan = Q42RangeTripleSelectPlan::from_execution_plan(&plan)
72        .map_err(|_| McpSystemError::InvalidParameters)?;
73
74    const PAGE_ROWS: usize = 128;
75    let mut compressed = [0u8; MAX_COMPRESSED_SUPERBLOCK_SIZE];
76    let mut decoded = [0u8; SUPERBLOCK_SIZE];
77    let mut quins = [qualia_core_db::NQuin::default(); PAGE_ROWS];
78    let mut rows = [BindingRow::default(); PAGE_ROWS];
79    let mut cursor = Q42RangeTripleSelectCursor::default();
80    let mut results = Vec::new();
81
82    while results.len() < limit {
83        let page = execute_range_triple_select_page_into(
84            &root,
85            range_plan,
86            &ctx,
87            cursor,
88            &mut compressed,
89            &mut decoded,
90            &mut quins,
91            &mut rows,
92        )
93        .map_err(|_| McpSystemError::ParseError)?;
94
95        for row in &rows[..page.returned] {
96            let mut row_obj = serde_json::Map::new();
97            for (slot_idx, slot) in row.slots.iter().enumerate() {
98                if let Some(v) = slot {
99                    let val_str = lexicon
100                        .as_ref()
101                        .and_then(|l| l.lookup(*v))
102                        .map(|s| s.to_string())
103                        .unwrap_or_else(|| format!("0x{v:016x}"));
104                    row_obj.insert(format!("?v{slot_idx}"), Value::String(val_str));
105                }
106            }
107            results.push(Value::Object(row_obj));
108            if results.len() >= limit {
109                break;
110            }
111        }
112
113        match page.next_cursor {
114            Some(next) => cursor = next,
115            None => break,
116        }
117    }
118
119    Ok(json!({
120        "vault": vault.display().to_string(),
121        "returned": results.len(),
122        "bindings": results,
123    }))
124}
125
126/// `query_sparql` tool — executes SPARQL queries against live in-memory daemon graph or a .q42 vault (e.g. codebase.q42).
127pub fn query_sparql(args: &[u8]) -> Result<String, McpSystemError> {
128    let v = parse_tool_args(args)?;
129    let query = v.get("query").and_then(Value::as_str).unwrap_or("");
130    if query.is_empty() {
131        return Err(McpSystemError::InvalidParameters);
132    }
133    let limit = v.get("limit").and_then(|x| x.as_u64()).unwrap_or(1_000) as usize;
134
135    let vault_opt = v
136        .get("vault_path")
137        .or_else(|| v.get("q42_path"))
138        .and_then(Value::as_str);
139
140    if let Some(v_path) = vault_opt {
141        let resolved = resolve_audit_path(Some(v_path));
142        let result = query_q42_vault(&resolved, query, limit)?;
143        return serde_json::to_string(&result).map_err(|_| McpSystemError::ParseError);
144    }
145
146    let graph = qualia_core_db::daemon_graph::graph_read_guard();
147    let (stats, results) = qualia_core_db::daemon_query::execute_query_on_graph(query, graph.as_slice())
148        .map_err(|e| match e {
149            qualia_core_db::daemon_query::QueryExecError::EmptyQuery
150            | qualia_core_db::daemon_query::QueryExecError::ParseError(_)
151            | qualia_core_db::daemon_query::QueryExecError::InvalidProgram => {
152                McpSystemError::InvalidParameters
153            }
154            qualia_core_db::daemon_query::QueryExecError::OutputBufferFull => McpSystemError::ParseError,
155            qualia_core_db::daemon_query::QueryExecError::ClassifiedEgress => {
156                McpSystemError::SanctuaryGateTriggered
157            }
158        })?;
159
160    let truncated = results.len().min(limit);
161    let payload = json!({
162        "query": query,
163        "matchCount": stats.match_count,
164        "returned": truncated,
165        "stats": {
166            "vmCycles": stats.vm_cycles,
167            "directJumpOps": stats.direct_jump_ops,
168            "lexiconLookupOps": stats.lexicon_lookup_ops,
169            "matchCount": stats.match_count,
170        },
171        "ntriples": quins_to_ntriples(&results[..truncated]),
172        "quins": results[..truncated].iter().map(quin_to_json).collect::<Vec<_>>(),
173    });
174    serde_json::to_string(&payload).map_err(|_| McpSystemError::ParseError)
175}
176
177/// `get_graph_stats` tool — returns resident daemon-graph quin count, capacity, and utilization.
178pub fn get_graph_stats(_args: &[u8]) -> Result<String, McpSystemError> {
179    let count = qualia_core_db::daemon_graph::graph_quin_count();
180    let capacity = qualia_core_db::daemon_graph::MAX_GRAPH_QUINS;
181    let payload = json!({
182        "quinCount": count,
183        "capacity": capacity,
184        "utilization": if capacity > 0 {
185            (count as f64) / (capacity as f64)
186        } else {
187            0.0
188        },
189        "empty": count == 0,
190    });
191    serde_json::to_string(&payload).map_err(|_| McpSystemError::ParseError)
192}
193
194/// `list_ontologies` tool — lists startup ontology catalog entries and on-disk presence.
195pub fn list_ontologies(_args: &[u8]) -> Result<String, McpSystemError> {
196    let dir = qualia_core_db::ontology_loader::ontology_dir_path();
197    let mut entries = Vec::new();
198    for (filename, context_hash) in qualia_core_db::ontology_loader::startup_ontology_catalog() {
199        let present = dir
200            .as_ref()
201            .map(|d| d.join(filename).is_file())
202            .unwrap_or(false);
203        entries.push(json!({
204            "filename": filename,
205            "contextHash": context_hash,
206            "present": present,
207        }));
208    }
209    let payload = json!({
210        "ontologyDir": dir.map(|p| p.display().to_string()).unwrap_or_default(),
211        "entries": entries,
212        "graphQuinCount": qualia_core_db::daemon_graph::graph_quin_count(),
213    });
214    serde_json::to_string(&payload).map_err(|_| McpSystemError::ParseError)
215}
216
217/// `ingest_ontology` tool — ingests RDF Turtle triples from a file or inline content into the daemon graph.
218pub fn ingest_ontology(args: &[u8]) -> Result<String, McpSystemError> {
219    let v = parse_tool_args(args)?;
220    let context_hash = v.get("context_hash").and_then(Value::as_u64).unwrap_or(0);
221
222    let (quins, path_str) = if let Some(path_str) = v.get("path").and_then(Value::as_str) {
223        let p = std::path::Path::new(path_str);
224        let ctx = if context_hash == 0 {
225            qualia_core_db::q_hash(path_str)
226        } else {
227            context_hash
228        };
229        let q = if p.extension().and_then(|s| s.to_str()) == Some("q42") {
230            qualia_core_db::ontology_loader::load_q42_file(p)
231        } else {
232            qualia_core_db::ontology_loader::parse_ttl_to_quins(p, ctx)
233        };
234        (q, path_str.to_string())
235    } else if let Some(content) = v.get("content").and_then(Value::as_str) {
236        let ctx = if context_hash == 0 {
237            qualia_core_db::q_hash("urn:inline:ontology")
238        } else {
239            context_hash
240        };
241        use rio_api::parser::TriplesParser;
242        let mut quins = Vec::new();
243        let mut parser = rio_turtle::TurtleParser::new(content.as_bytes(), None);
244        let _ = parser.parse_all(&mut |t: rio_api::model::Triple| -> Result<(), std::io::Error> {
245            let s = qualia_core_db::q_hash(&t.subject.to_string());
246            let p = qualia_core_db::q_hash(&t.predicate.to_string());
247            let o = qualia_core_db::q_hash(&t.object.to_string());
248            quins.push(qualia_core_db::NQuin {
249                subject: s,
250                predicate: p,
251                object: o,
252                context: ctx,
253                metadata: 0,
254                parity: s ^ p ^ o ^ ctx,
255            });
256            Ok(())
257        });
258        (quins, "inline".to_string())
259    } else {
260        return Err(McpSystemError::InvalidParameters);
261    };
262
263    let count_before = qualia_core_db::daemon_graph::graph_quin_count();
264    let ingested = quins.len();
265    qualia_core_db::daemon_graph::extend_with_ontology_quins_slice(&quins);
266    let count_after = qualia_core_db::daemon_graph::graph_quin_count();
267
268    let payload = json!({
269        "path": path_str,
270        "ingestedQuins": ingested,
271        "graphCountBefore": count_before,
272        "graphCountAfter": count_after,
273        "success": true,
274    });
275    serde_json::to_string(&payload).map_err(|_| McpSystemError::ParseError)
276}
277
278/// `get_did_info` tool — resolves a `did:q42:...` identifier into its topological pointer hash and bit flags.
279pub fn get_did_info(args: &[u8]) -> Result<String, McpSystemError> {
280    let v = parse_tool_args(args)?;
281    let did = v.get("did").and_then(Value::as_str).unwrap_or("");
282    if !did.starts_with("did:q42:") {
283        return Err(McpSystemError::InvalidParameters);
284    }
285
286    let parsed_hash = qualia_core_db::identifier::parse_did_q42(did.as_bytes())
287        .map_err(|_| McpSystemError::InvalidParameters)?;
288    let msb_set = (parsed_hash >> 63) == 1;
289
290    let payload = json!({
291        "did": did,
292        "hash": parsed_hash,
293        "hex": format!("0x{:016x}", parsed_hash),
294        "msbSet": msb_set,
295        "isTopologicalPointer": msb_set,
296    });
297    serde_json::to_string(&payload).map_err(|_| McpSystemError::ParseError)
298}
299
300/// `get_wallet_status` tool — inspects queued Interledger Protocol (ILP) micropayments.
301pub fn get_wallet_status(_args: &[u8]) -> Result<String, McpSystemError> {
302    let log_path = qualia_storage_path().join("pending_payments.ndjson");
303    let mut pending_count = 0;
304    let mut total_amount_drops = 0u64;
305
306    if let Ok(content) = std::fs::read_to_string(&log_path) {
307        for line in content.lines() {
308            if let Ok(record) = serde_json::from_str::<Value>(line) {
309                pending_count += 1;
310                if let Some(amt) = record.get("amount").and_then(Value::as_u64) {
311                    total_amount_drops += amt;
312                }
313            }
314        }
315    }
316
317    let payload = json!({
318        "pendingPaymentsCount": pending_count,
319        "totalAmountDrops": total_amount_drops,
320        "journalPath": log_path.display().to_string(),
321        "status": if pending_count > 0 { "unsettled" } else { "settled" },
322    });
323    serde_json::to_string(&payload).map_err(|_| McpSystemError::ParseError)
324}
325
326/// `codebase_audit` tool — fast query into the C:\github\qualiaDB\.audit\codebase.q42 database.
327/// Supports inspecting functions, signatures, methods, and files across the entire QualiaDB ecosystem.
328pub fn codebase_audit(args: &[u8]) -> Result<String, McpSystemError> {
329    let v = parse_tool_args(args)?;
330    let limit = v.get("limit").and_then(|x| x.as_u64()).unwrap_or(25) as usize;
331    let vault_str = v.get("vault_path").and_then(Value::as_str);
332    let vault = resolve_audit_path(vault_str);
333
334    let custom_query = v.get("query").and_then(Value::as_str);
335    let query_str = if let Some(q) = custom_query {
336        q.to_string()
337    } else {
338        format!("SELECT ?fn ?sig WHERE {{ ?fn <https://audit.dev/ns#signature> ?sig }} LIMIT {limit}")
339    };
340
341    let result = query_q42_vault(&vault, &query_str, limit)?;
342    serde_json::to_string(&result).map_err(|_| McpSystemError::ParseError)
343}
344