# Headquarter

**Headquarter** is an open-source, AI-first business and project management tool. It uses a "Ghost" architecture where data is stored locally in human-readable Markdown and JSON files, exposed via the **Model Context Protocol (MCP)**.

## Installation

### Quick Install (Recommended)

Download the latest binary for your platform from [GitHub Releases](https://github.com/axeldotdev/headquarter/releases):

| Platform              | File                            |
| --------------------- | ------------------------------- |
| macOS (Apple Silicon) | `headquarter-macos-arm64.zip`   |
| macOS (Intel)         | `headquarter-macos-x64.zip`     |
| Linux                 | `headquarter-linux-x64.tar.gz`  |
| Windows               | `headquarter-windows-x64.zip`   |

Extract the archive and configure your MCP client (see below).

### Install from Source (For Developers)

```bash
git clone https://github.com/axeldotdev/headquarter.git
cd headquarter
npm install
npm run build
```

### Configure Your MCP Client

Add the server to your MCP client configuration. For **Claude Desktop**, edit your config file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

**Using the binary (Quick Install):**

```json
{
  "mcpServers": {
    "headquarter": {
      "command": "/path/to/headquarter-macos-arm64"
    }
  }
}
```

**Using Node.js (From Source):**

```json
{
  "mcpServers": {
    "headquarter": {
      "command": "node",
      "args": ["/path/to/headquarter/dist/index.js"]
    }
  }
}
```

Replace `/path/to/...` with the actual path to the binary or cloned repository.

### Verify Installation

Restart Claude Desktop (or your MCP client) and the Headquarter tools should be available. You can test by asking Claude to list projects or create a new one.

### Development

For debugging, use the MCP Inspector:

```bash
npm run inspect
```

To build binaries locally (requires [Bun](https://bun.sh)):

```bash
npm run build:bin
```

## 🛠 Tech Stack

- **Language:** Node.js with **TypeScript** (Strict Mode).
- **Architecture:** Modular MCP Server + CLI.
- **Protocol:** MCP SDK 1.25+
- **Data Format:** Markdown with YAML Frontmatter (via `gray-matter`) and JSON.
- **Validation:** `Zod` for schema definition and runtime type-safety.
- **Code Quality:**
  - **ESLint:** Logic & Type checking (The "PHPStan").
  - **Prettier:** Formatting (The "Pint").
  - **Husky:** Git hooks for pre-commit linting.

## Tools

- [x] list_projects
- [x] get_project(id)
- [x] create_project(name, content)
- [x] update_project(id, name, content)
- [x] delete_project(id)
- [x] list_issues(?project_id)
- [x] get_issue(id)
- [x] create_issue(name, content, status, priority)
- [x] update_issue(id, name, content, status, priority)
- [x] delete_issue(id)
- [x] list_clients
- [x] get_client(id)
- [x] create_client(name, address, website, email, phone)
- [x] update_client(id, name, address, website, email, phone)
- [x] delete_client(id)
- [x] list_contacts(?client_id)
- [x] get_contact(id)
- [x] create_contact(name, email, phone, job_title)
- [x] update_contact(id, name, email, phone, job_title)
- [x] delete_contact(id)
- [x] list_notes
- [x] get_note(id)
- [x] create_note(content)
- [x] update_note(id, content)
- [x] delete_note(id)

## 🚀 Current Roadmap

- [x] Initial Project structure & Git config.
- [x] Quality tools setup (ESLint, Prettier, Husky).
- [x] Server setup
- [x] Build every tools