Skip to content

Commit b6d2ab4

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
feat(cartridge): add bofig-mcp (evidence-graph queries)
- Idris2 ABI with evidence types (Document, Interview, Dataset, Analysis, Media, Archive) - Zig FFI with 6 exported functions (query_evidence, search_evidence, get_connections, find_path, execute_query, get_graph_stats) - Deno MCP adapter exposing evidence-graph query tools on ws://127.0.0.1:5178 - Loopback proof pinning: IsLoopback 5178 - Supports path finding, custom queries, and graph analytics for investigative workflows Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
1 parent 303836e commit b6d2ab4

9 files changed

Lines changed: 654 additions & 0 deletions

File tree

‎cartridges/bofig-mcp/.editorconfig‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# SPDX-License-Identifier: PMPL-1.0-or-later
2+
root = true
3+
4+
[*]
5+
charset = utf-8
6+
indent_style = space
7+
indent_size = 2
8+
end_of_line = lf
9+
trim_trailing_whitespace = true
10+
insert_final_newline = true
11+
12+
[*.md]
13+
trim_trailing_whitespace = false

‎cartridges/bofig-mcp/.gitignore‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
*.swp
3+
*.swo
4+
*~
5+
.DS_Store
6+
node_modules/
7+
dist/
8+
build/
9+
target/
10+
.deno
11+
deno.lock

‎cartridges/bofig-mcp/LICENSE‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
SPDX-License-Identifier: PMPL-1.0-or-later
2+
3+
Bofig Cartridge
4+
Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
5+
6+
This software is licensed under the PMPL-1.0-or-later license.
7+
8+
PMPL-1.0-or-later is a license supporting dual licensing with MPL-2.0 as automatic fallback.
9+
For the full license text, see: https://hyperpolymath.dev/standards/PMPL-1.0
10+
11+
Legal Notice:
12+
Until PMPL achieves formal recognition as a standalone license, this software is
13+
automatically operative under the Mozilla Public License 2.0 (MPL-2.0).
14+
15+
This is a legal fallback arrangement confirmed by legal counsel.

‎cartridges/bofig-mcp/README.adoc‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
= Bofig Cartridge
2+
:toc: preamble
3+
:author: Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
4+
:date: 2026-04-25
5+
:spdx: PMPL-1.0-or-later
6+
7+
// SPDX-License-Identifier: PMPL-1.0-or-later
8+
9+
Evidence graph query interface for investigative journalism workflows — search evidence, find connections, analyze relationships in complex networks.
10+
11+
== Features
12+
13+
- **Evidence Queries** — Retrieve evidence by ID with metadata (source, confidence, date)
14+
- **Keyword Search** — Search evidence across documents, interviews, datasets, media
15+
- **Connection Discovery** — Find relationships and connections between entities
16+
- **Path Analysis** — Shortest path finding between entities in the graph
17+
- **Custom Queries** — Execute graph queries (Cypher-like syntax)
18+
- **Graph Analytics** — Get statistics on nodes and edges
19+
20+
== Architecture
21+
22+
[cols="1,3"]
23+
|===
24+
| Component | Purpose
25+
26+
| `abi/Bofig.idr`
27+
| Idris2 interface with evidence types (Document, Interview, Dataset, Analysis, Media, Archive)
28+
and connection/relationship definitions.
29+
30+
| `ffi/bofig_ffi.zig`
31+
| Zig bindings for evidence graph database queries.
32+
33+
| `adapter/mod.ts`
34+
| Deno MCP server exposing evidence-graph tools.
35+
Runs on `127.0.0.1:5178` (loopback only).
36+
37+
| `cartridge.json`
38+
| Tool manifest with 6 MCP tools for evidence analysis.
39+
|===
40+
41+
== MCP Tools
42+
43+
=== `query_evidence`
44+
Retrieve evidence record by ID with full metadata (source type, confidence level, date collected, description).
45+
46+
=== `search_evidence`
47+
Search evidence by keyword across all fields (titles, descriptions, source types, content).
48+
49+
=== `get_connections`
50+
Retrieve all relationships and connections for an entity in the evidence graph.
51+
52+
=== `find_path`
53+
Compute shortest path between two entities, useful for analyzing degrees of separation.
54+
55+
=== `execute_query`
56+
Execute custom graph query using graph query syntax (similar to Cypher).
57+
58+
=== `get_graph_stats`
59+
Retrieve overall statistics: total nodes, total edges, last updated timestamp.
60+
61+
== Integration
62+
63+
Connects to bofig (evidence graph) via:
64+
- **Evidence database** for record storage and retrieval
65+
- **Relationship index** for connection queries
66+
- **Graph algorithms** for path finding and analysis
67+
- **Search engine** for full-text evidence discovery
68+
69+
Loopback proof pinning: `IsLoopback 5178` at compile-time.
70+
71+
== Use Cases
72+
73+
- **Investigative Research** — Discover connections and relationships in complex networks
74+
- **Fact Checking** — Trace evidence chains and corroboration paths
75+
- **Narrative Analysis** — Identify key entities and relationship patterns
76+
- **Story Development** — Build and validate investigative narratives
77+
78+
== License
79+
80+
PMPL-1.0-or-later (MPL-2.0 legal fallback).

