# Suporta MCP Server

Connect [Claude Code](https://claude.ai/claude-code) to your Suporta helpdesk — manage tickets, search, and post replies directly from your editor.

Works with **any project** (Laravel, Vue, React, Node, etc.).

---

## Quick Setup (2 minutes)

### 1. Generate an API Token

1. Open your Suporta instance (e.g. `https://bitpeak.suportahub.com`)
2. Go to **Settings → API Tokens**
3. Click **Generate New Token**
4. Enter a name (e.g. `Claude MCP`)
5. Select the projects you want Claude to access
6. Click **Generate** and **copy the token immediately** — it's shown only once

### 2. Add to your project

Create `.mcp.json` in your project root:

```json
{
	"mcpServers": {
		"suporta": {
			"command": "npx",
			"args": ["-y", "suporta-mcp-server"],
			"env": {
				"SUPORTA_URL": "https://your-tenant.suportahub.com",
				"SUPORTA_TOKEN": "your-api-token-here"
			}
		}
	}
}
```

### 3. Restart Claude Code

After saving `.mcp.json`, restart Claude Code (or run `/mcp` to reload servers). Verify with:

> "who am I on Suporta?"

Claude should respond with your name and role. That's it — you're connected.

---

## Available Tools

| Tool                | Description                               | Example prompt                                            |
| ------------------- | ----------------------------------------- | --------------------------------------------------------- |
| `who-am-i`          | Verify your connection                    | _"who am I on Suporta?"_                                  |
| `list-projects`     | List all accessible projects              | _"show my projects"_                                      |
| `get-ticket`        | Fetch ticket details by slug or URL       | _"get ticket 1035-bug-ticket"_ or paste the ticket URL    |
| `list-my-tickets`   | List your assigned tickets                | _"show my open tickets"_                                  |
| `search-tickets`    | Search by keyword                         | _"search for tickets about login"_                        |
| `create-ticket`     | Create a new ticket                       | _"create a P1 ticket in project bitpeak about login bug"_ |
| `update-ticket`     | Update status, priority, assignees, etc.  | _"set ticket 1035-bug-ticket to Closed"_                  |
| `post-ticket-reply` | Post a reply (internal or client-visible) | _"post an internal note on ticket 1035-bug-ticket"_       |
| `link-branch`       | Attach a git branch to a ticket           | _"link branch fix/icons to ticket 1484"_                  |
| `unlink-branch`     | Remove a repository's branch              | _"unlink the bitpeak-v3 branch from ticket 1484"_         |
| `link-pull-request` | Attach a pull request to a ticket         | _"link this PR to ticket 1484"_                           |
| `unlink-pull-request` | Remove a pull request                   | _"unlink that PR from ticket 1484"_                       |
| `get-current-sprint` | Current sprint, optionally with its tickets | _"what's in the current sprint?"_                      |
| `list-sprints`      | List sprints with IDs and dates           | _"show all sprints"_                                      |
| `create-sprint`     | Create a sprint                           | _"create sprint 42 from 2026-10-01 to 2026-10-14"_        |
| `log-time`          | Log hours on a project or ticket          | _"log 2 hours on project bitpeak: API review"_            |
| `list-users`        | List users with IDs, emails and roles     | _"list all admins"_                                       |
| `get-project` / `create-project` / `update-project` / `delete-project` | Project CRUD (delete = archive) | _"create project Website for company 3"_ |
| `list-companies` / `get-company` / `create-company` / `update-company` / `delete-company` | Company CRUD (delete is permanent) | _"add company Acme B.V. in Utrecht"_ |

All tools act with the permissions of the user who created the API token.

---

## Usage Examples

**Fetch a ticket from URL:**

> Paste `https://bitpeak.suportahub.com/ticket/1035-bug-ticket` and Claude will extract the slug and fetch details.

**Filter your tickets:**

> _"show my overdue tickets"_
> _"list my open tickets due this week"_

**Create a ticket:**

> _"create a ticket in project bitpeak: Login page returns 500 on invalid email"_

**Update a ticket:**

> _"set ticket 1035-bug-ticket priority to P1 and assign to user 14"_
> _"close ticket 1035-bug-ticket"_

**Implement a ticket:**

> _"fetch ticket 1035-bug-ticket and implement it"_
>
> Claude will read the ticket, analyze the codebase, create a branch, implement the changes, and post a summary back on the ticket.

**Post an internal note:**

> _"post an internal note on ticket 1035-bug-ticket saying the fix is deployed"_

**Link a branch and a pull request:**

> _"link branch fix/icon-font-flash to ticket 1484"_
> _"link https://bitbucket.org/bitpeak_code/bitpeak-v3/pull-requests/11 to ticket 1484"_

These fill the same sidebar blocks the web app shows, and they satisfy the
board lanes that gate on a branch or a pull request.

Three things worth knowing:

- **They add, they do not replace.** The underlying API takes the complete
  list, so linking one pull request would normally unlink the rest. These tools
  read the current list first and merge, keeping what is there. Pass
  `replace_all: true` when you really do want only the new one.
- **A repository holds one branch.** Linking a second branch for the same
  repository replaces the first, and the result says which name it displaced.
- **`repository_slug` is optional** when the project maps exactly one Bitbucket
  repository, which is the usual case. When it maps several, the error lists
  them.

Both are staff-only (`role:admin|support`), matching the web sidebar, which has
always hidden branches and pull requests from clients.

---

## Multiple Projects / Tenants

Each project gets its own `.mcp.json` with its own token and URL. This means:

- **Project A** → connects to `https://clienta.suportahub.com` with token scoped to Project A's projects
- **Project B** → connects to `https://clientb.suportahub.com` with a different token

Tokens are scoped to specific projects at generation time, so each developer only sees what they need.

---

## Troubleshooting

**"Not connected" error**

- Check that `SUPORTA_URL` and `SUPORTA_TOKEN` are set in `.mcp.json`
- Make sure the token hasn't been deleted in Settings → API Tokens
- Restart Claude Code after changing `.mcp.json`

**"API 401" error**

- Your token is invalid or expired. Generate a new one in Settings → API Tokens

**Tools not showing up**

- Run `/mcp` in Claude Code to check server status
- Verify `node` is available in your PATH
- Make sure you have Node.js 18+ installed

---

## CI/CD: Auto-publish to npm on main

This repo includes GitHub Actions workflow [publish-npm.yml](.github/workflows/publish-npm.yml) that runs on every push to `main`.

What it does:

- Installs dependencies
- Bumps patch version automatically
- Commits the version bump back to `main`
- Publishes the new version to npm

### Required GitHub secret

Add this repository secret in GitHub:

- Name: `NPM_TOKEN`
- Value: your npm access token (Automation or Publish token)

GitHub path:
`Settings -> Secrets and variables -> Actions -> New repository secret`