npm package: @nbrem108/cai-mcp-server
Description: Official Jira issue writing prompt context and tools for Cursor (Command Alkon). No Jira API—copy-paste only.
Latest version: 0.1.1

# Command Alkon Teams MCP Server

**One place, official prompt context for writing Jira issues.** This MCP does not call any Jira APIs. It gives Cursor (and your team) a single source of truth: tools that return structured, copy-pasteable drafts and a prompt that encodes your standard description template, domain vocabulary, and quality rules.

Use it so everyone writes Jira issues the same way — consistent format, shared vocabulary, no guesswork.

## What it provides

- **Prompt: `jira_issue_guidelines`** – Official Jira issue writing guidelines (description template, App Areas, entities, label patterns, quality rules). Use this so the model follows your standards when writing or reviewing issues.
- **jira_issue_draft** – Draft Story, Task, Spike, or Bug from a short request
- **spike_plan** – Time-boxed spike plan with tasks, deliverables, and risks
- **jira_bug_from_report** – Turn messy bug reports into structured Jira bugs
- **acceptance_criteria** – Generate acceptance criteria and test notes for stories
- **release_notes** – Produce release notes from a list of issues

All output is for copy-paste into Jira. No API keys or Jira integration required.

## Install

**Option A: Run via npx (no install)**

If the package is published to npm, use:

```bash
npx @nbrem108/cai-mcp-server
```

Then in Cursor MCP config, point to this command (see below).

**Option B: Clone and build**

```bash
git clone <repo-url>
cd cai-mcp-server
npm install
npm run build
```

Then run with `npm start` or `node dist/index.js`, and point Cursor at `dist/index.js`.

## Environment variables

Optional. Copy `.env.example` to `.env` if you want to override defaults:

| Variable | Description | Default |
|----------|-------------|---------|
| `JIRA_DEFAULT_PROJECT_KEY` | Default project key used in drafts when none is provided | `PROJ` |

No Jira API keys or secrets are used. The MCP is prompt context and structured output only.

## Register MCP in Cursor

1. Open Cursor Settings → MCP (or edit your MCP config file).
2. Add the server using either **npx** (if the package is on npm) or a **path** to your build:

**Using npx:**

```json
{
  "mcpServers": {
    "command-alkon": {
      "command": "npx",
      "args": ["-y", "@nbrem108/cai-mcp-server"]
    }
  }
}
```

**Using a local path (Windows):**

```json
{
  "mcpServers": {
    "command-alkon": {
      "command": "node",
      "args": ["C:\\Users\\<you>\\cai-mcp-server\\dist\\index.js"]
    }
  }
}
```

**Using a local path (macOS/Linux):**

```json
{
  "mcpServers": {
    "command-alkon": {
      "command": "node",
      "args": ["/path/to/cai-mcp-server/dist/index.js"]
    }
  }
}
```

3. Restart Cursor if needed. The **prompt** (`jira_issue_guidelines`) and **tools** will appear.

## Cursor skill (how the agent uses this MCP)

This repo includes a **Cursor Agent Skill** so the agent knows when and how to use the Jira MCP:

- **Location:** `.cursor/skills/jira-issue-writer/SKILL.md`
- **When it applies:** Creating or formatting Jira stories, bugs, tasks, spikes; acceptance criteria; bug-from-report; release notes; or when the user asks how issues “should” be written.
- **What it does:** Tells the agent to load the `jira_issue_guidelines` prompt first, then call the appropriate tool and present copy-pasteable output.

If you cloned the repo, the skill is already in the project. For team-wide use, ensure the MCP is configured in Cursor and the agent will follow the skill when users ask for Jira content.

## Testing

### 1. Smoke test (no Cursor)

After `npm run build`, run the tool handlers with minimal input to confirm they return valid JSON:

```bash
npm test
```

This runs `scripts/smoke-test-tools.mjs`, which calls each of the five tools once and checks that the response has parseable JSON. Use this to verify the server build and tool logic.

### 2. Run the server and keep it alive

```bash
npm run build
npm start
```

The process will sit on stdio waiting for MCP messages. Do not type into the terminal; that would send input to the server. Stop with Ctrl+C.

### 3. Test inside Cursor (full flow)

1. Add the MCP server to Cursor (see “Register MCP in Cursor” above) and restart if needed.
2. In a chat, ask the model to use a tool, for example:
   - “Use the jira_issue_draft tool to create a Story with context: allow dispatchers to filter loads by carrier.”
   - “Call spike_plan with goal: evaluate OAuth providers, timebox 2 days.”
3. Confirm the model calls the tool and you get back structured JSON (summary, descriptionMarkdown, etc.).

If the tools don’t appear, check Cursor’s MCP settings and that the `args` path points to your built `dist/index.js`.

## Example prompts (for Cursor)

- **Load official guidelines:** Use the **jira_issue_guidelines** prompt so the model has the standard template and vocabulary, then ask it to write an issue.
- **Create a Jira story:** “Create a Jira story for: allow dispatchers to filter loads by carrier.”
- **Spike plan:** “Make a spike plan for evaluating OAuth providers, timebox 2 days.”
- **Bug from report:** “Convert this bug report into a Jira bug: [paste text]”
- **Acceptance criteria:** “Generate acceptance criteria for this story: [paste summary and description]”
- **Release notes:** “Write release notes for these issues: [paste list] with audience Customer, tone Neutral, group by Type.”

## Project structure

```
bin/
  cai-mcp.mjs       # Runnable entrypoint for npx
src/
  index.ts          # Entry point
  server.ts         # MCP server and tool registration
  config/           # Defaults and vocab
  tools/            # Tool handlers
  prompts/          # Template helpers + guidelines
  formatters/       # Jira markdown
  policies/         # Guardrails
.cursor/skills/
  jira-issue-writer/SKILL.md   # Cursor skill for when to use this MCP
server.json         # MCP Registry metadata (optional publish)
```

## Publishing

See **[PUBLISHING.md](PUBLISHING.md)** for step-by-step instructions to publish to npm and (optionally) the MCP Registry.

## Design

- **No Jira API** – This MCP never calls Jira. It is prompt context and structured drafts only; users copy-paste into Jira themselves.
- **Single source of truth** – The `jira_issue_guidelines` prompt and tools define how your team writes issues (template, vocabulary, guardrails).
- **Open questions** – When info is missing (e.g. project key, expected vs actual for bugs), the tools add open questions instead of guessing.

## License

MIT