Purple8 — AI-Native Application Backend MCP Server

Create a directed edge (relationship) between two existing nodes. This is the primary agentic handoff mechanism — agents write their output as edges (e.g. DERIVED_FROM, RISK_ASSESSMENT, EXTRACTED_FROM) so downstream agents can discover work by querying graph state rather than passing messages. edge_id is auto-generated (UUID4) when omitted. Requires editor role.

Insert a new node into the graph (accepts `type`, `label`, or `node_type`). Requires editor role.

Idempotently assert one native RDF quad with exact lexical terms, explicit blank-node scope and optional graph name. Uses existing node/edge create and read permissions, record policies and API-key label restrictions. No bulk import or caller-supplied metadata.

Return the total number of nodes in the graph, optionally filtered by label. A cheap situational-awareness call an agent can make before deciding how to query or ingest.

Retrieve a node and all its stored properties by ID.

Combine vector similarity with graph traversal for highest-recall retrieval. Best when graph structure matters.

List every node type (label) in the graph with how many nodes carry it, largest first. Cheap — O(types), not O(nodes). Call this first to learn what the graph contains (e.g. Person, Account, Invoice) before querying or filtering by label.

Execute a Cypher query against the Purple8 knowledge graph and return matching records. Use for nodes, edges, paths, or aggregated data.

Read-only indexed RDF/LPG pattern query with policy-filtered evidence. Use tagged rdf, lpg and lpg_edge patterns. Returns unified bindings and evidence or, with output_format=nquads, a JSON envelope containing selected asserted N-Quads and selection metadata. Raw work stats are withheld (stats=null). No inferred RDF, writes, import, or whole-corpus export. Existing read permissions apply; N-Quads additionally requires data:export.

Walk the graph from a starting node following edges up to a given depth.

Update properties or labels on an existing node. Properties are merged with existing values (patch semantics — only the keys you supply are changed). Labels replace the full label set when provided. Use this to advance agent relay state, e.g. setting {"status": "enriched", "handoff_to": null} to hand off work to the next agent in a relay pipeline. Requires editor role.

Find the k nearest nodes to a natural-language query using the HNSW vector index.

Advance a journey instance to the next stage. Actor and notes are written to the audit trail as an ADVANCED_TO edge. Requires editor role.

Define a new journey type (workflow template) with ordered stages, owner systems, and per-stage SLA policies. Once defined, instances can be started with journey.start. Call this first when building any new workflow — the agent can define the entire process in one call. Use overwrite=true to update an existing definition. Requires journey:admin permission (admin or super_admin by default). Use operation=configure_ai with ai_enabled to persistently enable/disable this tenant's advisor. Generation uses tenant LLM settings; delivery is currently best-effort.

List journey instances with optional filters. Use this to discover what is in flight, find instances for a specific entity, or check all instances of a given type. Also returns all defined journey types when called with no arguments. Essential for any agent monitoring or orchestrating workflows. Set runtime_status=true to inspect this tenant's advisor enablement, provider readiness and delivery guarantees.

List pending Human-In-The-Loop (HITL) tasks — decisions that require a human (or agent acting as human proxy) to approve, reject, or escalate before the journey can continue. Returns task ID, title, assigned role, description, and the stage the journey is waiting on. An agent can use this to surface pending decisions to the user or take autonomous action if authorised.

Resolve a Human-In-The-Loop (HITL) task — approve, reject, or escalate it. On approval the journey automatically advances to the next stage if advance_to_stage is set. The decision is written to the immutable graph audit trail with the actor and timestamp. An AI agent acting as a human proxy must set actor to the user or role it is acting on behalf of. Requires editor role.

Create a new Journey Engine instance for an entity and move it to the first stage. All transitions are recorded as immutable graph edges. Requires editor role.

Return the full state and audit trail for a journey instance — every stage transition, AI recommendation, and HITL decision.

