mindswapAI context
mcp server · repo-readable context

Let an AI tool
ask the repo.

If you are new, start here: clone the repo, run one install command, and let Claude Code, Cursor, Codex, or any MCP client read the same project context instead of asking you to explain the repo again.

Back to CLI
1
repo to clone before you start
1
install command to wire MCP locally
0
guesswork when a client asks for context
quick start
$ git clone https://github.com/ShipOrBleed/mindswap.git
✓ clone the project into your machine

$ cd mindswap
✓ open the repo folder

$ npx mindswap init
✓ detect the stack and prepare the handoff files

$ npx mindswap mcp-install
✓ connect supported AI clients to the repo

$
Problem / solution

What mindswap fixes for a new user.

The point is to stop repeating the same repo context every time you change tools or open a fresh session.

problem

The next AI starts blind

Without shared context, every new session asks the same questions and re-discovers the repo from scratch.

solution

Save the repo state once

Mindswap writes the current task, decisions, and handoff files into the project so the next tool can continue from there.

result

Start in seconds, not minutes

Clone, run one setup command, and keep the repo ready for Claude, Cursor, Codex, or any MCP client.

Quick start

The shortest path from clone to working MCP.

Copy these commands in order. The flow is: clone the repo, install locally, then connect your AI client.

1

Clone the repo

Get the project on your machine first.

git clone https://github.com/ShipOrBleed/mindswap.git
2

Enter and initialize

Let mindswap detect the stack and prepare the repo.

cd mindswap && npx mindswap init
3

Connect MCP

Install the local wiring for your editor or AI client.

npx mindswap mcp-install
Tools

The calls an AI client uses first.

These are the calls that matter before anything else because they define how a client reads and updates the repo.

start

mindswap_get_context

Ask what matters now. Returns a synthesized briefing with task, decisions, conflicts, test status, and recent work.

end

mindswap_save_context

Capture what changed. Persists the summary, decisions, blockers, and next steps into the repo state.

search

mindswap_search

Search decisions, history, and state when an agent needs a cited answer instead of a fresh summary.

memory

mindswap_memory

List, add, update, resolve, archive, or delete blockers, assumptions, questions, and resolutions.

Prompts

Reusable prompts for common handoffs.

These make the server useful for actual work instead of just exposing low-level calls.

mindswap_start_work

Prepares a context-rich prompt for kicking off a new session safely.

start

mindswap_resume_work

Creates a restart prompt with the current blockers, state, and next move.

resume

mindswap_prepare_handoff

Builds a compact brief for a new agent so it does not need to re-read the repo.

handoff

mindswap_review_conflicts

Focuses the agent on decision drift and dependency drift before risky edits.

conflict review
Resources

Stable artifacts clients can read directly.

These are the files and resources that stay predictable even as the repo grows.

Resource
Surface
Description
mindswap://context/current
context
Current synthesized project briefing for the active repo and branch.
mindswap://state/current
state
Machine-readable task, branch, checkpoint, and configuration state.
mindswap://decisions/recent
decisions
Recent decisions plus conflict signals for review or rollback.
mindswap://memory/current
memory
Structured blockers, questions, assumptions, and resolutions in JSON form.
mindswap://handoff/current
handoff
The current handoff text or a safe fallback when the generated file is missing.
Connect

How the server connects to clients.

Use local MCP first. Use HTTP only when the client is hosted or browser-based. Keep the package and registry metadata aligned.

transport

Start local. Move to HTTP only when the client needs it.

Most people use the local MCP setup inside an editor or desktop AI app. If the client is hosted or browser-based, mcp-http exposes a Streamable HTTP endpoint with optional bearer auth.

1
Install locally

Run mcp-install so the editor or AI client can see the server in the current project.

2
Use HTTP when needed

Run mcp-http if the client needs a hosted endpoint instead of stdio.

3
Keep metadata aligned

Run registry --json so the public listing matches the package version and server manifest.

local

mcp-install

Generate the local MCP wiring for supported editors and AI clients in the current repo.

registry

registry metadata

Keep server.json aligned with the package metadata so the server stays discoverable.

clients

Who uses it

Claude Code, Cursor, Codex, and any other client that speaks MCP.

FAQ

Answers a new user will actually need.

If someone lands here with only a basic understanding of MCP, these are the first questions they will ask.

What is mindswap?

Mindswap keeps project context inside the repo so the next AI tool can continue from the same task, decisions, and handoff files instead of starting over.

What do I clone first?

Clone the main repo: git clone https://github.com/ShipOrBleed/mindswap.git. Then enter the folder and run npx mindswap init.

What is the first command I should run?

If you are setting up a repo, run npx mindswap init. If you already set up the repo and only want to save state, run npx mindswap.

Do I need MCP for every use case?

No. Use the CLI when you work directly in the repo. Use MCP when an AI client should read and write repo context on its own.

How do I connect an AI client?

Run npx mindswap mcp-install for local editor setup. Use npx mindswap mcp-http only if the client is hosted or browser-based.

Is this open source?

Yes. Star the repo if it helps, and open a contribution if you want to improve the CLI, MCP server, docs, or UI.

Use it. Star it. Contribute if it helps.

This is open source. If mindswap saves time in your workflow, star the repo, try the CLI or MCP guide, and contribute back if you want to extend the server or the UI.

Overview Star on GitHub