@nbrem108/cai-mcp-server 0.1.0

package/.env.example

@@ -0,0 +1,4 @@
+# Optional: default project key used in drafts when none is provided
+# JIRA_DEFAULT_PROJECT_KEY=PROJ
+
+# This MCP does not call Jira APIs. It only provides prompt context and structured drafts for copy-paste.

package/README.md

@@ -0,0 +1,177 @@
+# 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

package/bin/cai-mcp.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Runnable entrypoint for npx / global install.
+ * Runs the MCP server over stdio (for Cursor and other MCP clients).
+ */
+import { fileURLToPath } from "node:url";
+import { pathToFileURL } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const distIndex = join(__dirname, "..", "dist", "index.js");
+
+await import(pathToFileURL(distIndex).href);

package/dist/config/defaults.d.ts

@@ -0,0 +1,8 @@
+export interface Vocab {
+    appAreas: string[];
+    entities: string[];
+    labelPatterns: string[];
+    personas: string[];
+}
+export declare function loadVocab(): Vocab;
+export declare function getDefaultProjectKey(): string;

package/dist/config/defaults.js

@@ -0,0 +1,16 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+let _vocab = null;
+export function loadVocab() {
+    if (!_vocab) {
+        const path = join(__dirname, "vocab.json");
+        const raw = readFileSync(path, "utf-8");
+        _vocab = JSON.parse(raw);
+    }
+    return _vocab;
+}
+export function getDefaultProjectKey() {
+    return process.env.JIRA_DEFAULT_PROJECT_KEY ?? "PROJ";
+}

package/dist/config/vocab.json

@@ -0,0 +1,32 @@
+{
+  "appAreas": [
+    "Company Admin",
+    "Dispatch",
+    "Deliveries",
+    "Billing",
+    "Sales & Quoting",
+    "Accounting"
+  ],
+  "entities": [
+    "Customer",
+    "Carrier",
+    "Location",
+    "Legal Entity",
+    "Role",
+    "Permission",
+    "ABAC filter",
+    "Team"
+  ],
+  "labelPatterns": [
+    "app-company-admin",
+    "feature-permissions",
+    "ux",
+    "bug",
+    "spike"
+  ],
+  "personas": [
+    "default",
+    "readyMixSupport",
+    "billingSupport"
+  ]
+}

package/dist/formatters/jiraMarkdown.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Jira-ready markdown formatting utilities.
+ * Uses a consistent description template for copy-paste into Jira.
+ */
+export interface DescriptionSections {
+    overview?: string;
+    userProblem?: string;
+    scope?: string;
+    outOfScope?: string;
+    workflowNotes?: string;
+    permissionsRoles?: string;
+    dataApiNotes?: string;
+    acceptanceCriteria?: string[];
+    testNotes?: string[];
+    openQuestions?: string[];
+}
+/**
+ * Build a standard Jira description with the canonical section order.
+ */
+export declare function buildDescription(sections: DescriptionSections): string;
+/**
+ * Build a bug description with: Problem, Steps to Reproduce, Expected, Actual, Environment, Impact, Notes/Logs.
+ */
+export interface BugDescriptionSections {
+    problem: string;
+    stepsToReproduce?: string;
+    expected?: string;
+    actual?: string;
+    environment?: string;
+    impact?: string;
+    notesLogs?: string;
+}
+export declare function buildBugDescription(sections: BugDescriptionSections): string;
+/**
+ * Escape or normalize text for Jira markdown (e.g. avoid breaking list items).
+ */
+export declare function escapeJiraMarkdown(text: string): string;

package/dist/formatters/jiraMarkdown.js

