CSDb Data Model 26 MCP Tools

CSDb Data Model & 26 MCP Tools

This page provides a detailed technical reference for the Claude Sleuth Database (CSDb), the persistent intelligence layer for the Claude Sleuth toolkit. CSDb is implemented as a Cloudflare Workers MCP server backed by a D1 SQLite database, providing cross-session persistence and referential integrity for all investigative data.

1. D1 Relational Schema

The CSDb schema is designed to support the POLE (Persons, Objects, Locations, Events) data model and the Admiralty 6x6 source grading framework. All data is strictly scoped to an investigation_id to ensure multi-tenant isolation.

Core Entity-Relationship Model

The following diagram illustrates the primary tables and their foreign key relationships within the D1 instance (sleuth-db).

Diagram: CSDb Relational Schema

erDiagram
    investigations ||--o{ entities : "contains"
    investigations ||--o{ relationships : "contains"
    investigations ||--o{ source_grades : "contains"
    investigations ||--o{ timeline_events : "contains"
    investigations ||--o{ locations : "contains"
    investigations ||--o{ evidence_register : "contains"
    investigations ||--|| progress : "tracks"
    investigations ||--|| notebook : "persists"

    investigations {
        text id PK
        text name
        text status "active|paused|closed|archived"
        text created_utc
    }

    entities {
        text id PK
        text investigation_id FK
        text type "person|org|location|etc"
        text name
        text aliases "JSON array"
        text identifiers "JSON object"
        text attributes "JSON object"
        text source_grade "Admiralty 6x6"
    }

    relationships {
        text id PK
        text investigation_id FK
        text source_entity
        text target_entity
        text type
        real weight
        real confidence
    }

    timeline_events {
        text id PK
        text investigation_id FK
        text utc_datetime
        text description
        text category "comm|mov|fin|etc"
    }

Loading

Table Definitions

• investigations: The root container for all case data.
• entities: Stores POLE entities with support for aliases and structured identifiers (e.g., Passport, LEI).
• relationships: Directed or undirected links between entities, including confidence weights and temporal bounds.
• source_grades: Implementation of the Admiralty 6x6 system (Reliability A-F, Credibility 1-6).
• timeline_events: Normalized chronological data for matrix construction.
• locations: Geospatial data points linked to entities or events.
• evidence_register: Metadata for preserved artefacts, including SHA-256 hashes for chain of custody.
• progress & notebook: Persistence for the task_runner.py state and the analyst's working notes.

---

2. The 26 MCP Tools

The CSDb MCP server exposes 26 tools to the Claude interface, categorized by their functional domain. These tools allow the LLM to perform CRUD operations on the underlying D1 database.

2.1 Investigation Management

Tool	Purpose	Key Inputs
create_investigation	Initializes a new case	name, description
list_investigations	Returns all cases	-
load_investigation	Full state dump for analysis	investigation_id
update_investigation	Modify status or metadata	updates (object)
close_investigation	Marks case as finished	investigation_id
delete_investigation	Permanent removal	confirm (boolean)

2.2 POLE & Relationship Tools

• add_entity: Supports types such as person, organisation, domain, email, and vehicle.
• search_entities: Fuzzy search across names and aliases.
• add_relationship: Links two entities with a specific type (e.g., shareholder_of) and weight.
• get_neighbors: Graph traversal tool to find entities within 1-3 hops of a starting node.

2.3 Specialized Intelligence Tools

• record_grade: Enforces Admiralty 6x6 grading on specific claims.
• add_timeline_event: Categories include communication, movement, financial, and incident.
• add_location: Records coordinates, labels, and observation timestamps.
• register_evidence: Logs SHA-256 hashes and storage locations for preserved files.

2.4 State & Analysis Tools

• save_progress / load_progress: Synchronizes the local .sleuth-progress.json with the remote DB.
• save_notebook / load_notebook: Persists the analyst's markdown-formatted investigation notebook.
• get_statistics: Returns counts of entities, relationships, and events for dashboarding.

---

3. Data Flow & Usage Patterns

CSDb acts as the "Single Source of Truth." Data flows from the analyst (Natural Language) through the MCP tools into the structured Code Entity Space.

Diagram: Data Flow from Natural Language to D1

graph TD
    subgraph "Natural Language Space"
        NL["Analyst: 'Subject X is a director of Company Y'"]
    end

    subgraph "Claude MCP Interface"
        T1["tool: add_entity (Subject X)"]
        T2["tool: add_entity (Company Y)"]
        T3["tool: add_relationship (X -> Y)"]
    end

    subgraph "Code Entity Space (server/worker.js)"
        W["worker.js: handleCallTool()"]
        Q["SQL: INSERT INTO entities/relationships"]
    end

    subgraph "Persistence (Cloudflare D1)"
        D1[("sleuth-db")]
    end

    NL --> T1
    NL --> T2
    NL --> T3
    T1 & T2 & T3 --> W
    W --> Q
    Q --> D1

Loading

Session Protocol

1. Start: The session begins by calling list_investigations to find the active ID, followed by load_progress and load_notebook to restore context.
2. Execution: As findings are made, tools like add_entity and record_grade are called immediately. IDs returned by the database must be used for all subsequent relationship linking.
3. Analysis: Complex analytical scripts (e.g., network_graph.py) ingest data by calling load_investigation to get the full JSON state.

ID Generation

CSDb uses a prefixed ID system to ensure type clarity during link analysis:

• P- : Person
• O- : Organisation
• L- : Location
• E- : Event

---

4. Implementation Details

Referential Integrity

The database enforces foreign key constraints. An entity cannot be deleted if it is a participant in an existing relationship unless a cascade is triggered. The delete_entity tool is explicitly designed to cascade-remove associated relationships to prevent orphaned links.

Data Integrity Rules

1. Provenance: Every entity and relationship record includes a source and source_grade field. No data should enter the database without an Admiralty 6x6 assessment.
2. UTC Normalization: All timestamps (created_utc, modified_utc, utc_datetime) are stored in ISO 8601 UTC format to facilitate chronological matrix construction,.

---