AI Features

Overview

HoxCore's primary AI integration is a built-in MCP (Model Context Protocol) server. MCP is an open standard that lets LLM clients connect to external tools and data sources. When the HoxCore MCP server is running, an AI assistant can query, search, and inspect your registry in real time, without you having to copy-paste YAML files manually.

There are two ways HoxCore works with AI:

• Active (MCP) — Start the MCP server and connect a compatible LLM client. The assistant can call tools, read resources, and use prompt templates to interact with your registry dynamically.
• Passive (YAML context) — Export entity YAML with hxc show <identifier> --raw and paste it directly into any LLM chat window. No server required.

Starting the Server

The MCP server is started with the hxc mcp subcommand. It communicates over stdio, the transport expected by most MCP-compatible clients. A standalone alias hxc-mcp is also installed and behaves identically.

# Start with the default or configured registry
hxc mcp

# Start with a specific registry path
hxc mcp --registry /path/to/your/registry

# Specify transport explicitly (only stdio is supported currently)
hxc mcp --transport stdio

# Show server capabilities (tools, resources, prompts) and exit without starting
hxc mcp --capabilities

# Start in read-only mode — expose only read tools to the LLM
hxc mcp --read-only

You can also start the server programmatically from Python:

from hxc.mcp.server import create_server

server = create_server(registry_path="/path/to/registry")
server.run_stdio()

Connecting MCP Clients

Any MCP-compatible client can connect to the HoxCore server using stdio transport. The server implements the 2024-11-05 version of the MCP protocol. Below are configuration examples for common clients.

Claude Desktop

Add HoxCore to your claude_desktop_config.json:

{
  "mcpServers": {
    "hoxcore": {
      "command": "hxc",
      "args": ["mcp", "--registry", "/path/to/your/registry"]
    }
  }
}

Restart Claude Desktop after saving. Claude will then have access to all HoxCore tools, resources, and prompts.

LM Studio

In LM Studio's Developer settings, add a new MCP server entry:

{
  "name": "hoxcore",
  "command": "hxc",
  "args": ["mcp", "--registry", "/path/to/your/registry"],
  "transport": "stdio"
}

Cursor

In your project's .cursor/mcp.json (or the global Cursor MCP config), add:

{
  "mcpServers": {
    "hoxcore": {
      "command": "hxc",
      "args": ["mcp", "--registry", "/path/to/your/registry"]
    }
  }
}

Continue (VS Code / JetBrains)

In your ~/.continue/config.json, add HoxCore under mcpServers:

{
  "mcpServers": [
    {
      "name": "hoxcore",
      "command": "hxc",
      "args": ["mcp", "--registry", "/path/to/your/registry"],
      "transport": "stdio"
    }
  ]
}

Example prompts

Once connected, you can ask your LLM assistant things like:

• "List all active projects in my registry."
• "What is the status of project P-001?"
• "Search for entities related to machine learning."
• "Show me all projects due before the end of the month."
• "What are the tags on entity proj_abc123?"
• "Which projects are children of program prog_abc123?"

Available Tools

Tools are callable functions that the LLM can invoke to interact with your registry. HoxCore exposes seven tools: four read-only and three write tools.

Read tools

list_entities

{
  "entity_type": "project",
  "status": "active",
  "tags": ["python", "api"],
  "sort_by": "title",
  "descending": false,
  "max_items": 20
}

get_entity

{
  "identifier": "P-001"
}

Accepts both human-readable IDs (e.g. P-001) and system UIDs (e.g. proj_abc123def456).

search_entities

{
  "query": "machine learning",
  "entity_type": "all",
  "status": "active"
}

Matches the query string against both title and description fields.

get_entity_property

{
  "identifier": "P-001",
  "property": "repositories",
  "key": "name:github"
}

The key argument filters list properties using key:value syntax. The index argument retrieves a specific item by position. Pass "property": "all" to return the complete entity.

Write tools

create_entity

Create a new entity. type and title are required. All other fields are optional; status defaults to active and start_date defaults to today.

{
  "type": "project",
  "title": "New API Service",
  "description": "Internal REST API for the billing system.",
  "status": "active",
  "id": "P-042",
  "category": "software.dev/api",
  "tags": ["python", "api"],
  "parent": "prog_abc123",
  "start_date": "2025-03-01",
  "due_date": "2025-12-31"
}

On success, the tool returns the new entity's uid, id, file_path, and the full entity object.

edit_entity

Modify an existing entity. identifier accepts either a UID or a human-readable ID. Scalar fields are updated with set_* arguments. Tags can be incrementally added or removed.

