MetaOntology OS MCP Server Plugin

Carcinization is the evolutionary tendency for crustaceans to converge on a crab-like body plan. OpenCrab applies the same principle to agent environments: all sufficiently advanced AI systems eventually evolve toward ontology-structured forms.

OpenCrab is an MCP (Model Context Protocol) server that exposes the MetaOntology OS grammar to any OpenClaw-compatible agent environment — Claude Code, n8n, LangGraph, and beyond.

Companion: crabharness/ — a plugin-based mission control plane that plans evidence collection, delegates heavy crawling to Codex workers, validates artifacts through a three-gate pipeline, and emits OpenCrab-ready promotion packages. See CrabHarness README.

• Grammar versioning: GRAMMAR_VERSION = "1.0.0" in every manifest response
• Type Schema Registry: YAML schemas in schemas/types/ — required, enum validation on every node write
• Receipt IDs: every add_node / add_edge returns receipt_id + receipt_ts for provenance

• WorkflowEngine: SQL state machine (pending → running → approved/rejected → completed/failed) with full audit log
• ApprovalEngine: three-state approval queue linked to workflow runs
• CrabHarness promotion-apply: CLI command + MCP tool to apply PromotionPackages inline

• IdentityEngine: alias table + fuzzy duplicate detection — no auto-merge, human review first
• CanonicalizeEngine: tombstone-based node merge — alias nodes preserved, resolve_canonical() for lookups
• PromotionEngine: full extraction lifecycle candidate → validated → promoted | rejected with evidence linking

• BM25 Index: pure Python keyword search over all node properties (no external deps)
• RRF Reranker: Reciprocal Rank Fusion merges vector + BM25 + graph results; BM25 cross-score boosts query-relevant hits
• Policy-aware filtering: pass subject_id to ontology_query and results are filtered by ReBAC view permission

• Tenant isolation: tenant_id context stamped on writes; X-Tenant-Id header support
• Billing hooks: billing_events table tracks node_write / query / ingest / promotion per tenant
• Schema packs: domain bundles (saas, biomedical, legal) installable with one MCP call

