# Onboarding MCP Server 🚀

A local-first Model Context Protocol (MCP) server that empowers AI coding assistants (e.g., Cursor, Claude Code, Antigravity IDE) to autonomously map codebases, transcribe onboarding videos with keyframe screenshots, and maintain structured knowledge vaults in Obsidian directly from IDE chat interactions.

---

## 🌟 Key Capabilities

1. **`set_vault_path`**: Dynamically configure the active Obsidian vault directory for session state from IDE chat.
2. **`set_workspace_path`**: Dynamically configure the target codebase workspace directory for session state from IDE chat.
3. **`get_codebase_structure`**: Recursively map code directory structures and detect dependency manifests, respecting `.gitignore` (uses configured session workspace path or optional `workspace_path` parameter).
4. **`process_video`**: Transcribe onboarding videos using `faster-whisper` (CPU int8), extract scene keyframes via OpenCV, and output timestamp-aligned transcript data.
5. **`write_obsidian_note`**: Write structured Markdown notes and MOCs (Maps of Concepts) directly into the user's local Obsidian vault (uses configured session vault path or optional `vault_path` parameter).

---

## 🚀 Quickstart

### Option 1: Docker (Recommended - Zero Host Setup)

Build and run the containerized server with pre-packaged `ffmpeg` and dependencies. Note: because Docker containers run in an isolated environment, volume mounts (`-v`) are required to grant the container access to host directories specified in chat:

```bash
# Build the Docker image
make build-docker

# Run container (mount host directories so chat can access them)
docker run -i --rm -v $HOME:$HOME onboarding-mcp-server
```

### Option 2: Local Python Environment (No Volume Mounts Needed)

Runs directly on your host OS. Any absolute path passed from IDE chat works natively without volume mounts.

Requires Python 3.11+ and `ffmpeg` installed on host (`brew install ffmpeg` on macOS).

```bash
# Install dependencies into virtualenv
make setup

# Run the tests
make test

# Run the MCP server over stdio
.venv/bin/python -m onboarder.server
```

---

## ⚙️ IDE Chat Integration & Setup

The IDE chat assistant can configure workspace and vault paths dynamically at any point during a chat session:

- `set_workspace_path(path="/path/to/repo")`
- `set_vault_path(path="/path/to/ObsidianVault")`

Alternatively, individual tools (`get_codebase_structure`, `write_obsidian_note`, `process_video`) accept optional `workspace_path` and `vault_path` arguments directly.

### Docker Configuration Example (`claude_desktop_config.json` / Cursor / Antigravity)

Mount your user home directory (or relevant code/vault folders) so paths passed in chat are accessible:

```json
{
  "mcpServers": {
    "onboarding-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/Users/yourname:/Users/yourname",
        "onboarding-mcp-server"
      ]
    }
  }
}
```


### Local Python Configuration Example

```json
{
  "mcpServers": {
    "onboarding-mcp": {
      "command": "/absolute/path/to/onboarding-mcp/.venv/bin/python",
      "args": ["-m", "onboarder.server"]
    }
  }
}
```

---

## 🛠 Developer Workflow

```bash
make setup    # Set up venv and install dev dependencies
make test     # Run pytest suite
make lint     # Run ruff check and mypy type checking
make format   # Run ruff formatter
```

---

## 📄 License

MIT