# OntologyEX > Agent Ontology Kit β€” a portable skill that makes AI agents understand a business before they act. Extracts four-layer ontologies (upper/domain/task/application) from companies, APIs, markets, and codebases. - **Type:** MCP server - **Install:** `agentstack add mcp-new1direction-ontologyex` - **Verified:** Yes β€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [New1Direction](https://agentstack.voostack.com/s/new1direction) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [New1Direction](https://github.com/New1Direction) - **Source:** https://github.com/New1Direction/OntologyEX - **Website:** https://new1direction.github.io/OntologyEX/ ## Install ```sh agentstack add mcp-new1direction-ontologyex ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 🧭 Agent Ontology Kit **Make AI agents understand a business before they act.** Agent Ontology Kit is a **portable skill for AI agents**. It reads a company, product, API, market, or codebase and writes a clean, structured **map of how that world works** β€” the things that exist, the actions you can take, and the rules between them β€” in a form an agent can use *before* it acts. No framework. No build step. It's markdown you hand to any capable agent (Claude Code, Codex, Cursor, custom runners), plus a tiny Python validator. **β–Ά [Live explainer β€” in plain English](explain.html) Β· [Examples](#-worked-examples) Β· [Quick start](#-quick-start)** --- ## πŸ€” The problem AI agents are great at *doing* things β€” issuing refunds, booking slots, calling APIs. They're bad at *understanding the business* first. An agent will happily refund an order that was never paid, because nobody told it that's impossible. This kit makes that understanding **explicit, checkable, and reusable.** ## 🧱 What it builds: four layers Imagine describing a **coffee shop** to a robot β€” from "true of anything" down to "this exact shop." | Layer | Plain English | Coffee-shop example | |---|---|---| | **L0 Β· Upper** | universal kinds of things | a thing, a person, an amount | | **L1 Β· Domain** | the nouns of the trade | Order, Drink, Barista | | **L2 Β· Task** | the actions + their rules | TakeOrder, Refund *("can't refund what wasn't paid")* | | **L3 Β· Application** | this exact system's files | the `orders` table, the "new order" button | The discipline that makes it worth doing: **every L3 maps to an L1, every L1 anchors to an L0, every L2 names the L1 nouns it touches.** That cross-layer mapping table is the deliverable. ## πŸš€ Quick start Give any capable agent this: ```text Use AGENT_SKILL.md as your workflow. Target: Consumer: Boundary: Deliver: the YAML layers, the mapping table, validation notes, and the consumer binding. ``` That's it. The agent scopes the target, mines sources, builds the four layers, validates them, and emits the output your consumer needs. ## πŸ› οΈ Run the tooling locally (optional) ```bash cd ontology-extraction python3 scripts/scaffold.py init --name my-target --out ../my-target-ontology # ...fill in the YAML layers... python3 scripts/scaffold.py validate ../my-target-ontology # 0 errors = structurally sound python3 scripts/scaffold.py mappings ../my-target-ontology # regenerate the crosswalk ``` The only dependency is `pyyaml` (`pip install pyyaml`). The skill itself needs nothing. ## πŸ“¦ What you get A 7-file workspace plus a consumer-specific binding: ``` my-target-ontology/ 00-scope.md target, consumer, boundary, competency questions 10-upper.yaml L0 β€” chosen universal anchors (selected, never invented) 20-domain.yaml L1 β€” the domain nouns + relations 30-task.yaml L2 β€” the actions, with inputs/outputs/preconditions/effects 40-application.yaml L3 β€” the concrete system artifacts 50-mappings.yaml the app β†’ domain β†’ upper crosswalk README.md ``` …then one binding: **MCP tool schemas**, an RDF/Turtle knowledge graph, TypeScript/Pydantic types, RAG metadata, or a Mermaid diagram. ## πŸ§ͺ Worked examples Five runs in [`examples/`](examples/), each validated clean by the bundled script: | Eval | Target | Highlight | |---|---|---| | `eval-1-stripe` | Stripe (research) | API β†’ safe MCP tools with preconditions baked in | | `eval-2-realworld` | RealWorld app (retrofit) | map an existing codebase to its domain | | `eval-3-prediction-markets` | a market (research) | a sparse / emerging domain | | `eval-4-self` | **the kit itself** | it described its own code β€” **0 errors** | | `eval-5-adyen` | Adyen (research) | **competitor swap vs Stripe: 8/9 domain concepts matched** ⭐ | The plain-English walkthrough of the last two is in **[explain.html](explain.html)**. ## πŸ’‘ Why four layers (the payoff) Because the middle layer belongs to the *trade*, not the *vendor*. We proved it: building the same model for **Stripe and Adyen**, **8 of 9 core concepts matched** β€” only the bottom, vendor-specific layer differed (see [`examples/eval-5-adyen/comparison-vs-stripe.md`](examples/eval-5-adyen/comparison-vs-stripe.md)). Build your agent once on the shared layer; swap providers without re-teaching it the business. ## πŸ”Œ Use it as a skill - **Claude Code / Cursor / Codex:** point the agent at `AGENT_SKILL.md`, or drop the `ontology-extraction/` folder into your skills directory (it has a ready `SKILL.md` with trigger frontmatter). - **Any runner:** the workflow is plain markdown β€” no runtime lock-in. ## 🌐 Publish the site (GitHub Pages, zero build) `index.html` (landing) and `explain.html` (explainer) are self-contained static HTML. **Settings β†’ Pages β†’ Deploy from a branch β†’ `main` / `(root)`.** Your live site: `https://.github.io//`. ## πŸ—ΊοΈ How it works Work **middle-out**: scope β†’ competency questions β†’ mine sources β†’ anchor L0 β†’ build L1 β†’ build L2 β†’ project L3 β†’ validate β†’ emit the binding. Full method in [`ontology-extraction/SKILL.md`](ontology-extraction/SKILL.md); evidence rules, reuse catalog, and production design principles in [`ontology-extraction/references/`](ontology-extraction/references/). The design bias is deliberately domain-driven: model how the real business operates, not a 1:1 copy of source tables or departmental systems. The validator now flags common ontology anti-patterns such as God Objects, Kitchen Sink schemas, duplicated department/system classes, action sprawl, vague misnomers, and over-deep hierarchies that should be replaced with reusable interfaces. ## πŸ“ Repo layout ``` . β”œβ”€ README.md β”œβ”€ AGENT_SKILL.md ← the portable workflow β€” hand this to any agent β”œβ”€ index.html Β· explain.html ← zero-build site (deploy to GitHub Pages) β”œβ”€ ontology-extraction/ β”‚ β”œβ”€ SKILL.md β”‚ β”œβ”€ scripts/scaffold.py ← init Β· validate Β· mappings β”‚ └─ references/ ← source-mining Β· reuse-catalog Β· design-principles Β· output-formats └─ examples/ ← 5 worked, validated evals ``` ## 🀝 Contributing PRs welcome β€” new worked evals (a real company/API/codebase + its validated ontology) are the most valuable contribution. Run `python3 scaffold.py validate` before opening a PR. ## πŸ“„ License [MIT](LICENSE) Β© 2026 New1Direction ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source β€” we do not rehost the code. - **Author:** [New1Direction](https://github.com/New1Direction) - **Source:** [New1Direction/OntologyEX](https://github.com/New1Direction/OntologyEX) - **License:** MIT - **Homepage:** https://new1direction.github.io/OntologyEX/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** β€” Free ## Security capabilities Automated source analysis of v0.1.0 β€” what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source β€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** β€” security scan: passed β€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-new1direction-ontologyex - Seller: https://agentstack.voostack.com/s/new1direction - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack β€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.