Semantic Ontology System

The Constellation API uses a semantic ontology system to provide a structured, concept-based approach to managing MCP (Model Context Protocol) tools. This ontology layer allows you to define semantic concepts, their properties, relationships, and mappings to tools in a declarative YAML format.

Overview

The ontology system provides:

• Semantic Concepts: Core domain entities (Repository, Issue, Ticket, Page, Project, etc.)
• Concept Properties: Typed properties with descriptions for each concept
• Relationships: Defines how concepts relate to each other
• Tool Mappings: Maps API tools to semantic concepts and operations
• LLM Hints: Keywords, aliases, and examples to help AI assistants select the right tools
• Domain Grouping: Functional groupings with routing hints for LLM navigation
• Automatic Parameter Descriptions: Generates parameter descriptions from concept properties

Available Systems

System	Prefix	Concepts	Tools
GitHub	/github	Repository, Issue, PullRequest, Branch, File, Workflow, User, Comment, Label, GitHubMetrics	27
Jira	/jira	Project, Ticket, User, Comment, Status, Transition, Label, Sprint, JiraMetrics	24
Confluence	/confluence	Space, Page, Comment, Attachment, Label	14

Architecture

The ontology system consists of two main components:

1. ontology.yaml: Declarative YAML file defining all semantic concepts, properties, and tool mappings
2. tool_registry.py: Python code that loads the ontology and uses it to enhance tool definitions

┌─────────────────┐
│  ontology.yaml  │  ← Semantic definitions
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ tool_registry.py │  ← Loads and applies ontology
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   MCP Tools API  │  ← Exposes tools with semantic metadata
└─────────────────┘

Ontology Structure

The ontology.yaml file is organized into several sections:

1. Capabilities (NEW)

The capabilities section explicitly classifies each tool/capability as action, analytical, or read:

capabilities:
  # Action capabilities (side effects)
  github.issues.create:
    type: action
    system: github
    tool: create_issue
    side_effects: true
    idempotent: false
    
  # Analytical capabilities (read-only, may aggregate)
  github.analytics.dora_metrics:
    type: analytical
    system: github
    tool: get_dora_metrics
    read_only: true
    requires:
      - github
    outputs:
      - deployment_frequency
      - lead_time
      - change_failure_rate
      - mttr
      
  # Read capabilities (simple data access)
  github.repositories.list:
    type: read
    system: github
    tool: get_repositories
    read_only: true

Capability Types

Type	Description	Execution Path
action	Side-effect operations (create, update, delete)	Action Executor with retry/recovery
analytical	Read-only aggregation/metrics operations	Analytics Executor with partial results
read	Simple data access operations	Analytics Executor (simple path)

Capability Fields

Field	Type	Description
type	string	action, analytical, or read
system	string	The integration system (github, jira, confluence)
tool	string	The tool/endpoint name
read_only	boolean	true for read/analytical, false for actions
side_effects	boolean	true for actions that modify data
idempotent	boolean	true if operation can be safely retried
requires	array	Systems needed for multi-source analytics
outputs	array	Output fields produced (documentation)

2. Systems Configuration

Defines the available systems and their associated concepts:

systems:
  github:
    prefix: "/github"
    description: "GitHub integration for repositories, issues, pull requests, and metrics"
    concepts:
      - Repository
      - Issue
      - PullRequest
      - Branch
      - File
      - Workflow
      - User
      - Comment
      - Label
      - GitHubMetrics
  
  jira:
    prefix: "/jira"
    description: "Jira integration for projects, tickets, users, and metrics"
    concepts:
      - Project
      - Ticket
      - User
      - Comment
      - Status
      - Transition
      - Label
      - Sprint
      - JiraMetrics

  confluence:
    prefix: "/confluence"
    description: "Confluence integration for spaces, pages, and documentation"
    concepts:
      - Space
      - Page
      - Comment
      - Attachment
      - Label

2. Semantic Concepts

