# LifeOS MCP

Give any AI agent read access to your LifeOS knowledge base — Claude Desktop, Claude Code, Cursor, ChatGPT, Codex, or any MCP-compatible client.

The server reads from `~/lifeos/` and surfaces everything through `lifeos://` resource URIs and `lifeos__*` tool names.

---

## Install

### Once published (coming soon)

```bash
npx lifeos-mcp
```

### From source (now)

```bash
git clone https://github.com/bwats/lifeos-mcp
cd lifeos-mcp
npm install && npm run build
node bin/lifeos-mcp.js
```

### Global install from source

```bash
cd ~/lifeos-mcp
npm install -g .
lifeos-mcp  # starts the MCP server on stdio
```

---

## What it exposes

`lifeos-mcp` gives any MCP-compatible AI client direct read access to:

| Surface | Path in ~/lifeos/ | Tool |
|---------|-------------------|------|
| Identity | `identity.md` | `lifeos__get_identity` |
| Preferences | `preferences.md` | `lifeos__get_preferences` |
| Skills | `skills/*/` | `lifeos__list_skills`, `lifeos__read_skill` |
| Projects | `projects/*.md` | `lifeos__list_projects`, `lifeos__read_project` |
| Wiki | `wiki/pages/**/*.md` | `lifeos__list_wiki_pages`, `lifeos__read_wiki_page` |
| Rules | `system/*.md` | `lifeos__list_rules`, `lifeos__read_rule` |
| Any file | (path-safe) | `lifeos__read_file` |
| Search | (full-text) | `lifeos__search` |

---

## Modes

| Invocation | What happens |
|---|---|
| `lifeos-mcp` | Start MCP server on stdio (default) |
| `lifeos-mcp --stdio` | Start MCP server on stdio (explicit) |
| `lifeos-mcp list` | List rituals in `~/lifeos/cadence/rituals/` |
| `lifeos-mcp validate <ritual.md>` | Validate a ritual spec file |
| `lifeos-mcp render <ritual.md> --to <harness>` | Render ritual to a target harness |
| `lifeos-mcp --help` | Show all subcommands and options |

---

## Configure MCP clients

### Claude Desktop

macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "lifeos": {
      "command": "npx",
      "args": ["lifeos-mcp"]
    }
  }
}
```

Or from source:

```json
{
  "mcpServers": {
    "lifeos": {
      "command": "node",
      "args": ["/Users/yourname/lifeos-mcp/bin/lifeos-mcp.js"]
    }
  }
}
```

### Cursor (`settings.json`)

```json
{
  "mcpServers": {
    "lifeos": {
      "command": "node",
      "args": ["/Users/yourname/lifeos-mcp/bin/lifeos-mcp.js"]
    }
  }
}
```

### Claude Code (`~/.claude/settings.json`)

```json
{
  "mcpServers": {
    "lifeos": {
      "command": "node",
      "args": ["/Users/yourname/lifeos-mcp/bin/lifeos-mcp.js"]
    }
  }
}
```

### OpenAI Codex (`codex.json`)

```json
{
  "mcpServers": {
    "lifeos": {
      "command": "node",
      "args": ["/Users/yourname/lifeos-mcp/bin/lifeos-mcp.js"]
    }
  }
}
```

### Custom LifeOS path

Pass `--lifeos-path` or set `LIFEOS_PATH` env var:

```json
{
  "mcpServers": {
    "lifeos": {
      "command": "node",
      "args": [
        "/Users/yourname/lifeos-mcp/bin/lifeos-mcp.js",
        "--lifeos-path", "/custom/path/to/lifeos"
      ]
    }
  }
}
```

---

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `LIFEOS_PATH` | `~/lifeos` | Absolute path to the LifeOS root directory |

---

## Tools

| Tool | Description |
|------|-------------|
| `lifeos__health` | Check server health and LifeOS availability |
| `lifeos__get_identity` | Read `identity.md` — frontmatter + body |
| `lifeos__get_preferences` | Read `preferences.md` — frontmatter + body |
| `lifeos__list_skills` | List all skill directory names in `~/lifeos/skills/` |
| `lifeos__read_skill` | Read documentation for a named skill |
| `lifeos__list_rules` | List rule/guideline names from `~/lifeos/system/` |
| `lifeos__read_rule` | Read a specific rule file |
| `lifeos__list_projects` | List project filenames from `~/lifeos/projects/` |
| `lifeos__read_project` | Read a specific project definition |
| `lifeos__list_wiki_pages` | List all wiki page paths recursively |
| `lifeos__read_wiki_page` | Read a wiki page by path |
| `lifeos__search` | Full-text search across all LifeOS files |
| `lifeos__read_file` | Read any file under `~/lifeos/` by relative path (path-traversal safe) |
| `lifeos__propose_edge` | Propose a typed semantic edge between two knowledge nodes |
| `lifeos__accept_edge` | Accept a proposed edge (write-opt-in required) |
| `lifeos__reject_edge` | Reject a proposed edge (write-opt-in required) |
| `lifeos__read_pending_queue` | List pending edge proposals (always read-only) |

---

## Resources

| URI | Description |
|-----|-------------|
| `lifeos://identity` | LifeOS identity profile (`identity.md`) |
| `lifeos://preferences` | User preferences (`preferences.md`) |
| `lifeos://skills/{name}` | Skill documentation for `~/lifeos/skills/{name}/` |
| `lifeos://projects/{name}` | Project definition for `~/lifeos/projects/{name}.md` |
| `lifeos://wiki/{+path}` | Wiki page at `~/lifeos/wiki/pages/{path}.md` |
| `lifeos://rules/{name}` | System rule at `~/lifeos/system/{name}.md` |

All template resources support listing — clients can enumerate available resources.

---

## CLI subcommands

```bash
# List all rituals with id, title, and trigger summary
lifeos-mcp list

# Validate a ritual spec (structural check)
lifeos-mcp validate ~/lifeos/cadence/rituals/morning-review.md

# Render a ritual to a harness
lifeos-mcp render ~/lifeos/cadence/rituals/morning-review.md --to openclaw
lifeos-mcp render ~/lifeos/cadence/rituals/morning-review.md --to claude-code
```

---

## Renderer interface (pluggable)

Third-party renderers plug in at runtime via `registerRenderer`:

```typescript
import { registerRenderer } from "lifeos-mcp/dist/renderers/index.js";

registerRenderer({
  name: "my-harness",
  async render(spec, body, ctx) {
    return {
      files: [{ path: "/out/job.json", content: JSON.stringify(spec) }],
      summary: `Rendered ${spec.id} to my-harness`,
    };
  },
});
```

Built-in renderers: `openclaw` (cron job JSON), `claude-code` (slash command + launchd plist).

---

## Security

- All file paths are validated to stay within the LifeOS root — no path traversal possible.
- The server is read-only by default; write tools (`lifeos__propose_edge`, `lifeos__accept_edge`, `lifeos__reject_edge`) require explicit opt-in via `~/Library/Application Support/LifeOS/mcp-write-config.json`.
- Only files under `~/lifeos/` (or `LIFEOS_PATH`) are accessible.

---

## Build

```bash
cd ~/lifeos-mcp
npm install
npm run build
# Output: dist/ + bin/lifeos-mcp.js
```

---

## License

MIT