# Blobi — Claude Desktop Extension

The bridge between **Claude Desktop** and the **Blobi®** app on your Mac.

Blobi is a teaching-portfolio app: you build Experiences, Courses, and Programs, and keep a reflection journal alongside them. This extension lets you do that work by talking to Claude — create an Experience, pull up your reflections, rewrite a section — while everything stays in your portfolio.

**Blobi remains the home for your work.** This extension does not store, copy, or host anything. It only exposes Blobi's tools to Claude Desktop over a connection that never leaves your Mac.

**Requires:** Blobi for macOS, running, with **External AI Access** enabled.

---

## Install

### From the Claude Desktop extension directory

Once Blobi is listed, install it from **Claude Desktop → Settings → Extensions** and skip to [Setup](#setup).

### Manual install

1. Download **[blobi.mcpb](https://raw.githubusercontent.com/schoolProjectIdeas/blobi-claude-extension/main/blobi.mcpb)** — this link always serves the current release.
2. Open **Claude Desktop → Settings → Extensions**.
3. Click **Advanced** → install the downloaded `.mcpb` file.


**Download URLs**

| Purpose | URL |
| --- | --- |
| Always latest — use in docs, on the website, and for end users | `https://raw.githubusercontent.com/schoolProjectIdeas/blobi-claude-extension/main/blobi.mcpb` |


---

## Setup

In the Blobi app:

1. Go to **Console → AI Service Provider (AISP)**.
2. Turn on **Enable External AI Access**.
3. Click **Connect Claude Desktop**.

Claude Desktop will prompt you to confirm the install. If Claude Desktop isn't installed yet, Blobi shows a **Download Claude Desktop** button instead, with an **Already installed? Connect** link next to it.

Blobi generates a fresh security token each time it launches, and the extension reads that token on every request — so a restart never breaks the connection.

---

## Example prompts

Once connected, talk to Claude normally:

> Create an experience called The Cycle of Water

> Show my reflections for this experience

> Rewrite the objectives section using the experience you have in context

---

## Tools

The extension itself defines no tools — it forwards `tools/list` to Blobi, so the tool set always matches the version of Blobi you're running. Blobi 1.28 exposes 29 tools.

Each tool carries MCP [tool annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) — a human-readable **Title**, plus behavioural hints Claude Desktop uses to decide how to present the call and when to ask you to confirm it:

| Annotation | Meaning |
| --- | --- |
| **Read-only** | `readOnlyHint: true` — the tool only reads; it never modifies your portfolio. |
| **Destructive** | `destructiveHint: true` — the tool overwrites or deletes existing content. Expect a confirmation prompt. |
| **Write** | Neither hint set — the tool creates or changes something, but does not destroy existing content. |

These are advisory hints, not enforcement. Blobi enforces its own permissions on every call regardless of what a client does with the annotations.

### Documents

| Tool | Title | Annotations | What it does |
| --- | --- | --- | --- |
| `list_documents` | List Documents | Read-only | Lists documents of a given type (experience, course, program) with summary metadata, paginated. |
| `get_document_metadata` | Get Document Metadata | Read-only | Returns a document's full metadata and its total block count, without the content. |
| `get_document_content` | Get Document Content | Read-only | Returns a document's editor content blocks, paginated. |
| `create_document` | Create Document | Write | Creates a new document with a name and optional classification metadata. |
| `update_document_metadata` | Update Document Metadata | Destructive | Updates a document's classification metadata; only the fields you provide change. |
| `delete_document` | Delete Document | Destructive | Permanently deletes a document and its reflection journal. Irreversible. |
| `open_document` | Open Document | Write | Opens a document in Blobi's editor, saving any currently open document first. |

### Metadata and links

| Tool | Title | Annotations | What it does |
| --- | --- | --- | --- |
| `list_metadata_options` | List Metadata Options | Read-only | Lists your categories (with their programs), grades, cognitive levels, and activity types. |
| `link_experience_to_course` | Link Experience to Course | Write | Links or unlinks an experience to or from a course. |
| `link_course_to_program` | Link Course to Program | Write | Links, unlinks, or updates a course's membership in a program, including required flag and order. |

### Editor content

These act on the document currently open in Blobi's editor.

| Tool | Title | Annotations | What it does |
| --- | --- | --- | --- |
| `write_editor_content` | Write Editor Content | Write | Appends markdown to the open document, parsed into blocks. |
| `replace_editor_content` | Replace Editor Content | Destructive | Replaces all content in the open document with new markdown. |
| `list_sections` | List Sections | Read-only | Lists the top-level sections (headers) in the open document with their positions. |
| `replace_section` | Replace Section | Destructive | Replaces the body of one section, keeping its header. |
| `delete_section` | Delete Section | Destructive | Deletes a section — its header, body, and nested subsections. |
| `remove_content` | Remove Content | Destructive | Removes a single text block matched by its text content. |
| `replace_content` | Replace Content | Destructive | Replaces the text of a single block, keeping its type and position. |
| `save_document` | Save Document | Write | Saves the open document's editor content to the database immediately. |
| `close_document` | Close Document | Write | Saves and closes the open document, returning to the document list. |

### Reflections

| Tool | Title | Annotations | What it does |
| --- | --- | --- | --- |
| `get_reflection_entries` | Get Reflection Entries | Read-only | Reads all reflection journal entries for the current document. |
| `get_child_reflections` | Get Child Reflections | Read-only | Aggregates reflections across child documents — a Course's Experiences, a Program's Courses and Experiences. |
| `create_reflection` | Create Reflection | Write | Creates a new reflection journal entry in the open document. |
| `classify_reflection` | Classify Reflection | Destructive | Updates a reflection entry's type and tags based on its content. |
| `get_reflection_tags` | Get Reflection Tags | Read-only | Returns the tag schema for a module type — entry types, tags, valid classifications. |
| `get_reflection_guide` | Get Reflection Guide | Read-only | Returns the Reflection Journal quick-start guide and its pedagogical framework. |
| `get_mission` | Get Mission | Read-only | Retrieves your mission statements — your stated goals for your teaching practice. |

### Saved commands

| Tool | Title | Annotations | What it does |
| --- | --- | --- | --- |
| `list_commands` | List Commands | Read-only | Lists your saved custom commands, or the full details of one by name. |
| `save_command` | Save Command | Write | Saves a new custom command, or updates an existing one. |
| `delete_command` | Delete Command | Destructive | Deletes a saved custom command by name. |

**Totals:** 11 read-only, 9 destructive, 9 write.

Most editor and reflection tools require a document to be open in Blobi. Called with nothing open, they return an error telling Claude to call `open_document` first — `get_mission`, `get_reflection_tags`, and `get_reflection_guide` are the exceptions, since they read from the data store rather than the editor.

---

## Privacy Policy

**The connection runs locally on your Mac.** Claude Desktop launches this bridge, which talks to Blobi over `localhost` (`127.0.0.1:9090`) using a bearer token that Blobi regenerates on every launch. No server sits between them.

**Blobi never uploads your documents.** Your portfolio lives on your Mac. This extension does not send it anywhere.

**Content Claude works on travels through your own Claude account.** When you ask Claude to read or edit a document, the bridge passes that content to Claude Desktop, and Claude Desktop sends it to Anthropic as part of your conversation — the same as anything else you type into Claude. That data is governed by your own Claude account settings, including your training and data-retention preferences. Blobi has no visibility into or control over it, and nothing is sent while Claude is idle.

**You control the connection.** Turn off **Enable External AI Access** in Blobi's Console to cut Claude Desktop off at any time.

Full policy: **https://blobi.net/legal.html#privacy-policy**

---

## Troubleshooting

**Claude says it can't reach Blobi.**
- Blobi must be *running*. The bridge talks to the live app, not to files on disk.
- Check that **Enable External AI Access** is on in **Console → AI Service Provider (AISP)**.

**The connection worked before and stopped.**
- Restart Blobi. That regenerates the security token, which the extension re-reads on its next request.

**Claude doesn't show Blobi's tools at all.**
- Open **Claude Desktop → Settings → Extensions** and confirm Blobi is installed and enabled.
- Restart Claude Desktop after installing.

**Still stuck.**
- The bridge writes a log to `/tmp/blobi-bridge.log`. It records connection attempts and errors, and is useful to attach to a bug report.
---

## Building

`build.sh` is the same script the Blobi app uses to build its bundled copy, adapted for this repository — so the release asset and the copy the app installs are built identically.

```bash
./build.sh
```

It reads the version from `manifest.json`, stages the four bundled files in a temp directory, validates the staged manifest, zips it to `blobi.mcpb`, and verifies that every packed file matches its source. The bundle contains exactly `manifest.json`, `index.js`, `icon.png`, and `README.md` — the staging step keeps `LICENSE`, `CHANGELOG.md`, `package.json`, and the previous `blobi.mcpb` out of the artifact.

**The output filename is always plain `blobi.mcpb`, never versioned.** The always-latest download URL resolves by asset filename, so that name has to be byte-for-byte identical in every release; a versioned filename would break it. The version lives in `manifest.json` and in the release tag.

Because the built bundle is committed next to the sources it contains, editing `README.md`, `index.js`, `manifest.json`, or `icon.png` leaves the committed `blobi.mcpb` stale until you re-run `./build.sh`.

Release checklist:

1. Bump `version` in `manifest.json` (it tracks the Blobi app release) and add a `CHANGELOG.md` entry.
2. Run `./build.sh`.
3. Commit the rebuilt `blobi.mcpb` along with the source changes.
4. Tag the commit `v<version>` and push the tag.
5. Create the GitHub Release on that tag and attach `blobi.mcpb`, keeping the filename exactly as built.
6. Open the release page and right-click the asset to confirm the URL — asset URLs are case-sensitive and match the uploaded filename exactly.

**Requirements:** Node.js 16 or later, and `zip` (preinstalled on macOS). The bridge itself has no third-party dependencies; it uses Node built-ins only.

---

## Issues and contact

- Bugs and feature requests: [GitHub Issues](../../issues)
- Support: **support@blobi.net**

---

## License

This extension (the Claude Desktop bridge) is licensed under the MIT License — see [LICENSE](LICENSE). The Blobi app itself is proprietary software, © Oneness LLC. This license covers only the code in this repository.

### Trademarks

Blobi® is a registered trademark of Oneness LLC. The MIT License above covers the source code in this repository only — it grants no rights to the Blobi name, logo, or icon (`icon.png`), which remain the property of Oneness LLC. Forks and derivative works must not use the Blobi name or marks in a way that suggests affiliation with or endorsement by Oneness LLC.

Blobi® is made by Oneness LLC. https://blobi.net