Defines the core domain entities with their properties and relationships:

concepts:
  Repository:
    description: "A GitHub repository containing code, issues, and pull requests"
    properties:
      repo_id:
        type: string
        description: "Repository identifier in owner/repo format (e.g., microsoft/vscode). Optional for list/read operations"
        required: false
      owner:
        type: string
        description: "Repository owner username"
      name:
        type: string
        description: "Repository name"
    relationships:
      - has_many: Issue
      - has_many: PullRequest
      - has_many: Branch
      - has_many: File
      - has_many: User
  
  Page:
    description: "A Confluence page containing content and documentation"
    properties:
      page_id:
        type: string
        description: "Page identifier"
        required: true
      space_key:
        type: string
        description: "Space key containing the page. Optional for list operations"
        required: false
      title:
        type: string
        description: "Page title"
        required: true
      body:
        type: object
        description: "Page content body"
    relationships:
      - belongs_to: Space
      - has_many: Comment
      - has_many: Attachment
      - has_many: Label

3. Tool Mappings

Maps each tool (API endpoint) to a semantic concept and operation:

tool_mappings:
  github:
    get_repositories:
      concept: Repository
      operation: list
      description: "List, show, get, fetch, or retrieve all GitHub repositories you can access"
    
    get_issue:
      concept: Issue
      operation: read
      description: "Get, show, fetch, view, or retrieve a specific GitHub issue by repository and number"

  confluence:
    get_spaces:
      concept: Space
      operation: list
      description: "List, show, get, fetch, or retrieve all Confluence spaces you can access"
    
    create_page:
      concept: Page
      operation: create
      description: "Create, make, add, write, or start a new Confluence page in a space"

How It Works

1. Loading the Ontology

When the ToolRegistry is initialized, it:

1. Loads ontology.yaml from app/mcp/ontology.yaml
2. Extracts system prefixes (replacing hardcoded values)
3. Builds a concept properties index for fast lookups
4. Loads tool mappings for semantic descriptions

2. Parameter Description Resolution

When generating tool schemas, the registry:

1. Checks if the tool has a concept mapping
2. Looks up the parameter in the concept's properties
3. Falls back to parent concept if specified
4. Uses the description from the ontology

3. Tool Description Enhancement

Tool descriptions are enhanced from the ontology with rich, natural language descriptions that help AI agents understand when to use each tool.

Key Concepts

GitHub Concepts

Concept	Description
Repository	A GitHub repository containing code, issues, and pull requests
Issue	A GitHub issue tracking bugs, features, or discussions
PullRequest	A GitHub pull request for code review and merging
Branch	A Git branch in a repository
File	A file in a repository
Workflow	A GitHub Actions workflow
GitHubMetrics	Metrics and analytics data for repositories

Jira Concepts

Concept	Description
Project	A Jira project containing tickets and sprints
Ticket	A Jira issue or ticket tracking work items
Status	A workflow status in Jira
Transition	A workflow transition between statuses
Sprint	A Jira sprint for agile development
JiraMetrics	Metrics and analytics for Jira projects

Confluence Concepts

Concept	Description
Space	A Confluence space containing pages and documentation
Page	A Confluence page containing content and documentation
Comment	A comment on a page
Attachment	A file attachment on a page
Label	A label or tag for categorization

Shared Concepts

Concept	Description
User	A user in GitHub, Jira, or Confluence
Comment	A comment on an issue, ticket, or page
Label	A label or tag for categorization

Benefits

1. Centralized Semantic Definitions

All semantic information is defined in one place (ontology.yaml), making it easy to:

• Update parameter descriptions across all tools
• Add new concepts and properties
• Maintain consistency across the API

2. Concept-Based Understanding

Tools are mapped to semantic concepts, making it easier to:

• Understand what a tool operates on
• Group related tools by concept
• Generate better documentation

3. Type Safety and Validation

Properties have types defined in the ontology:

