Metadata-Version: 2.4
Name: hoxcore
Version: 0.1.4
Summary: HoxCore - A meta-manager for organizational objects (projects, missions, activities, programs)
Author-email: "Salvador D. Escobedo" <salvadec@live.com.mx>
License: # LICENSE
        MIT License
        
        Copyright (c) 2025 Salvador D. Escobedo
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/SDEscobedo/hoxcore
Project-URL: Repository, https://github.com/SDEscobedo/hoxcore
Project-URL: Bug Tracker, https://github.com/SDEscobedo/hoxcore/issues
Keywords: project-management,registry,cli,mcp,organizational
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Utilities
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Dynamic: license-file

# HoxCore

<p align="center">
    <img src="https://raw.githubusercontent.com/SDEscobedo/hoxcore/refs/heads/master/images/hoxcore_logo.jpg" alt="Hoxcore" width="400">
</p>


## What is HoxCore?

HoxCore is a **meta-manager** — a low-level tool that centralizes the core metadata of organizational objects into a single, unified registry. Rather than managing execution or visualization directly, HoxCore acts as the foundational layer that independent software can build upon.

### Organizational Object Types

HoxCore handles four categories of objects:

| Type | Orientation | Description |
|---|---|---|
| **Projects** | Goal-oriented | Has a defined finalization point; decoupled from execution |
| **Missions** | Event-oriented | Linked to execution; tied to a specific occurrence or execution window |
| **Activities** | Action-oriented | No definite end; represents indefinite, ongoing progression |
| **Programs** | Container | Groups and organizes Projects, Missions, and/or Activities |

### Design Philosophy

HoxCore is intentionally minimal and low-level. It owns the metadata — everything else is up to you. Independent tools can be built on top of HoxCore for visualization, reporting, dashboards, or richer management interfaces, all reading from the same single source of truth.

## Installation

### From PyPI

```bash
pip install hoxcore
```

### For Development

```bash
# Clone the repository
git clone https://github.com/SDEscobedo/hoxcore
cd hoxcore

# Create a virtual environment (optional but recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .
```

## Usage

HoxCore manages your projects using a simple file-based system. It operates on a **Registry** (a directory on your disk) that holds various **Entities** (Programs, Projects, Missions, or Actions) stored as individual files. This mental model allows you to maintain full control over your data while using simple CLI commands to organize your workflow.

### Available Commands

| Command | Description |
| :--- | :--- |
| `init` | Initialize a new registry |
| `create` | Create a new entity (project, program, mission, action) |
| `list` | List entities with optional filters |
| `show` | Show full details of a specific entity |
| `get` | Get a specific property from an entity |
| `edit` | Edit properties of an entity |
| `delete` | Delete an entity from the registry |
| `validate` | Validate registry integrity |
| `registry` | Manage registry location |
| `mcp` | Start the MCP server for LLM access |

### Quick Start Guide

#### 1. Initialize a Registry

Set up your first registry to start storing entities.

```bash
# Initialize a registry in the current directory
hxc init

# Initialize in a specific directory
hxc init ~/my-registry

# Initialize without git integration
hxc init --no-git
```

#### 2. Create Entities
   
Add projects, programs, missions, or actions to your registry.

```bash
# Create a basic project
hxc create project "My First Project"

# Create a project with a description, tags, and due date
hxc create project "API Redesign" --description "Redesign the public API" --tags backend api --due-date 2025-06-01

# Create a program (container for projects)
hxc create program "Q2 Initiatives"

# Create a mission (execution-oriented, time-bound)
hxc create mission "Deploy v2.0"

# Create an action (ongoing, no end date)
hxc create action "Monitor system health"
```
#### 3.  List and Inspect
   
View your registry content and drill down into details.

```bash
# List all projects
hxc list project

# List all entities in the registry
hxc list all

# Filter by status or tag
hxc list project --status active
hxc list project --tag backend

# Show full details of a specific entity
hxc show <uid>

# Get a specific property
hxc get <uid> status
```

#### 4. Edit and Delete
   
Update or remove entities as your tasks progress.

```bash
# Change status or add a tag
hxc edit <uid> --set-status completed
hxc edit <uid> --add-tag backend

# Set a new due date
hxc edit <uid> --set-due-date 2025-06-01

# Delete an entity (prompts for confirmation)
hxc delete <uid>

# Delete immediately without prompt
hxc delete <uid> --force
```

**Getting Help**

If you need more information about a specific command or general flags:

```bash
# General help
hxc --help

# Command-specific help
hxc create --help
hxc list --help
```

---

## MCP Server (Model Context Protocol)

HoxCore includes a built-in MCP server that exposes registry functionality to LLMs through a standardized interface. This allows AI assistants (like Claude) to interact with your HoxCore registries directly.

### Starting the Server

```bash
# Start with the default or configured registry
hxc mcp

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

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

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

# Start in read-only mode — write tools are not exposed to the LLM
hxc mcp --read-only
```
You can also start the server programmatically:

```python
from hxc.mcp.server import create_server

# Normal mode (all tools)
server = create_server(registry_path="/path/to/registry")
server.run_stdio()

# Read-only mode (write tools omitted)
server = create_server(registry_path="/path/to/registry", read_only=True)
server.run_stdio()
```

### Connecting to Claude (or other MCP-compatible clients)

Add HoxCore to your MCP client configuration. For Claude Desktop, update your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "hoxcore": {
      "command": "hxc",
      "args": ["mcp", "--registry", "/path/to/your/registry"]
    }
  }
}
```
To restrict the assistant to read-only access, add `"--read-only"` to the args list:

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

### Available Tools

The MCP server exposes tools that an LLM can call. By default all seven tools are available; start with `--read-only` to expose only the four read tools.
 
| Tool | Type | Description |
|---|---|---|
| `list_entities` | Read | List entities in the registry, with optional filters for type, status, tags, category, and parent |
| `get_entity` | Read | Retrieve a specific entity by its ID or UID |
| `search_entities` | Read | Full-text search across entity titles and descriptions |
| `get_entity_property` | Read | Fetch a specific property from an entity, with support for list indexing and key filtering |
| `create_entity` | Write | Create a new entity (program, project, mission, or action) in the registry |
| `edit_entity` | Write | Update scalar fields or incrementally add/remove tags on an existing entity |
| `delete_entity` | Write | Delete an entity; requires a two-step confirmation (`force=false` first, then `force=true`) |

### Available Resources

Resources are accessible via `hxc://` URIs:

| URI | Description |
|---|---|
| `hxc://entity/{identifier}` | A specific entity by ID or UID (YAML) |
| `hxc://entities/{type}` | All entities of a given type (JSON) |
| `hxc://hierarchy/{identifier}` | Entity hierarchy and relationships (JSON) |
| `hxc://registry/stats` | Registry statistics and overview (JSON) |
| `hxc://search?q={query}` | Search results for a query (JSON) |

### Extending the Server

You can register custom tools, resources, and prompts at runtime:

```python
from hxc.mcp.server import create_server

server = create_server()

# Register a custom tool
def my_tool(registry_path=None, **kwargs):
    """My custom tool description."""
    return {"result": "..."}

server.register_tool("my_tool", my_tool)

# Register a custom prompt
server.register_prompt({
    "name": "my_prompt",
    "description": "A helpful prompt template",
    "arguments": [
        {"name": "context", "description": "Context for the prompt", "required": True}
    ]
})

server.run_stdio()
```

---

## Contributing

Contributions are welcome! Please see [CONTRIBUTING](CONTRIBUTING.md) for details on our development workflow, including branch naming and test requirements.

