# Stash MCP

Professional MCP (Model Context Protocol) server for Bitbucket Server/Data Center (formerly Stash). It provides high-signal tools for project discovery, repository browsing, pull request workflows, and code search.

![CI](https://github.com/schwarztim/stash-mcp/actions/workflows/ci.yml/badge.svg)
![License](https://img.shields.io/github/license/schwarztim/stash-mcp)

## Features

- Project and repository discovery
- Pull request lifecycle management (create, review, merge, decline)
- Commenting and inline review notes
- Diff viewing with safe truncation for large files
- Code search (when enabled on the server)
- Read-only mode to prevent write operations

## Requirements

- Node.js 18+
- Bitbucket Server/Data Center (Stash) REST API access

## Install

```bash
npm install
npm run build
```

Or use the helper script:

```bash
./scripts/install.sh
```

## Configuration

Add to `~/.claude/user-mcps.json`:

```json
{
  "mcpServers": {
    "stash": {
      "command": "node",
      "args": ["/absolute/path/to/stash-mcp/dist/index.js"],
      "env": {
        "BITBUCKET_URL": "https://stash.example.com",
        "BITBUCKET_TOKEN": "your-access-token",
        "BITBUCKET_DEFAULT_PROJECT": "PROJ"
      }
    }
  }
}
```

### Environment Variables

- `BITBUCKET_URL` (required): Base URL of your Bitbucket Server instance.
- `BITBUCKET_TOKEN`: Personal access token (recommended).
- `BITBUCKET_USERNAME` / `BITBUCKET_PASSWORD`: Basic auth alternative.
- `BITBUCKET_DEFAULT_PROJECT`: Default project key when `project` is omitted.
- `BITBUCKET_DIFF_MAX_LINES_PER_FILE`: Diff truncation limit per file.
- `BITBUCKET_READ_ONLY`: Set to `true` to disable write operations.

## Dependencies

- **[Hermes](https://github.com/schwarztim/hermes)** — Authentication broker. Manages OAuth2/SSO token acquisition, refresh, and serving for this MCP server.
- **[ToolHive](https://github.com/stacklok/toolhive)** — Container runtime. Hosts this server as a Docker container with streamable HTTP transport.
- **[MCP Gateway](http://127.0.0.1:3100/mcp)** — Aggregation layer. Provides unified tool access across all MCP backends.
- **[node-vault-mcp](~/Projects/node-vault-mcp)** — Credential storage. AES-256-GCM encrypted file vault (replaces macOS Keychain/keytar).

## Architecture

This MCP server runs as a Docker container managed by ToolHive:

1. **Container** — Built from the local Dockerfile and published as `localhost:5555/stash-mcp:latest`
2. **Transport** — Streamable HTTP via the ToolHive proxy
3. **Authentication** — Managed by Hermes (`http://127.0.0.1:9876`)
4. **Discovery** — Exposed through MCP Gateway at `http://127.0.0.1:3100/mcp`
5. **Credentials** — Stored in `~/.claude/secrets.vault` via node-vault-mcp (AES-256-GCM)

## Usage

### List projects

```
list_projects:
  limit: 25
```

### List repositories

```
list_repositories:
  project: PROJ
```

### Review a pull request

```
get_pull_request:
  project: PROJ
  repository: my-repo
  prId: 123
```

### Search for a file

```
search:
  query: README.md
  type: file
  project: PROJ
```

## Read-Only Mode

Set `BITBUCKET_READ_ONLY=true` to block write operations. Read-only mode allows safe browsing and review without modifying repositories.

## Development

```bash
npm run build
npm test
npm run lint
```

## Security

Please report security issues privately. See `SECURITY.md` for guidance.

## License

MIT. See `LICENSE`.