‎cartridges/bofig-mcp/abi/Bofig.idr‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
-- SPDX-License-Identifier: PMPL-1.0-or-later
2+
-- Bofig Cartridge ABI — Evidence graph query interface
3+
4+
module ABI.Bofig
5+
6+
%language ElabReflection
7+
8+
-- Evidence source type
9+
public export
10+
data EvidenceSource : Type where
11+
Document : EvidenceSource
12+
Interview : EvidenceSource
13+
DataSet : EvidenceSource
14+
Analysis : EvidenceSource
15+
Media : EvidenceSource
16+
Archive : EvidenceSource
17+
18+
-- Confidence level
19+
public export
20+
data ConfidenceLevel : Type where
21+
High : ConfidenceLevel
22+
Medium : ConfidenceLevel
23+
Low : ConfidenceLevel
24+
Unverified : ConfidenceLevel
25+
26+
-- Evidence record
27+
public export
28+
record Evidence where
29+
constructor MkEvidence
30+
evidenceId : String
31+
title : String
32+
source : EvidenceSource
33+
confidence : ConfidenceLevel
34+
description : String
35+
dateCollected : String
36+
37+
-- Connection/relationship in graph
38+
public export
39+
record Connection where
40+
constructor MkConnection
41+
fromId : String
42+
toId : String
43+
relationshipType : String
44+
strength : Nat -- 0-100
45+
description : String
46+
47+
-- Graph query result
48+
public export
49+
record GraphQueryResult where
50+
constructor MkGraphQueryResult
51+
queryId : String
52+
nodeCount : Nat
53+
edgeCount : Nat
54+
evidence : List Evidence
55+
connections : List Connection
56+
57+
-- Bofig cartridge interface
58+
public export
59+
interface Bofig.Graph where
60+
-- Query evidence by ID
61+
queryEvidence : String -> IO (Maybe Evidence)
62+
63+
-- Search evidence by keyword
64+
searchEvidence : String -> IO (List Evidence)
65+
66+
-- Get connections for an entity
67+
getConnections : String -> IO (List Connection)
68+
69+
-- Find shortest path between two nodes
70+
findPath : String -> String -> IO (List String)
71+
72+
-- Execute graph query
73+
executeQuery : String -> IO GraphQueryResult
74+
75+
-- Get graph statistics
76+
getGraphStats : IO (Nat, Nat) -- (nodes, edges)
77+
78+
-- Loopback proof: cartridge runs on localhost only
79+
IsLoopback : (port : Nat) -> Type
80+
IsLoopback 5178 = ()
81+
82+
public export
83+
Loopback.proof : IsLoopback 5178
84+
Loopback.proof = ()

0 commit comments

Comments
 (0)