@@ -0,0 +1,75 @@
+/**
+ * Jira-ready markdown formatting utilities.
+ * Uses a consistent description template for copy-paste into Jira.
+ */
+const H2 = (title) => `\n## ${title}\n`;
+const bullets = (items) => items.length ? items.map((s) => `* ${s}`).join("\n") : "";
+/**
+ * Build a standard Jira description with the canonical section order.
+ */
+export function buildDescription(sections) {
+    const parts = [];
+    if (sections.overview) {
+        parts.push(H2("Overview"), sections.overview);
+    }
+    if (sections.userProblem) {
+        parts.push(H2("User Problem / Value"), sections.userProblem);
+    }
+    if (sections.scope) {
+        parts.push(H2("Scope"), sections.scope);
+    }
+    if (sections.outOfScope) {
+        parts.push(H2("Out of Scope"), sections.outOfScope);
+    }
+    if (sections.workflowNotes) {
+        parts.push(H2("Workflow / UI Notes"), sections.workflowNotes);
+    }
+    if (sections.permissionsRoles) {
+        parts.push(H2("Permissions / Roles"), sections.permissionsRoles);
+    }
+    if (sections.dataApiNotes) {
+        parts.push(H2("Data / API Notes"), sections.dataApiNotes);
+    }
+    if (sections.acceptanceCriteria?.length) {
+        parts.push(H2("Acceptance Criteria"), bullets(sections.acceptanceCriteria));
+    }
+    if (sections.testNotes?.length) {
+        parts.push(H2("Test Notes"), bullets(sections.testNotes));
+    }
+    if (sections.openQuestions?.length) {
+        parts.push(H2("Open Questions"), bullets(sections.openQuestions));
+    }
+    return parts.join("\n").trim() || "";
+}
+export function buildBugDescription(sections) {
+    const parts = [];
+    parts.push(H2("Problem"), sections.problem);
+    if (sections.stepsToReproduce) {
+        parts.push(H2("Steps to Reproduce"), sections.stepsToReproduce);
+    }
+    if (sections.expected) {
+        parts.push(H2("Expected"), sections.expected);
+    }
+    if (sections.actual) {
+        parts.push(H2("Actual"), sections.actual);
+    }
+    if (sections.environment) {
+        parts.push(H2("Environment"), sections.environment);
+    }
+    if (sections.impact) {
+        parts.push(H2("Impact"), sections.impact);
+    }
+    if (sections.notesLogs) {
+        parts.push(H2("Notes / Logs"), sections.notesLogs);
+    }
+    return parts.join("\n").trim();
+}
+/**
+ * Escape or normalize text for Jira markdown (e.g. avoid breaking list items).
+ */
+export function escapeJiraMarkdown(text) {
+    return text
+        .replace(/\r\n/g, "\n")
+        .replace(/\r/g, "\n")
+        .trim();
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Command Alkon Teams MCP Server
+ * Entry point: runs the MCP server over stdio for Cursor.
+ */
+import "./server.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+/**
+ * Command Alkon Teams MCP Server
+ * Entry point: runs the MCP server over stdio for Cursor.
+ */
+import "./server.js";

package/dist/policies/guardrails.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Guardrails: no hallucinated fields, open questions for missing/ambiguous info.
+ */
+import type { Vocab } from "../config/defaults.js";
+/**
+ * Ensure labels only use known patterns or safe defaults; otherwise suggest open question.
+ */
+export declare function validateLabels(labels: string[], vocab: Vocab): {
+    labels: string[];
+    openQuestions: string[];
+};
+/**
+ * If project key is missing or empty, add open question.
+ */
+export declare function ensureProjectKey(projectKey: string | undefined, openQuestions: string[]): string[];
+/**
+ * For bugs: if expected/actual behavior is missing, add open question.
+ */
+export declare function ensureBugExpectedActual(expected: string | undefined, actual: string | undefined, openQuestions: string[]): string[];
+/**
+ * If app area is provided but not in vocab, add open question.
+ */
+export declare function validateAppArea(appArea: string | undefined, vocab: Vocab): string[];
+export declare function capDescription(markdown: string): string;
+/**
+ * Collect all open questions and deduplicate.
+ */
+export declare function mergeOpenQuestions(...questionLists: string[][]): string[];
+/**
+ * Get vocab for use in tools (prefer vocab terms, fall back to open questions).
+ */
+export declare function getVocab(): Vocab;

package/dist/policies/guardrails.js

@@ -0,0 +1,88 @@
+import { loadVocab } from "../config/defaults.js";
+/**
+ * Ensure labels only use known patterns or safe defaults; otherwise suggest open question.
+ */
+export function validateLabels(labels, vocab) {
+    const known = new Set(vocab.labelPatterns);
+    const valid = [];
+    const questions = [];
+    for (const l of labels) {
+        const normalized = l.toLowerCase().replace(/\s+/g, "-");
+        if (known.has(normalized) || normalized === "bug" || normalized === "spike") {
+            valid.push(l);
+        }
+        else {
+            valid.push(l);
+            if (!questions.includes("Confirm label usage for: " + l)) {
+                questions.push("Confirm label usage for: " + l);
+            }
+        }
+    }
+    return { labels: valid, openQuestions: questions };
+}
+/**
+ * If project key is missing or empty, add open question.
+ */
+export function ensureProjectKey(projectKey, openQuestions) {
+    if (!projectKey || projectKey.trim() === "") {
+        return [...openQuestions, "Which Jira project key should this issue use?"];
+    }
+    return openQuestions;
+}
+/**
+ * For bugs: if expected/actual behavior is missing, add open question.
+ */
+export function ensureBugExpectedActual(expected, actual, openQuestions) {
+    const out = [...openQuestions];
+    if (!expected?.trim()) {
+        out.push("What was the expected behavior?");
+    }
+    if (!actual?.trim()) {
+        out.push("What was the actual behavior?");
+    }
+    return out;
+}
+/**
+ * If app area is provided but not in vocab, add open question.
+ */
+export function validateAppArea(appArea, vocab) {
+    if (!appArea?.trim())
+        return [];
+    const known = new Set(vocab.appAreas.map((a) => a.toLowerCase()));
+    if (known.has(appArea.toLowerCase()))
+        return [];
+    return ["Is the app area correct? Known areas: " + vocab.appAreas.join(", ")];
+}
+/**
+ * Cap description length for "ready to paste" (avoid massive blocks).
+ */
+const MAX_DESCRIPTION_LENGTH = 32000;
+export function capDescription(markdown) {
+    if (markdown.length <= MAX_DESCRIPTION_LENGTH)
+        return markdown;
+    return (markdown.slice(0, MAX_DESCRIPTION_LENGTH) +
+        "\n\n... (truncated for length; consider splitting into child issues)");
+}
+/**
+ * Collect all open questions and deduplicate.
+ */
+export function mergeOpenQuestions(...questionLists) {
+    const seen = new Set();
+    const out = [];
+    for (const list of questionLists) {
+        for (const q of list) {
+            const t = q.trim();
+            if (t && !seen.has(t)) {
+                seen.add(t);
+                out.push(q);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Get vocab for use in tools (prefer vocab terms, fall back to open questions).
+ */
+export function getVocab() {
+    return loadVocab();
+}

package/dist/prompts/guidelines.d.ts

@@ -0,0 +1,10 @@
+export declare function getJiraIssueGuidelines(): {
+    description?: string;
+    messages: Array<{
+        role: "user" | "assistant";
+        content: {
+            type: "text";
+            text: string;
+        };
+    }>;
+};

package/dist/prompts/guidelines.js

@@ -0,0 +1,52 @@
+/**
+ * Official Jira issue writing guidelines — single source of truth for prompt context.
+ * Exposed as MCP prompt "jira_issue_guidelines" so the model can use it when writing issues.
+ */
+import { loadVocab } from "../config/defaults.js";
+export function getJiraIssueGuidelines() {
+    const vocab = loadVocab();
+    const text = `You are following Command Alkon's official Jira issue writing standards. Use this as the single source of truth whenever you write or review Jira issues.
+
+## Standard description template
+
+Use this section order for issue descriptions (markdown). Prefer structured bullets over long paragraphs.
+
+1. **Overview** – What this is and why it matters.
+2. **User Problem / Value** – Who is affected and what value they get.
+3. **Scope** – What is in scope.
+4. **Out of Scope** – What is explicitly not in scope.
+5. **Workflow / UI Notes** – How it should behave in the product.
+6. **Permissions / Roles** – If applicable (roles, permissions, ABAC).
+7. **Data / API Notes** – If applicable (APIs, data model).
+8. **Acceptance Criteria** – Bullet list of testable criteria.
+9. **Test Notes** – Manual test checklist.
+10. **Open Questions** – Unresolved questions; do not guess — list them.
+
+Consistency is more important than being verbose.
+
+## Domain vocabulary (Command Alkon / Command Cloud)
+
+**App areas:** ${vocab.appAreas.join(", ")}
+
+**Entities:** ${vocab.entities.join(", ")}
+
+**Label patterns:** Prefer these when relevant: ${vocab.labelPatterns.join(", ")}. Do not invent custom field IDs or project-specific fields unless the user provides them.
+
+**Personas:** ${vocab.personas.join(", ")}
+
+## Quality rules
+
+- Never hallucinate Jira custom fields (e.g. story points field IDs) unless the user or config provides them.
+- When information is missing (e.g. project key, expected vs actual for bugs, permissions scope), add **Open Questions** instead of guessing.
+- Output must be copy-pasteable into Jira (clear headings, bullets, no broken markdown).
+- For bugs, always include: Problem, Steps to Reproduce, Expected, Actual, Environment, Impact (and Notes/Logs if applicable).`;
+    return {
+        description: "Official Jira issue writing guidelines (template, vocabulary, quality rules)",
+        messages: [
+            {
+                role: "user",
+                content: { type: "text", text },
+            },
+        ],
+    };
+}

package/dist/prompts/templates.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Deterministic prompt/template helpers for tool output structure.
+ * Tools use these to build consistent, copy-pasteable content.
+ */
+import type { JiraIssueDraftInput, JiraIssueDraftOutput } from "../types/index.js";
+import type { JiraBugFromReportInput, JiraBugFromReportOutput } from "../types/index.js";
+import type { SpikePlanInput, SpikePlanOutput } from "../types/index.js";
+import type { AcceptanceCriteriaInput, AcceptanceCriteriaOutput } from "../types/index.js";
+import type { ReleaseNotesInput, ReleaseNotesOutput } from "../types/index.js";
+export declare function applyJiraIssueDraftTemplate(input: JiraIssueDraftInput): JiraIssueDraftOutput;
+export declare function applySpikePlanTemplate(input: SpikePlanInput): SpikePlanOutput;
+export declare function applyJiraBugFromReportTemplate(input: JiraBugFromReportInput): JiraBugFromReportOutput;
+export declare function applyAcceptanceCriteriaTemplate(input: AcceptanceCriteriaInput): AcceptanceCriteriaOutput;
+export declare function applyReleaseNotesTemplate(input: ReleaseNotesInput): ReleaseNotesOutput;