# opencode-session-context-mcp
osc-mcp



## Demo

https://github.com/user-attachments/assets/d41fb2b8-96ca-4a03-9bcd-afede68212e2

## Dictionary

- [Description](#description)
- [How It Works](#how-it-works)
- [Tools](#tools)
- [Requirements](#requirements)
- [Install](#install)
- [Run](#run)
- [Tips](#tips)
- [Environment](#environment)
- [OS Notes](#os-notes)

## Description
`opencode-session-context-mcp` (aka osc-mcp) is an MCP server that supplies new sessions
with context from prior sessions in the same project, so your OpenCode instance can pick
up where you left off and better align with your project’s ongoing needs.

⚠️ Caution: this tool is under active development, especially around optimizing token spend when fetching context. Contributions are welcome.

## How It Works

- On session start, the server stores a filtered summary of the previous session into `mcp.db`.
- When a new session asks for context, it looks up recent summaries for the current project.
- The client (OpenCode) uses those summaries to seed your new session with relevant context.

## Tools

- `store_previous_session_content`: stores filtered content from the most recent
  previous session into `mcp.db`.
- `get_relevant_sessions`: returns a lightweight list of recent session
  summaries for the current project.

## Requirements

- `bun`
- `git`
- OpenCode (installed and configured)

## Install

### Quick Start (best UX)

Linux/mac

```bash
curl -fsSL https://github.com/vohs-1980/osc-mcp/blob/main/scripts/install.sh?raw=1 | bash
```

Windows (PowerShell):

```powershell
irm https://github.com/vohs-1980/osc-mcp/blob/main/scripts/install.ps1?raw=1 | iex
```

Security note: review `scripts/install.sh` before running or use the manual
steps below. For Windows, review `scripts/install.ps1` before running.

What the installer does (Linux/mac):

- Finds your `opencode.json` (honors `XDG_CONFIG_HOME`).
- Verifies `bun` and `git` are installed.
- Verifies the OpenCode data dir exists (honors `XDG_DATA_HOME`).
- Clones or updates the repo in `~/.local/share/opencode/osc-mcp`.
- Runs `bun install` and builds the server.
- Updates `opencode.json` to add the `"osc-mcp"` MCP entry.
- If config editing fails or `--no-config` is set, prints manual steps.

If your config is invalid JSON or you pass `--no-config`, follow the manual
steps below.

### Manual Install

```bash
git clone https://github.com/vohs-1980/osc-mcp.git \
  ~/.local/share/opencode/osc-mcp
cd ~/.local/share/opencode/osc-mcp
bun install
bun run build
```

OpenCode config (`~/.config/opencode/opencode.json`):

If you don't already have the instruction files listed, add them:

```json
"instructions": [
  "~/.local/share/opencode/osc-mcp/instructions/session-start.md",
  "~/.local/share/opencode/osc-mcp/instructions/context-lookup.md"
]
```

Then add the local MCP entry (if not present):

```json
"osc-mcp": {
  "type": "local",
  "enabled": true,
  "command": ["bun", "~/.local/share/opencode/osc-mcp/src/index.ts"]
}
```




## Run

```bash
# Run the MCP server
bun src/index.ts
```

## Tips

- Start OpenCode from your project root so the MCP can map sessions to the correct project.
- Keep your project in git so sessions can be tied to a stable repo context.

## Environment

- `OPENCODE_DB`: Path to OpenCode DB (default
  `~/.local/share/opencode/opencode.db`)

If the default path doesn’t work for your setup, set it explicitly
before launching OpenCode/MCP.

Example:

```bash
export OPENCODE_DB="$HOME/.local/share/opencode/opencode.db"
opencode
```

Installer overrides (optional):

- `OSC_MCP_REPO_URL`: Git repo URL to clone (default
  `https://github.com/vohs-1980/osc-mcp.git`).
- `OSC_MCP_INSTALL_DIR`: Install directory (default
  `~/.local/share/opencode/osc-mcp`).
- `OSC_MCP_REF`: Git ref to checkout (tag/branch/commit, default `main`).
- `XDG_CONFIG_HOME`: Base config directory (default `~/.config`).
- `XDG_DATA_HOME`: Base data directory (default `~/.local/share`).

Example override:

```bash
export OSC_MCP_REPO_URL="https://github.com/vohs-1980/osc-mcp.git"
export OSC_MCP_INSTALL_DIR="$HOME/.local/share/opencode/osc-mcp"
export OSC_MCP_REF="v0.1.0"
export XDG_CONFIG_HOME="$HOME/.config"
export XDG_DATA_HOME="$HOME/.local/share"
```

## OS Notes

- macOS/Linux: use `scripts/install.sh` (requires `bash`, `git`, `bun`)
- Windows: use `scripts/install.ps1` in PowerShell.

Config path detection (installers search in this order):

macOS/Linux:

1) `$XDG_CONFIG_HOME/opencode/opencode.json`
2) `~/.config/opencode/opencode.json`
3) `~/Library/Application Support/opencode/opencode.json`

Windows:

1) `%XDG_CONFIG_HOME%\opencode\opencode.json`
2) `%APPDATA%\opencode\opencode.json`
3) `%LOCALAPPDATA%\opencode\opencode.json`
4) `~\.config\opencode\opencode.json`
5) `~\Library\Application Support\opencode\opencode.json`

Default data locations (databases):

macOS/Linux:

- `~/.local/share/opencode/opencode.db`
- `~/.local/share/opencode/osc-mcp/mcp.db`

Windows:

- `%USERPROFILE%\.local\share\opencode\opencode.db`
- `%USERPROFILE%\.local\share\opencode\osc-mcp\mcp.db`

## License

MIT. See `LICENSE`.