{
  "identifier": "P-042",
  "set_title": "Billing API Service",
  "set_status": "completed",
  "add_tags": ["deployed"],
  "remove_tags": ["wip"]
}

On success, the tool returns the updated entity, a list of changes, and the file_path.

delete_entity

Delete an entity from the registry. Because deletion is irreversible, a two-step confirmation guard is enforced:

1. Call delete_entity with "force": false (the default). The tool returns a confirmation_required response describing which entity would be deleted — no file is removed.
2. Call again with "force": true to proceed with deletion.

// Step 1 — inspect
{ "identifier": "P-042", "force": false }
 
// Step 2 — confirm
{ "identifier": "P-042", "force": true }

Available Resources

Resources are read-only data endpoints accessible via hxc:// URIs. An MCP client can subscribe to these URIs to retrieve structured data from the registry.

Example — registry stats

{
  "total_entities": 39,
  "by_type": {
    "program": 4,
    "project": 23,
    "mission": 7,
    "action": 5
  },
  "by_status": {
    "active": 22,
    "completed": 10,
    "on-hold": 4,
    "cancelled": 3
  },
  "tags": {
    "python": 9,
    "api": 7,
    "backend": 6
  }
}

Example — entity hierarchy

Reading hxc://hierarchy/P-001 returns an object with three keys: root (the entity itself), children (child entities), and related (non-hierarchical references).

Available Prompts

Prompts are reusable message templates that guide the LLM when working with the registry. They are surfaced via the prompts/list and prompts/get MCP methods.

Extending the Server

You can register custom tools, resources, and prompts at runtime by creating the server programmatically:

from hxc.mcp.server import create_server

server = create_server(registry_path="/path/to/registry")

# Register a custom tool
def summarize_overdue(registry_path=None, **kwargs):
    """Return all active projects that are past their due date."""
    from datetime import date
    from hxc.mcp.tools import list_entities_tool
    result = list_entities_tool(entity_type="project", status="active", registry_path=registry_path)
    today = date.today().isoformat()
    overdue = [
        e for e in result.get("entities", [])
        if e.get("due_date") and str(e["due_date"]) < today
    ]
    return {"overdue": overdue, "count": len(overdue)}

server.register_tool("summarize_overdue", summarize_overdue)

# Register a custom prompt
server.register_prompt({
    "name": "weekly_review",
    "description": "Generate a weekly status summary across all active projects",
    "arguments": [
        {"name": "focus_tag", "description": "Optional tag to focus the review on", "required": False}
    ]
})

server.run_stdio()

Using YAML as LLM Context

Even without running the MCP server, your HoxCore YAML files are immediately useful as LLM context. Because HoxCore stores everything as human-readable YAML, you can feed entity data directly into any chat interface.

Export a single entity

# Print raw YAML to the terminal, then copy into a chat
hxc show P-001 --raw

# Output as JSON
hxc show P-001 --format json

# Output as YAML (structured, same as --raw but parsed and re-serialised)
hxc show P-001 --format yaml

Collect multiple entities

# List all active projects as JSON and redirect to a file
hxc list project --status active --format json > context.json

# List all entities as YAML
hxc list all --format yaml > registry-snapshot.yml

# Narrow by tag, output JSON
hxc list project --tag ml --format json

Programmatic use

import subprocess, json

result = subprocess.run(
    ["hxc", "show", "P-001", "--format", "json"],
    capture_output=True, text=True
)
project = json.loads(result.stdout)

context = f"""
Project: {project['title']}
Status:  {project['status']}
Tags:    {', '.join(project.get('tags', []))}
Description:
{project.get('description', '')}
"""
# Pass `context` to your LLM of choice

Best Practices

Use UIDs for stable references

When asking an LLM to reference a specific entity across multiple tool calls, prefer UIDs (e.g. proj_abc123def456) over human-readable IDs. UIDs are immutable and will never break if you rename an entity.

Start with list_entities, drill down with get_entity

A natural conversation pattern is to first call list_entities to get an overview, then call get_entity or get_entity_property to retrieve specific details. This keeps token usage efficient.

Write rich descriptions

The search_entities tool searches title and description fields. The more context you include in descriptions when creating entities, the more useful natural-language searches will be.

Keep registries focused

The MCP server exposes your entire registry. Smaller, topic-focused registries produce better LLM interactions than one enormous registry covering unrelated domains. Consider maintaining separate registries for work, research, and personal projects.

Validate before connecting

Run hxc validate before starting the MCP server to ensure all entity files are well-formed. Malformed YAML files are silently skipped by the server, which can cause entities to appear missing.