Commit a reviewed extraction or your own extractor's output without invoking DocIntel. Uses the complete POST /ingest/commit contract: entities, relationships, Markdown, spans, tables/pages, context, file_ref or inline file_bytes_b64 and ingestion options. Existing entities are linked, not edited, unless update_entities=true. For extractor-generated IDs use identity_policy='review_conflicts': name matches alone are not identity proof. On entity_identity_conflict nothing was written; correct/exclude the incoming entity and update relationship endpoints, or explicitly confirm identity_resolution='link_existing', then retry. link_existing never edits existing facts. After interruption or a lost response, ask the user to confirm retrying the retained reviewed payload. Reuse entity IDs, assertion keys and file_ref; do not automatically re-extract. Retain metadata.sha256 (original bytes) and optional metadata.file_version. On source_version_conflict nothing was written: obtain and review current-source extraction and ask for confirmation, rather than replaying or relabeling the old review. SIMILAR_TO edges (enabled by default) are similarity, not factual assertions. Inspect embedding, document_chunks, structured_content and original_file outcomes; a successful write alone does not guarantee retrieval readiness. Requires editor role.

Send a document file (PDF, DOCX, PPTX, XLSX, HTML, IFC, CSV, …) to Purple8 DocIntel for parsing, entity extraction, and graph ingestion. The document is fetched by DocIntel from a public URL, not a local path. The complete extraction is committed only when finished successfully. auto_commit=false returns a review-only preview; pending jobs return job_id for resumption. URL extraction does not retain original bytes in Graph; supply file_ref or commit an original separately. Use this when the knowledge source is a document rather than raw text. Requires editor role and DocIntel to be running. After an interrupted write, ask the user to confirm a retry; use data.commit with the retained reviewed payload instead of re-extracting.

Extract entities and relationships from raw text and write them into the graph. Calls preview first, then commits the complete extraction on success. auto_commit=false returns a review-only preview. Pending jobs return job_id for resumption. Original bytes are not stored automatically; supply file_ref or use data.commit with file_bytes_b64 if needed. After an interrupted write, ask the user to confirm a retry; use data.commit with the retained reviewed payload instead of re-extracting. Requires editor role.

Hybrid Graph-Vector RAG — fuses vector similarity AND graph structural signals at every stage: dual-seed fusion (Weighted RRF over vector rank + degree centrality), vector-guided BFS, and semantic path scoring. Highest accuracy: MRR 0.85, multi-hop 0.91. ~5x slower (p50 ~240 ms). Recommended as the default RAG tool for agents that need high quality.

Analyse the graph topology and return recommended RAG retrieval settings. Profiles node count, edge density, degree distribution, edge-type distribution, and embedding coverage, then derives concrete values for fusion_alpha, max_hops, seed_k, vector_weight, k, and mode. Call this before tuning rag.hybrid_query on a new corpus or collection. Returns topology_class (sparse/moderate/dense), a 'recommended' param block ready to pass to rag.hybrid_query, and a 'rationale' explaining each choice.

Flat Vector RAG — retrieves the most relevant graph nodes by pure vector similarity (HNSW + RRF fusion + keyword fallback), then calls the configured LLM to generate a grounded answer. Fastest of the three RAG modes (p50 ~45 ms, MRR 0.64); best for single-hop factual questions. Use rag.graph_query or rag.hybrid_query for multi-hop or relationship-heavy questions.

Define a new edge (relationship) type. Constrain which node types may be the source/target, declare edge properties, and set cardinality (one_to_one | one_to_many | many_to_one | many_to_many). Fails 409 if the type already exists.

Define a new node type — the primitive that lets an agent build the data model itself. The type_name becomes the canonical label for nodes of this type. Set app_id to make the type a per-app IAM boundary (only matching API keys may touch its nodes). Declare properties with per-field type / required / enum constraints, and immutable_properties that cannot change after creation. Fails 409 if the type already exists (use schema.update_node_type to change).

Validate the tenant's live graph data against the defined schema. Reports missing required properties, type/enum violations, edge source/target-type violations, and orphan labels (labels present in the graph but undefined in the schema). Returns valid=true with empty violation lists when the graph conforms.