# Projectmind

> AI-driven architecture browser: MCP server + desktop app. Claude Code, Codex & other AI agents explain your codebase with guided walkthroughs, diagrams and visual artifacts. Read-only, local-first. Tauri + Rust + Svelte.

- **Type:** MCP server
- **Install:** `agentstack add mcp-plaintext-gmbh-projectmind`
- **Verified:** Pending review
- **Seller:** [Plaintext-Gmbh](https://agentstack.voostack.com/s/plaintext-gmbh)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MPL-2.0
- **Upstream author:** [Plaintext-Gmbh](https://github.com/Plaintext-Gmbh)
- **Source:** https://github.com/Plaintext-Gmbh/projectmind
- **Website:** https://plaintext.ch/#projectmind

## Install

```sh
agentstack add mcp-plaintext-gmbh-projectmind
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

ProjectMind
Your project, explained by AI.
by Plaintext · MPL-2.0

ProjectMind uses AI-ready project maps to explain software architecture,
classes, modules and relationships in a way humans and coding agents can
navigate. It's a lightweight, **read-only** architecture browser for source
code that pairs bidirectionally with LLM-driven coding agents — Claude Code,
ChatGPT / OpenAI Codex, Gemini CLI, Cursor, and any other frontier model
that speaks the **Model Context Protocol (MCP)**.

  

An AI agent authors this tour live over MCP — steps, line highlights and narration are pushed into the viewer. No human clicked anything.

> **Status:** v0.8 — MCP server + desktop app for **macOS, Linux and Windows**, with signed auto-updates. Java + Rust language plugins, Spring + Lombok framework recognisers, eight diagram types (bean graph, C4 container, folder heatmap, package tree, inheritance tree, doc graph, architecture layers, language stats), Markdown + HTML browsers (sandboxed), guided AI walkthroughs with quiz support, live AI-generated HTML/Markdown artifacts, and bidirectional MCP sync between LLM, desktop app and browser.

## Quickstart

Install the desktop app + MCP server with one line. The script picks the
right pre-built bundle for your OS / arch, no build toolchain required.

**macOS / Linux:**

```sh
curl -fsSL https://raw.githubusercontent.com/Plaintext-Gmbh/projectmind/master/scripts/install.sh | sh
```

**Windows (PowerShell):**

```powershell
iwr -useb https://raw.githubusercontent.com/Plaintext-Gmbh/projectmind/master/scripts/install.ps1 | iex
```

The desktop app lands in `/Applications` (macOS), `~/.local/share/projectmind`
(Linux), or `%LOCALAPPDATA%\Programs\ProjectMind` (Windows). The MCP server
binary is installed alongside on your `PATH` so any LLM CLI can launch it.

Re-running the script upgrades to the newest release. Pin a specific version
with `PM_VERSION=v1.2.3 …`. Skip components with `PM_NO_APP=1` or
`PM_NO_MCP=1` (Bash) / `$env:PM_NO_APP="1"` (PowerShell).

When the bash installer detects a supported LLM CLI on `PATH` (currently
`claude` and `codex`) it offers to register `projectmind-mcp` for you with a
single `claude mcp add` / `codex mcp add` call. Override with
`PM_REGISTER=yes` (auto-register every detected CLI without prompting) or
`PM_REGISTER=no` (skip the prompt and just print the manual command).

## Why

Modern AI-assisted development with CLI agents is great — until you want to *see* what just changed, *visualise* how the architecture is evolving, or *drill into* the structure without firing up a heavy IDE.

`projectmind` aims to be the missing piece:

- **Standalone** desktop app (Mac & Linux); not a VS Code extension.
- **Read-only** — no editing, no builds. Just an "architecture lens".
- **MCP-bidirectional** — your LLM can say *"show class X with lines 42-58 highlighted"* and the viewer renders it. You can mark code regions and the selection flows back into the conversation.
- **Plugin-based** — languages (Java, Kotlin, TypeScript, …), frameworks (Spring, Lombok, JSF, …) and visualisations (bean graph, package tree, C4, …) are all plugins.

## GUI tabs

The Tauri shell has four tabs (each disabled until a repository is open):

- **Code** — module sidebar, class list, source viewer with stereotype filters, package drilldown.
- **Diagrams** — Mermaid bean graph or package tree; click a node to drill in.
- **MD** — every Markdown file in the repo, grouped by top-level directory, with rendered preview, mermaid blocks, and embedded images.
- **HTML** — every `.html` / `.xhtml` / `.htm` / `.jsp` / `.vm` / `.ftl` file plus HTML snippets extracted from `.java` / `.kt` / `.groovy` / `.scala` string literals (Java text blocks supported). Toggle Rendered ↔ Source; Rendered uses a strict sandbox iframe (no JS, no network) so untrusted repo content stays inert.

## What it looks like

A 21-module Spring Boot monorepo (543 classes), straight after `open_repo`:

| Folder heatmap | C4 container view | Guided AI walkthrough |
|---|---|---|
|  |  |  |

Dark and light themes, five UI languages, resizable panes throughout.

## What works today

The Phase 1 MVP ships a **Rust MCP server** (`projectmind-mcp`) that any
MCP-aware client — Claude Code, ChatGPT, Gemini CLI, Cursor, or your own
custom agent — can connect to. It implements:

| Tool | What it does |
|---|---|
| `open_repo` | Open a repository. Detects Maven multi-module layouts (any `pom.xml`) and Cargo workspaces (any `Cargo.toml` with a `[package]`); falls back to a single module otherwise. |
| `repo_info` | Summary (modules, classes) of the active repo. |
| `module_summary` | Per-module class count and stereotype histogram. |
| `list_classes` | List parsed classes (filter by stereotype). |
| `find_class` | Case-insensitive substring search by simple or fully-qualified name. |
| `class_outline` | Methods, fields, annotations and visibility of a class — without source. |
| `show_class` | Source of a class with optional line-range highlights. |
| `list_changes_since` | Files changed since a given git ref. |
| `show_diff` | Unified diff between two refs (or ref vs working tree). |
| `show_diagram` | Mermaid bean graph (subgraphs per Maven module, colour-coded by stereotype) or package tree. |
| `list_html` | List HTML / XHTML / JSP / Velocity / FreeMarker template files in the open repository. |
| `list_html_snippets` | Scan source files (`.java`, `.kt`, `.groovy`, `.scala`, incl. Java text blocks) for HTML snippets in string literals — filtered to ≥2 tags so XML namespace declarations and short error strings drop out. |
| `plugin_info` | List active language and framework plugins. |
| `start_gui` | Launch the ProjectMind desktop app if it isn't already running (the `view_*` tools auto-launch on demand, so call this only to bring up the window before any view intent). Honours `$PROJECTMIND_APP` for an override path. |
| `open_browser_repo` | Start the in-process browser host that serves the ProjectMind webapp at a tokenized URL — same UI as the Tauri shell, but reachable from any browser. Default binds on `127.0.0.1`; pass `lan: true` to bind on `0.0.0.0` so the URL works from another device on the same WLAN (iPad / phone / second laptop). The bearer token in the URL fragment gates every API call. |
| `browser_status` | Return the running browser host's bind address, tokenized URLs and open repo, or null if no host is started. Side-effect free — handy to re-surface the URL/token without restarting the host. |
| `stop_browser` | Forget the cached browser host status so the next `open_browser_repo` starts fresh. |
| `present_artifact` | Render an AI-generated HTML or Markdown artifact live in every open viewer. Content is passed inline (not read from the repo), so the LLM can show generated dashboards, notes or diagrams without writing them to disk. HTML renders inside a sandboxed, CSP-locked iframe (no scripts, no network); Markdown renders like a `.md` file (mermaid + images). Re-use the `id` to iterate/stream. Max ~2 MB. |
| `list_artifacts` | List the pushed artifacts (id, title, format, size, created/updated) — bodies excluded. |

The browser host is the natural answer to *"open this repo on my iPad
while I keep working on the laptop"*: ask the LLM to call
`open_browser_repo` with `lan: true`, the response carries a
`http://:/#token=…` URL you open on the second device.
Both the Tauri desktop window and the browser tab subscribe to the
same shared statefile, so any subsequent `view_*` / `walkthrough_*`
push from the LLM mirrors to whichever viewers happen to be open.

Active language plugins in Phase 1:

- **Java** — Tree-sitter parser. Classes, interfaces, enums, records; methods, fields, annotations, visibility.
- **Rust** — Tree-sitter parser. Structs, enums, traits, unions; `impl` blocks attach methods and lift `impl Trait for T` as annotations on `T`. Module namespace is derived from the nearest `[package].name`.

Active framework recognisers in Phase 1:

- **Spring** — `@Service`, `@RestController`, `@Controller`, `@Component`, `@Repository`, `@Configuration`. Constructor and field injection (`@Autowired`, `@Inject`, `@Resource`) become Mermaid edges.
- **Lombok** — `@Data`, `@Value`, `@Builder`, `@SuperBuilder`, `@*ArgsConstructor`, `@ToString`, `@EqualsAndHashCode`, `@Slf4j`/`@Log*`, `@Getter`, `@Setter`, `@With`, … attached as a `lombok` stereotype with the detected annotations in `class.extras`.

Smoke-tested against real codebases: a 21-module Spring Boot Maven monorepo parses to **~500 classes** with stereotype histograms and a Mermaid bean graph grouped by module; an 8-crate Cargo workspace (this repo) parses to ~60 classes with per-crate modules.

## Build the MCP server (Ubuntu / Debian)

This is the path you want for **using `projectmind` from any MCP-aware
agent (Claude Code, ChatGPT, Gemini CLI, …) on Ubuntu** — no GUI required.

The repo ships an installer for the impatient:

```bash
git clone git@github.com:Plaintext-Gmbh/projectmind.git
cd projectmind
./scripts/install-ubuntu.sh             # MCP server only
# or:
./scripts/install-ubuntu.sh --with-app  # also build the Tauri shell
```

The script installs build prerequisites, the Rust toolchain (via rustup, if missing), then builds and prints a ready-made `.mcp.json` snippet. If you'd rather install manually:

```bash
sudo apt update
sudo apt install -y build-essential pkg-config libssl-dev cmake git curl
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

git clone git@github.com:Plaintext-Gmbh/projectmind.git
cd projectmind
cargo build --release --bin projectmind-mcp

# Result: target/release/projectmind-mcp
```

## Build the MCP server (macOS)

```bash
# Prerequisites — Homebrew + Rust
brew install rustup-init || true
rustup-init -y
source "$HOME/.cargo/env"

git clone git@github.com:Plaintext-Gmbh/projectmind.git
cd projectmind
cargo build --release --bin projectmind-mcp
```

## Build the Tauri shell (optional, GUI)

The Tauri app is the read-only graphical browser. It is the same engine, just with a UI on top.

### Ubuntu / Debian

```bash
# Tauri prerequisites
sudo apt install -y \
  libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev \
  librsvg2-dev libsoup-3.0-dev libjavascriptcoregtk-4.1-dev patchelf

# Node toolchain (for the frontend)
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Build
cd app
pnpm install
pnpm tauri build
```

### macOS

```bash
# Node toolchain
brew install pnpm

cd app
pnpm install
pnpm tauri build
```

Run the app in dev mode (live-reload):

```bash
cd app && pnpm tauri dev
```

## Use with an MCP-aware agent

ProjectMind speaks the **Model Context Protocol (MCP)**, so any frontier
LLM client that supports MCP can drive it: Claude Code, ChatGPT desktop,
Gemini CLI, Cursor, Continue, or your own scripted agent. Add the server
to whichever config the client uses (e.g. `.mcp.json` for Claude Code,
`mcp_settings.json` for Cursor):

```json
{
  "mcpServers": {
    "projectmind": {
      "type": "stdio",
      "command": "/absolute/path/to/projectmind-mcp",
      "env": {
        "PROJECTMIND_LOG": "info"
      }
    }
  }
}
```

### Where is `projectmind-mcp` on disk?

Pick whichever of these you have installed:

- **Desktop app installed** — the MCP server is bundled next to the GUI
  binary, so you can point your client straight at the in-app path. No
  separate install step:
  - **macOS:** `/Applications/ProjectMind.app/Contents/MacOS/projectmind-mcp`
  - **Linux (`.deb` / `.AppImage`):** `/usr/bin/projectmind-mcp` (`.deb`
    installs to `/usr/bin/`; `.AppImage` mounts a temporary FUSE root —
    extract the AppImage with `--appimage-extract` if you need the binary
    on a stable path)
  - **Windows (`.msi`):** `C:\Program Files\ProjectMind\projectmind-mcp.exe`
- **MCP-only install** (without the desktop app) — use the standalone
  tarball from the [Releases page](https://github.com/Plaintext-Gmbh/projectmind/releases/latest)
  or the helper scripts under [`scripts/`](scripts/). The binary lands
  wherever you placed it (commonly `~/.local/bin/projectmind-mcp`).
- **From source** — `target/release/projectmind-mcp` after
  `cargo build --release --bin projectmind-mcp`.

Claude Code users can register the bundled binary in one line:

```bash
# macOS
claude mcp add projectmind /Applications/ProjectMind.app/Contents/MacOS/projectmind-mcp
```

Re-running the same command after a desktop-app upgrade is a no-op, so
the MCP server stays in lockstep with the GUI version automatically.

Restart the client. From a session, you can then ask things like:

- *"Open the repo at `/home/me/projects/my-spring-app` and tell me how many services and controllers there are per module."*
- *"Find any class containing `Auszahl` and outline the most relevant one."*
- *"Show me the `UserService` class — highlight lines 80-95."*
- *"Which files changed since HEAD~5? Group them by module."*
- *"Render the bean graph as a Mermaid diagram."*

The agent will pick the right tool calls from the list above.

### Pre-built binary

The latest release on the
[Releases page](https://github.com/Plaintext-Gmbh/projectmind/releases/latest)
ships `projectmind-mcp` and desktop app bundles where the GitHub runners
can build them. New releases are produced by the **Auto-Release** workflow
from the Actions tab; it bumps the version, opens a PR, merges, tags, and
publishes in one shot.

## Tests / development

For day-to-day work, use the small `./build` helper:

```bash
./build dev      # Tauri app with hot reload
./build check    # cargo fmt --check + cargo clippy
./build test     # cargo test --workspace --all-targets + doctests
./build ci       # check + test
./build mcp      # release-build and smoke-test projectmind-mcp
./build app      # desktop app bundle for this machine
./build dist     # app bundle plus tar.gz + sha256 package
```

The lower-level CI wrapper is still available when you need exactly the
workflow commands:

```bash
./scripts/ci.sh check
./scripts/ci.sh test
./scripts/ci.sh all
```

CI runs on **Ubuntu 22.04** and **macOS 14** for every push and pull request, plus a Linux release-build smoke test.

## Architecture

A Cargo workspace with seven crates plus a Svelte frontend:

| Crate | Purpose |
|---|---|
| `crates/plugin-api` | Public traits and types (no implementations) |
| `crates/core` | Repo loader, file walker, plugin pipeline, Maven + Cargo discovery, git helpers |
| `crates/mcp-server` | The `projectmind-mcp` binary (JSON-RPC over stdio) |
| `plugins/lang-java` | Java parser via Tree-sitter |
| `plugins/lang-rust` | Rust parser via Tree-sitter |
| `plugins/framework-spring` | Spring stereotypes + bean graph |
| `plugins/framework-lombok` | Lombok annotation recogniser |
| `app/src-tauri` | Tauri shell (Rust backend exposing Tauri commands) |
| `app/src/` | Svelte + TypeScript frontend with Mermaid integration |

Phase 1 plugins are **statically registered**. Phase 2 will add dynamic loading from a `./plugins/` directory next to the binary, so third-party plugins can drop in `.so` / `.dylib` files.

## Reference docs (in the repo)

- [`docs/architecture.md`](docs/architecture.md) — workspace layout, plugin API, MCP tool schemas. Living reference, kept in sync with the code.
- [`docs/SYNC.md`](docs/SYNC.md) — how the MCP server and the Tauri GUI stay in sync (statefile + view intents).
- [`docs/branding.md`](docs/branding.md) — colour, typography, logo specs.
- [`docs/reviews/`](docs/reviews/) — historical architecture reviews.

## Roadmap & planning

The roadmap and feature backlog now live on **GitHub**:

- **[Issues](https://github.com/Plaintext-Gmbh/projectmind/issues)** — concrete, schedulable work items (bugs, features, sub-tasks of epics)
- **[Project board](https://github.com/Plaintext-Gmbh/projectmind/projects)** — Kanban view of what's in flight
- **[Discussions](https://github.com/Plaintext-Gmbh/projectmind/discussions)** — vision, longer-form des

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Plaintext-Gmbh](https://github.com/Plaintext-Gmbh)
- **Source:** [Plaintext-Gmbh/projectmind](https://github.com/Plaintext-Gmbh/projectmind)
- **License:** MPL-2.0
- **Homepage:** https://plaintext.ch/#projectmind

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-plaintext-gmbh-projectmind
- Seller: https://agentstack.voostack.com/s/plaintext-gmbh
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.