properties:
  issue_number:
    type: integer
    description: "Issue number (numeric ID)"
    required: true
  state:
    type: string
    enum: [open, closed, all]

4. Relationship Modeling

Concepts can define relationships:

Repository:
  relationships:
    - has_many: Issue
    - has_many: PullRequest
    - has_many: Branch

Page:
  relationships:
    - belongs_to: Space
    - has_many: Comment
    - has_many: Attachment

5. Optional Parameters for Parallel Execution

Many concepts have optional identifier parameters that enable parallel execution:

repo_id:
  type: string
  description: "Repository in owner/repo format. Optional for list operations - if not provided, fetches from all accessible repositories in parallel"
  required: false

project_key:
  type: string
  description: "Jira project key. Optional for list operations - if not provided, fetches from all accessible projects in parallel"
  required: false

space_key:
  type: string
  description: "Space key. Optional for list operations - if not provided, fetches from all accessible spaces"
  required: false

Example: Adding a New Concept

Let's say you want to add a "Milestone" concept for GitHub:

Step 1: Add to Systems

systems:
  github:
    concepts:
      - Repository
      - Issue
      - Milestone  # Add here

Step 2: Define the Concept

concepts:
  Milestone:
    description: "A GitHub milestone for grouping issues and pull requests"
    properties:
      milestone_id:
        type: integer
        description: "Milestone number (numeric ID)"
        required: true
      title:
        type: string
        description: "Milestone title"
        required: true
      description:
        type: string
        description: "Milestone description"
      due_date:
        type: string
        description: "Due date in ISO 8601 format"
      state:
        type: string
        description: "Milestone state: open or closed"
        enum: [open, closed]
    relationships:
      - belongs_to: Repository
      - has_many: Issue

Step 3: Map Tools

tool_mappings:
  github:
    get_milestones:
      concept: Milestone
      operation: list
      description: "List milestones in a repository"
    
    get_milestone:
      concept: Milestone
      operation: read
      description: "Get details of a specific milestone"
    
    create_milestone:
      concept: Milestone
      operation: create
      description: "Create a new milestone"

Operation Types

The ontology supports these operation types:

Operation	Description
list	List multiple resources
read	Get a single resource
create	Create a new resource
update	Update an existing resource
delete	Delete a resource
search	Search across resources
add	Add items to a resource (e.g., labels)
remove	Remove items from a resource
lookup	Look up a resource by attribute
execute	Execute an action (e.g., transition)
merge	Merge resources (e.g., PR merge)
assign	Assign a resource to a user

Configuration Files

The MCP system uses a single YAML configuration file:

ontology.yaml

The ontology.yaml file is the single source of truth for the MCP system, defining:

1. Domains - Functional groupings with tool filtering and LLM hints
2. Concepts - Unified entities with operations and field schemas
3. Providers - System implementations with endpoint mappings

# Domains with LLM routing hints
domains:
  work:
    description: "Issues, tickets, sprints, and project management"
    keywords: ["ticket", "issue", "bug", "task", "sprint", "jira"]
    when_to_use: "Use for issue tracking..."
    systems: [jira, github]
    concepts:
      - Issue
      - Sprint
    tools:
      jira:
        - get_tickets
        - get_ticket

# Concepts with LLM hints
concepts:
  Issue:
    description: "Work item, bug, or task"
    llm_hints:
      aliases: ["ticket", "issue", "bug"]
      when_to_use: "Use for work tracking..."
      not_for: "Pull requests -> use PullRequest concept"
      examples:
        - query: "Show my open tickets"
          tool: "issue.list"
    operations:
      list:
        description: "List issues/tickets"
        type: read

# Providers with endpoint mappings
providers:
  jira:
    description: "Atlassian Jira"
    concepts:
      Issue:
        list:
          endpoint: "/rest/api/3/search"
          method: GET

LLM Hints

The ontology includes LLM hints at both the domain and concept level to help AI assistants select the right tools.

Domain-Level Hints

