service-ontology-lite 0.1.0

Lightweight service ontology, audit CLI, and MCP server for small web apps.

service-ontology-lite ·

English | 한국어

Map routes, auth boundaries, data entities, scheduled jobs, and external services before an AI agent edits a web app.

service-ontology-lite turns a small Next.js-style app into a machine-readable service map, then exposes that map through a CLI and MCP stdio server.

Status: public alpha. Project-specific scoring, production schema, tokens, and incident runbooks stay outside this package.

Why this exists

AI coding agents can change files quickly, but they often start without a service-level map.

This package gives the agent a compact answer before it edits:

What routes exist?
Which routes are public, authenticated, admin, or cron?
Which data entities and external services are nearby?
If this file changes, what is the blast radius?

What it returns

Question                                      Output
Which routes exist?                           routes[] with path, handler, methods, auth
Which routes are public/auth/admin/cron?      auth boundary labels
Which data entities are touched?              entities[] and route-to-entity links
Which external services are in play?          external_services[] with env-name hints and used_by files
What is the blast radius of this edit?        LOW/MEDIUM/HIGH risk with impacted routes/services/jobs

Install

Install from GitHub:

python3 -m pip install "git+https://github.com/veris-official/service-ontology-lite.git"

Local development install:

python3 -m pip install -e .

Planned PyPI install after package release:

python3 -m pip install service-ontology-lite

The MVP has no runtime dependency.

30-second example

service-ontology validate ./your-nextjs-app
service-ontology audit ./your-nextjs-app --json
service-ontology risk ./your-nextjs-app --changed app/api/admin/route.ts --json

Use this before handing a task to an AI coding agent. The result tells the agent whether the change touches public routes, authenticated routes, admin routes, cron handlers, data entities, or external integrations.

CLI

service-ontology --version   # or: service-ontology -V
service-ontology scan ./sample-app --json
service-ontology audit ./sample-app --json
service-ontology graph ./sample-app --json
service-ontology agent-os ./sample-app --json
service-ontology agent-os ./sample-app --project-context service-ontology-lite --json
service-ontology risk ./sample-app --changed app/api/admin/route.ts --json
service-ontology validate ./sample-app

Commands:

scan       Generate routes, auth boundaries, entities, external services, and jobs
--version  Print installed package version
validate   Validate service-ontology.json/yaml metadata
risk       Classify changed files by service blast radius
audit      Flag missing auth/entity/job/service metadata
graph      Return the combined service graph
agent-os   Return Agent OS registry and project_context grouping

MCP server

service-ontology-mcp ./sample-app

Supported MCP tools:

get_service_graph
list_routes
list_external_dependencies
audit_change_risk
audit_service
validate_manifest
get_agent_os_graph
list_project_contexts

agent-os and list_project_contexts accept project_context_id filtering for a single project handoff context.

Hermes Agent MCP config example:

mcp_servers:
  service_ontology:
    command: "service-ontology-mcp"
    args: ["/absolute/path/to/your-nextjs-app"]
    timeout: 60
    connect_timeout: 30

When registered, an AI agent can call audit_change_risk before editing a route and see whether the touched file crosses public, admin, cron, data, or external-service boundaries.

Python API

from service_ontology_lite import (
    audit_change_risk,
    filter_project_contexts,
    load_agent_os_registry,
    scan_project,
    validate_manifest,
)

registry = load_agent_os_registry("./sample-app")
project_context = filter_project_contexts(registry, "service-ontology-lite")

Example dry-run result

Against the bundled sample app, the current release reports:

scan route_count        5
external_services       Discord, Supabase
audit score             100
audit findings          0
risk admin route        HIGH
manifest_valid          true
MCP tools exposed       8

Next.js route support

The scanner understands common App Router path conventions:

app/(marketing)/blog/[slug]/page.tsx       → /blog/:slug
app/docs/[...parts]/page.tsx               → /docs/:parts*
app/shop/[[...filters]]/route.ts           → /shop/:filters*
app/api/admin/route.ts                     → /api/admin

Explicit manifest

Static scanning works without config. Add service-ontology.json, service-ontology.yaml, or service-ontology.yml for durable project knowledge:

routes:
  - path: /dashboard
    auth: required
    handler: app/dashboard/page.tsx
    entities: [User]
    external_services: []
entities:
  - name: User
    storage: database:users
    fields: [id, email]
external_services:
  - name: Stripe
    type: payments
    env: [STRIPE_SECRET_KEY]
jobs:
  - name: daily-sync
    schedule: "0 0 * * *"
    handler: app/api/cron/route.ts
agent_os:
  projects:
    - id: service-ontology-lite
      name: service-ontology-lite sample
  agents:
    - id: implementation-agent
      role: implementation
  surfaces:
    - id: local-sample-app
      type: local_repo
      project_context_id: service-ontology-lite
  tasks:
    - id: agent-os-registry-poc
      project_context_id: service-ontology-lite
      owner_agent: implementation-agent
  artifacts:
    - id: pytest-agent-os-registry
      type: test_output
      project_context_id: service-ontology-lite

Validate a manifest before sharing it with agents:

service-ontology validate ./sample-app

The JSON Schema reference is in docs/service-ontology.schema.json. The same schema file is included in the wheel as package data at service_ontology_lite/service-ontology.schema.json.

Practical scenarios

Before an AI agent edits an admin route

service-ontology risk . --changed app/api/admin/route.ts --json

Expected signal:

severity: HIGH
reason: admin_or_cron_route_changed
next step: require route-level tests and human review before merge

Before changing an integration file

service-ontology risk . --changed app/lib/supabase.ts --json

Expected signal:

severity: HIGH when the file is linked to an external dependency
next step: check env names, failure mode, retry behavior, and release rollback path

Before public release

service-ontology validate .
service-ontology audit . --json

Expected signal:

manifest_valid: true
finding_count: 0 or reviewed findings with explicit fixes

Good use cases

Use case                                      How this repo helps
Pre-release check for a small Next.js app      Run validate + audit + risk before deploy
AI coding guardrail                            Give agents a route/auth/service map first
Private app documentation                      Keep service-ontology.json beside source
Refactor planning                              See which routes/entities/services are touched
Cron/API safety review                         Flag admin/cron/external-service edits as high risk
MCP experiment                                 Serve service graph over stdio without app runtime dependencies

Not a replacement for

authentication tests
dependency vulnerability scanning
SAST/DAST
production penetration tests
framework-specific type checking
real database schema introspection
runtime traffic analysis

The package is a static inspection layer. It does not execute the target app, open network connections, read .env values, or verify production authorization behavior.

Release gate

Before publishing or pushing a release branch, run:

python3 -m compileall -q src tests
python3 -m pytest -q
python3 -m ruff check .
python3 -m build --sdist --wheel

The GitHub Actions workflow in .github/workflows/ci.yml runs the same gate on Python 3.11.

Security model

service-ontology-lite is a static inspection and guardrail tool. It reads project files from the target directory and emits structural metadata: routes, declared auth boundaries, entities, external service names, cron handlers, and generic risk findings.

It does not execute application code, open network connections, read .env files, or collect secret values.

Public/private boundary

Public core:

schema
CLI
MCP stdio server
generic scanner
generic audit rules
sample Next.js/Vercel app
report format

Private project plugins stay outside the package:

domain-specific scoring
live production database structure
affiliate/commercial logic
real cron tokens
incident runbooks
SEO/GEO monetization formulas

Contributing

See CONTRIBUTING. Korean guide: CONTRIBUTING-ko_kr.

License

MIT. See LICENSE.