{"id":"9346d82a-701e-463a-a890-5308a538520c","slug":"code-ontology-companion","kind":"mcp","name":"code-ontology-companion","summary":"Map Java, Spring, and Python repositories into local code knowledge graphs for architecture and change-impact analysis.","owner":"battle-doll","repoUrl":"https://github.com/battle-doll/code-ontology-companion","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":5,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-07-29T14:50:55.000Z","addedAt":"2026-10-21T09:22:55.471Z","logoUrl":"https://avatars.githubusercontent.com/u/222929439?u=bf0a185323e155e84f76e856e036d8bcc6c269d6&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","memory-knowledge","utilities"],"tags":["codex","knowledge-graph","ontology","python","rdf","static-analysis","change-impact-analysis","code-analysis"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T23:08:09.383Z","sample":false,"url":"https://conduits.dev/tools/code-ontology-companion","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Code Ontology Companion\n\n[English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md) | [Русский](README.ru.md)\n\nCode Ontology Companion is an **initial MVP of an AI data-pipeline platform**: it turns authorized local code into source-linked knowledge for AI and a lightweight offline overview for people. It analyzes code statically, without executing the target project or requiring a model or cloud service.\n\n**0.9.3 release candidate** · Developer: **battle-doll** · English, Korean, Japanese, Simplified Chinese and Russian · Windows, macOS and Linux. Keep your selected GPT-6 Astra or GPT-6.1 Sol model and reasoning effort; this plugin does not switch them.\n\n## Version 0.9.3 capabilities\n\n- Select source folders, inventory the complete selected scope, and generate immutable, partitioned source and business knowledge snapshots.\n- Find declarations, relationships, call candidates and semantic fragments; inspect their source bindings, support limits, changes and coverage through local read-only MCP.\n- Connect business concepts and typed properties to source evidence, review or revoke claims explicitly, and query supported policy fragments with typed context.\n- Open an offline 3D overview, or explicitly export record pages, a portable SQLite/JSON bundle and a parallel RDF 1.1 Turtle graph.\n\nJava/Spring, Python, JavaScript/TypeScript and Bash have different supported analyses. Other adapters have explicit declaration/import or partial support levels. Neither a recognized file nor an extracted expression implies complete language or business semantics. See the [implementation guide](docs/PIPELINE_0_9_0.md) and [quality workflow](docs/QUALITY_0_9_3.md).\n\n## Start with your code\n\nUse Python 3.9 or newer. On Windows, use `py -3` in place of `python3`. Choose a new knowledge workspace outside the source tree. Before generating HTML or a portable export, configure `CODE_ONTOLOGY_PRIVACY_FILE` with a private identity-deny profile outside the source and output roots; follow the [privacy setup](skills/manage-code-ontology/references/privacy-operations.md).\n\n```sh\npython3 skills/manage-code-ontology/scripts/companion.py analyze --repo /path/to/source --workspace /path/outside/source/knowledge --authorized --language en\npython3 skills/manage-code-ontology/scripts/companion.py pipeline-status --workspace /path/outside/source/knowledge\npython3 skills/manage-code-ontology/scripts/companion.py pipeline-search --workspace /path/outside/source/knowledge --snapshot SNAPSHOT_ID --term Service --limit 20\n```\n\nReplace `SNAPSHOT_ID` with the returned concrete ID. Repeat `--source-root` on `analyze` to select relative source directories. The result reports source, business and HTML stages separately; open the returned HTML `entrypoint` directly with `file://`. A successful source build does not guarantee that a later business or HTML stage completed.\n\nAfter code changes, run `refresh --workspace /path/outside/source/knowledge --language en`. Refresh retains the selected scope and earlier snapshots. Add `--no-html` to analyze/refresh when you only need sealed knowledge. Status checks saved artifacts without rereading source; it does not establish fresh source or runtime behavior.\n\nIn an AI task, ask: **“Apply Code Ontology Companion here and use the authorized workspace while we work.”** The [application skill](skills/apply-code-ontology/SKILL.md) checks available tools, performs a real first lookup and keeps related reads on one snapshot. Sending local MCP results to a remote model requires separate authorization.\n\n## Human overview, exact AI knowledge\n\nPublic `analyze`, `refresh` and ordinary `pipeline-html` default to `--presentation human`: area → major structural module → core flow/evidence, with default depth 2 and maximum depth 3. The first page is bounded to 32 nodes, 64 aggregate edges and 128 KiB of data. Five UI languages share one data set; local script chunks load only the chosen view. There is no initial full-corpus or whole-search-index parsing, network dependency or required HTTP server. Search covers the current page.\n\nWhole mode summarizes the full scope; focus mode shows a bounded selection. 3D animation, a separate whole-scope link, reduced motion, mobile/text fallback and camera controls remain. Unknown groups and explicit remainder counts stay visible. Source policy cards are opaque evidence tiles with **UNKNOWN** meaning, not complete narratives of policy conditions, calculations or exceptions.\n\nOriginal source-record count, file outcomes, displayed groups/nodes and evidence references use separate units. A hidden group is not an omitted ontology record; a privacy-withheld relationship count is not a count of people or whole records. Summary selection never changes ontology/MCP coverage. Native browser/OS results and workload capacity must be verified separately.\n\nFor exact/deep knowledge use MCP; `--presentation records` retains complete record presentation. Existing legacy and explicit partitioned routes remain available, and business HTML has its own projection contracts. To export an existing snapshot to a new directory:\n\n```sh\npython3 skills/manage-code-ontology/scripts/companion.py pipeline-html --workspace /path/outside/source/knowledge --snapshot SNAPSHOT_ID --output /path/to/new-html --language en\n```\n\n## From local code to usable knowledge\n\n```mermaid\nflowchart TB\n    source[\"Authorized local code: Java/Spring + Python + JS/TS + Bash<br/>explicitly selected source roots\"]\n    scope[\"Selection inventory + private SHA-256 fingerprints<br/>privacy boundaries + unsupported / omitted outcomes\"]\n    adapters[\"Bounded language adapters<br/>Python AST + conservative Java / other support tiers\"]\n    evidence[\"Declarations + relations + semantic fragments<br/>source-backed observed / inferred evidence\"]\n    gate[\"Coverage + source / business knowledge layers<br/>HMAC-SHA256 privacy + current ACL + explicit review\"]\n    snapshot[\"Immutable partitioned SQLite + policy.json; legacy ontology.json<br/>private source-manifest.json + append-only lineage.jsonl\"]\n    rdf[\"Parallel RDF 1.1 Turtle interchange<br/>ontology.ttl + lineage.ttl / bounded PROV-O subset\"]\n    mcp[\"Local stdio MCP reads SQLite + JSON + JSONL<br/>snapshot-pinned, bounded AI evidence\"]\n    ai[\"AI task knowledge<br/>structure, policy evidence, impact and changes\"]\n    human[\"Offline human HTML<br/>bounded 2 / max 3 layers + shared local chunks\"]\n    source --> scope\n    scope --> adapters\n    adapters --> evidence\n    evidence --> gate\n    gate --> snapshot\n    snapshot -->|Turtle exports| rdf\n    snapshot -->|SQLite + policy.json / legacy JSON + JSONL| mcp\n    mcp --> ai\n    snapshot -->|bounded pages / embedded JSON| human\n```\n\nThe source layer preserves declarations, evidence and limitations; the business layer adds source-linked concepts, typed properties and explicit review states. `observed`, `inferred` and `runtime_unknown` are distinct. Exact calls, candidates and unresolved calls keep separate status: an unresolved call is not silently removed or promoted to exact. Constructor/component, caller/provider and helper transfers are bounded structural evidence, not automatically complete policy meaning or runtime values.\n\nSelection inventory, declarations/types, exact calls, policy semantics, MCP delivery and policy-document coverage have separate denominators. Unsupported, omitted, redacted, PARTIAL and UNKNOWN outcomes remain visible. Before policy prose, map essential conditions, AND/OR, state/effect, units, formulas, rounding, exceptions, authority, ownership and time bounds to evidence; keep unsupported meaning UNKNOWN. The repeatable feedback loop is evidence worksheet → coverage/meaning checks → supported corrections or explicit review → refreshed snapshot → pinned queries. A worksheet or a small HTML summary is not proof of complete policy prose.\n\nSnapshots bind source fingerprints, analysis specifications and artifact hashes. Private `source-manifest.json` and append-only `lineage.jsonl` support local checks; `lineage.ttl` uses a bounded PROV-O subset. RDF `RelationshipEvidence` and shape validation do not certify truth, full source reconstruction, a complete provenance chain, human identity or runtime success. MCP reads sealed SQLite/JSON/JSONL, not the RDF branch. The legacy `graph.html` / `ontology.json` / `ontology.ttl` workflow remains supported separately.\n\n## Policy knowledge and export choices\n\nBusiness knowledge is source-linked and typed. Approval/revocation and current source/business snapshot pins are checked separately from extraction. `verified_implemented` is not `approved_business`; `DECLARED` is not proof of source enforcement. Supported static policy evaluation requires explicit context and complete supported inputs. Missing context, ambiguous composition, unsupported effects and unknown units stay UNKNOWN. A source match or raw IR does not establish authorization or business correctness.\n\n`business-html` defaults to the existing lossy `business_only` view. Explicit `--projection policy_projection` preserves the exact authorized MCP policy view, including selected identities, source candidates, typed mappings, UNKNOWN states and aggregate snapshot bindings, with `read_policy` and `export_html`:\n\n```sh\npython3 skills/manage-code-ontology/scripts/companion.py business-html --workspace /path/outside/source/knowledge --snapshot SNAPSHOT_ID --business-snapshot BUSINESS_ID --business-digest BUSINESS_DIGEST --output /path/to/new-policy-view --projection policy_projection\n```\n\nThe ordinary policy projection is limited to 10,000 records and 1 GiB. For an explicitly larger schema2 business snapshot, add `--partitioned --partition-size 10000`; physical windows preserve the original selected denominator and remain within the trusted workspace budget. A compatible, isolated Python/SQLite worker is required; `--export-python PATH` selects an already trusted interpreter, without automatic installation/discovery. Its 128 MiB SQLite allocation cap is not a total process-memory guarantee. Resource failure retains incomplete counts/frontiers; storage completion does not mean complete business semantics.\n\n`pipeline-html --presentation records --partitioned` selects the existing partitioned source-atlas/record route. `pipeline-export` creates the authorized portable bundle. SQLite/JSON retains full authorized records; RDF is a defined projection, not a universal lossless reconstruction. Every export keeps its own permissions, limits and withholding rules. Unsigned copies do not authenticate an issuer, confer publication permission or support remote revocation.\n\n## Local installation and compatibility\n\n[GitHub packages](https://github.com/battle-doll/code-ontology-companion/releases) · [Directory entry](https://chatgpt.com/plugins/plugins_6a6a23c0434c8191aec6a38bb590fd3c) · [Local MCP setup](skills/manage-code-ontology/references/local-mcp.md)\n\nThe full package includes the read-only stdio MCP server: 12 legacy tools plus 8 pipeline tools, 20 total. **Skills-only** contains the application/management skills, analyzer, workbench and setup guidance, but no MCP server. No cloud endpoint is required. Directory availability/version has a separate review process; this source candidate does not claim official submission, approval, endorsement or eligibility.\n\nLegacy `init`/`sync`, `query`, `impact` and `diff` workspaces are not silently converted. Legacy large-query tools include `ontology_large_modules`, `ontology_large_search`, `ontology_large_neighbors`, `ontology_evidence_bundle` and `ontology_evidence_pack`. Code handles source structure; optional Context and Contracts companions retain their own responsibilities and verified compatibility limits. [Model-era workflow](skills/manage-code-ontology/references/model-era-workflow.md) · [Reference exchange](skills/manage-code-ontology/references/code-reference.md).\n\nOptional existing Ollama at `127.0.0.1:11434` requires separate consent; suggestions remain `inferred` sidecars outside observed evidence. Deterministic analysis needs no model, model installation or automatic model switch.\n\n## Privacy and trust\n\nLocal analysis authorization, ACL grants, knowledge review and publication permission are separate. Current ACL/profile/binding checks remain mandatory. Personal information and registered protected values are hard denies: administrator approval, aliases, `manage_knowledge` and review basis cannot bypass them. HMAC-SHA256 profile keys and protected fingerprints must never be published. Missing required protection or unverifiable publication identity means **HOLD**; the public developer alias is **battle-doll** only.\n\nComments/literals are opaque by default. Explicit private occurrence permissions may retain permitted local evidence; this is not semantic approval, instruction authority or permission to publish it. Revocation affects subsequent authorized reads, not copies already exported. The analyzer does not execute target code, send telemetry or make direct network requests. A host may forward selected MCP results, so approve recipients separately.\n\n## More information\n\n[Quality workflow](docs/QUALITY_0_9_3.md) · [Coverage](docs/COVERAGE_0_9_2.md) · [Pipeline guide](docs/PIPELINE_0_9_0.md) · [Public self-ontology demo](https://battle-doll.github.io/code-ontology-companion/) · [Translation coverage](docs/TRANSLATION_COVERAGE.md)\n\nApache-2.0 · [Privacy](PRIVACY.md) · [Security](SECURITY.md) · [Support](SUPPORT.md) · [Terms](TERMS.md) · [Changelog](CHANGELOG.md)\n"}