Domains include keywords and when_to_use for routing:

domains:
  work:
    description: "Issues, tickets, sprints, and project management"
    keywords: ["ticket", "issue", "bug", "task", "sprint", "jira", "backlog"]
    when_to_use: "Use for issue tracking, tickets, sprints, and project management tasks"

Concept-Level Hints

Concepts include detailed llm_hints:

concepts:
  Issue:
    llm_hints:
      aliases: ["ticket", "issue", "bug", "task", "story", "work item"]
      when_to_use: |
        Use for work tracking operations. Triggered by:
        - "my tickets", "assigned to me", "open issues"
        - "create a ticket", "update the bug"
        - "what's in the backlog", "sprint tickets"
      not_for: |
        - Pull requests -> use PullRequest concept
        - Analytics/metrics -> use analytics domain
      examples:
        - query: "Show my open tickets"
          tool: "issue.list"
          params: { state: "open" }
        - query: "Create a bug for the login issue"
          tool: "issue.create"
          params: { title: "Login issue", project_id: "PROJ" }

LLM Hint Fields

Field	Purpose	Example
aliases	Alternative names/synonyms	["ticket", "issue", "bug"]
when_to_use	Intent signals for when to use this tool	"Use when user asks about PRs..."
not_for	Disambiguation - when NOT to use	"Jira tickets -> use Issue concept"
examples	Concrete query examples	[{ query: "...", tool: "...", params: {...} }]

Accessing LLM Hints via API

LLM hints are exposed in the /mcp/{domain}/tools response:

{
  "tools": [
    {
      "name": "issue.list",
      "description": "List issues/tickets from Jira or GitHub",
      "llm_hints": {
        "aliases": ["ticket", "issue", "bug"],
        "when_to_use": "Use for work tracking...",
        "not_for": "Pull requests -> use PullRequest",
        "examples": [...]
      }
    }
  ]
}

---

Best Practices

1. Use Semantic Names

Choose concept names that reflect the domain:

• ✅ Repository, Issue, Ticket, Page
• ❌ Repo, IssueObj, TicketEntity

2. Consistent Property Names

Use consistent property names across concepts:

• id or {concept}_id for identifiers
• title for titles
• description for descriptions
• state or status for state fields

3. Comprehensive Descriptions

Provide clear, helpful descriptions:

repo_id:
  type: string
  description: "Repository identifier in owner/repo format (e.g., microsoft/vscode). Optional - if not provided, fetches from all accessible repositories"
  required: false

4. Use Enums for Limited Values

state:
  type: string
  description: "Filter by state: open, closed, or all"
  enum: [open, closed, all]

merge_method:
  type: string
  description: "Merge strategy"
  enum: [merge, squash, rebase]

5. Document Relationships

Define relationships even if not used yet:

relationships:
  - belongs_to: Repository
  - has_many: Comment
  - has_many: Label

6. Rich Tool Descriptions

Use natural language descriptions with action verbs:

description: "List, show, get, fetch, or retrieve all GitHub repositories you can access. Use when: listing repos, showing my repositories, getting all repos"

Troubleshooting

Ontology Not Loading

If the ontology doesn't load:

1. Check file path: app/mcp/ontology.yaml
2. Verify YAML syntax (use a YAML validator)
3. Check logs for parsing errors

Parameters Not Getting Descriptions

If parameters don't get ontology descriptions:

1. Verify the tool is mapped in tool_mappings
2. Check the concept has the property defined
3. Ensure property name matches exactly (case-sensitive)

System Prefix Not Found

If system prefix errors occur:

1. Verify system is defined in systems: section
2. Check prefix: is set correctly
3. Ensure system name matches in tools.yaml

Related Documentation

• Architecture Overview - Ontology-driven layered architecture
• MCP API Reference - API endpoints for MCP tools
• GitHub API Reference - GitHub tools documentation
• Jira API Reference - Jira tools documentation
• Confluence API Reference - Confluence tools documentation