Total MCP tools: 30

                        ┌─────────────────────────────────────────────┐
                        │           OpenCrab MCP Server               │
                        │              (stdio JSON-RPC)               │
                        └──────────────────┬──────────────────────────┘
                                           │
              ┌────────────────────────────┼────────────────────────────┐
              │                           │                            │
      ┌───────▼──────┐           ┌────────▼───────┐          ┌────────▼───────┐
      │  grammar/    │           │   ontology/    │          │    stores/     │
      │  manifest.py │           │   builder.py   │          │                │
      │  validator.py│           │   rebac.py     │          │  neo4j_store   │
      │  glossary.py │           │   impact.py    │          │  chroma_store  │
      └──────────────┘           │   query.py     │          │  mongo_store   │
                                 │   identity.py  │          │  sql_store     │
      ┌───────────────┐          │   canonicalize │          └───────┬────────┘
      │  schemas/     │          │   promotion.py │                  │
      │  types/*.yaml │          │   bm25.py      │   ┌─────────────▼──────────┐
      │  packs/*.yaml │          │   reranker.py  │   │       billing/         │
      │  loader.py    │          │   tenant.py    │   │   hooks.py             │
      │  pack_registry│          └────────────────┘   └────────────────────────┘
      └───────────────┘
                                 ┌──────────────────────────────────┐
                                 │         execution/               │
                                 │   workflow.py  approvals.py      │
                                 │   action_registry.py             │
                                 └──────────────────────────────────┘

subject    ──[owns, manages, can_view, can_edit, can_execute, can_approve]──► resource
resource   ──[contains, derived_from, logged_as]──────────────────────────► evidence
evidence   ──[mentions, describes, exemplifies]────────────────────────────► concept
evidence   ──[supports, contradicts, timestamps]───────────────────────────► claim
concept    ──[related_to, subclass_of, part_of, influences, depends_on]────► concept
concept    ──[contributes_to, constrains, predicts, degrades]──────────────► outcome
lever      ──[raises, lowers, stabilizes, optimizes]───────────────────────► outcome
lever      ──[affects]─────────────────────────────────────────────────────► concept
community  ──[clusters, summarizes]────────────────────────────────────────► concept
policy     ──[protects, classifies, restricts]─────────────────────────────► resource
policy     ──[permits, denies, requires_approval]──────────────────────────► subject

docker-compose up -d

This starts Neo4j, MongoDB, PostgreSQL, and ChromaDB.

pip install -e ".[dev]"

opencrab init          # creates .env from template
# Edit .env if your credentials differ from defaults

Local mode (no Docker required):

STORAGE_MODE=local opencrab serve

Local mode uses SQLite + JSON files — no external services needed.

python scripts/seed_ontology.py

opencrab status

claude mcp add opencrab -- opencrab serve

Or add to your .claude/mcp.json manually (see below).

opencrab query "system performance and error rates"
opencrab manifest    # see the full grammar

Add to ~/.claude/mcp.json (or project-level .mcp.json):

{
  "mcpServers": {
    "opencrab": {
      "command": "opencrab",
      "args": ["serve"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "opencrab",
        "MONGODB_URI": "mongodb://root:opencrab@localhost:27017",
        "MONGODB_DB": "opencrab",
        "POSTGRES_URL": "postgresql://opencrab:opencrab@localhost:5432/opencrab",
        "CHROMA_HOST": "localhost",
        "CHROMA_PORT": "8000"
      }
    }
  }
}

Local mode (SQLite + JSON, no Docker):

{
  "mcpServers": {
    "opencrab": {
      "command": "opencrab",
      "args": ["serve"],
      "env": {
        "STORAGE_MODE": "local"
      }
    }
  }
}

Returns the full MetaOntology grammar with version, spaces, meta-edges, impact categories, and ReBAC config.

{
  "space": "subject",
  "node_type": "User",
  "node_id": "user-alice",
  "properties": { "name": "Alice Chen", "role": "analyst" },
  "tenant_id": "acme",
  "subject_id": "user-alice"
}

Returns receipt_id + receipt_ts. Properties validated against type schema if one exists.

{
  "from_space": "subject", "from_id": "user-alice",
  "relation": "owns",
  "to_space": "resource", "to_id": "doc-spec"
}

Validates the (from_space, to_space, relation) triple against the grammar before write.

{
  "question": "What factors degrade system performance?",
  "spaces": ["concept", "outcome"],
  "limit": 10,
  "subject_id": "user-alice",
  "tenant_id": "acme",
  "use_bm25": true,
  "use_rerank": true
}

Pipeline: vector similarity → BM25 keyword → graph expansion → RRF reranking → policy filter.

{ "question": "machine learning", "spaces": ["concept"], "limit": 10 }

BM25-only keyword search. Fast and deterministic, no embeddings.

{ "node_id": "lever-cache-ttl", "change_type": "update" }

Returns triggered I1–I7 impact categories and affected neighbours.

{ "subject_id": "user-alice", "permission": "edit", "resource_id": "ds-events" }

Returns { "granted": true/false, "reason": "...", "path": [...] }.

{ "lever_id": "lever-cache-ttl", "direction": "lowers", "magnitude": 0.7 }

{ "text": "...", "source_id": "incident-2026-01", "metadata": { "space": "evidence" } }

Register alias_id as an alias for canonical_id. Types: name, merge, external.

Resolve a node ID to its canonical form. Returns is_alias: true if it was an alias.

Propose two nodes as potential duplicates for human review.

Accept or reject a pending duplicate candidate. On accept, registers alias automatically.

List all pending duplicate candidates sorted by similarity.

Merge alias_id into canonical_id using tombstone pattern — alias node is preserved.

Find nodes with similar names and auto-propose them as duplicate candidates.

Tracks extracted entities through: candidate → validated → promoted | rejected.

Register an extracted entity as a promotion candidate (not visible in normal queries yet).

Mark a candidate as validated — ready for final review.

Promote to promoted status. Optionally links evidence nodes via supports edges.

Mark a candidate as rejected with an optional reason.

Start an auditable workflow run in pending state before executing any sensitive action.

Advance a run to a new status (pending → running → approved/rejected → completed/failed).

Submit an approval request linked to a workflow run.

{ "package": { ... }, "dry_run": false }

Apply a CrabHarness PromotionPackage inline. Returns receipt_id + receipt_ts per node/edge written. Use dry_run: true to validate without writing.

{ "tenant_id": "acme", "event_type": "query", "since": "2026-04-01T00:00:00Z" }

Aggregated usage counts by event type for a tenant.

Recent raw billing events for a tenant (last N).

Domain-specific schema bundles that extend the type registry without touching core schemas.

List available packs with install status. Built-in packs: saas, biomedical, legal.

{ "name": "biomedical" }

Generates stub YAML type schemas in schemas/types/. Existing user schemas are never overwritten.

{ "name": "biomedical", "force": false }

opencrab init              Create .env from template
opencrab serve             Start MCP server (stdio)
opencrab status            Check store connections
opencrab ingest <path>     Ingest files into vector store
opencrab query <question>  Run a hybrid query
opencrab manifest          Print MetaOntology grammar

Global flags:

opencrab --version
opencrab query --json-output <q>
opencrab manifest --json-output
opencrab ingest -r <dir>
opencrab ingest -e .txt,.md <dir>

Every node and edge can carry orthogonal metadata attributes:

make dev-install    # install with dev extras
make up             # start docker services
make seed           # seed example data
make test           # run test suite
make coverage       # test + coverage report
make lint           # ruff linter
make format         # black + isort
make status         # check store connections

OPENCRAB_INTEGRATION=1 pytest tests/ -v

opencrab/
├── grammar/          # MetaOntology grammar (manifest, validator, glossary)
├── schemas/          # Type schemas (YAML), schema packs, loader
│   ├── types/        # Per-node-type YAML schemas (required/enum validation)
│   └── packs/        # Domain packs: saas, biomedical, legal
├── ontology/         # Core engines
│   ├── builder.py    # Node/edge write with receipt IDs + schema validation
│   ├── query.py      # Hybrid query: vector + BM25 + graph + RRF reranker
│   ├── bm25.py       # Pure Python BM25 index
│   ├── reranker.py   # RRF + BM25 cross-score fusion
│   ├── identity.py   # Alias table + duplicate candidate detection
│   ├── canonicalize.py # Tombstone-based node merge
│   ├── promotion.py  # Extraction lifecycle (candidate → promoted)
│   ├── tenant.py     # Tenant isolation context + property stamping
│   ├── rebac.py      # Relationship-based access control
│   └── impact.py     # I1–I7 impact analysis
├── execution/        # Workflow & approvals runtime
│   ├── workflow.py   # WorkflowEngine state machine
│   ├── approvals.py  # ApprovalEngine queue
│   └── action_registry.py # YAML action schemas
├── billing/          # Usage metering
│   └── hooks.py      # BillingHooks — billing_events table
├── stores/           # Store adapters (Neo4j, ChromaDB, MongoDB, PostgreSQL, Local)
└── mcp/              # MCP server (stdio JSON-RPC) + 30 tool definitions
tests/                # Test suite
scripts/              # Seed script
crabharness/          # Evidence collection pipeline
docker-compose.yml    # All data services

crabharness/ is the companion data collection pipeline for OpenCrab. It owns the "how do we get the evidence that fills the ontology" layer, while OpenCrab owns the "how is the ontology structured and queried" layer.

cd crabharness
pip install -e .
crabharness catalog
crabharness run missions/examples/github-trending-harvest.json
crabharness promotion-apply artifacts/runs/<mission>/<run>/promotion_package.json

CrabHarness produces promotion packages as pure JSON. Apply them via:

• CLI: crabharness promotion-apply <package.json>
• MCP: harness_promotion_apply { "package": { ... } }

The dry_run: true flag validates grammar and schemas without writing.

MIT — see LICENSE.

OpenCrab: resistance is futile. Your agent will become an ontology.