Ascona AI Documentation — User Guide, CLI & MCP Protocol Reference

🚀 Overview & Capabilities

Ascona AI is the enterprise autonomous Jira copilot designed to bridge product strategy, architectural decomposition, and agile sprint delivery. It automates the transition from raw Product Requirement Documents (PRDs) into fully estimated Jira Epics, testable Given-When-Then Gherkin stories, and calibrated story points.

Key Tenet: Ascona operates on a zero-data retention model. Your proprietary codebases, PRDs, and Jira issue histories are never stored, logged, or used to fine-tune foundation models.

Core Integration Surfaces

Web Application & Dashboard: Real-time spec decomposition, visual sprint review, and one-click Jira Cloud synchronization.
Terminal CLI (@ascona/cli): Automated git hook and CI/CD pipelines to validate specs and groom backlogs on PR creation.
Model Context Protocol (MCP) Server: Native integration with Cursor, Claude Desktop, Antigravity, and autonomous agent loops.
REST API Gateway: High-throughput programmatic endpoints for custom enterprise orchestration.

Ascona AI vs. GitHub Projects & Issues

Many engineering teams ask: "We already use GitHub Projects (tables, boards, task lists) and GitHub Issues—why do we need Ascona?"

The fundamental difference is Passive Tracking vs. Autonomous Synthesis:

GitHub Projects is a tracking container: It provides blank tables, kanban boards, and markdown text fields. But it requires human product managers and engineering leads to spend 15+ hours weekly manually reading PRDs, typing issue titles, creating sub-issues one by one, writing descriptions, and debating story points.
Ascona AI is the generative upstream engine: You feed Ascona a raw PRD, Notion spec, or RFC, and in 30 seconds it identifies architectural domain boundaries, generates structured Jira Epics, writes persona-based User Stories ("As a [Persona], I want [Feature], so that [Value]"), drafts testable Given-When-Then Gherkin criteria, calibrates Fibonacci complexity, and generates a 16-field Agile Sprint Matrix.
Seamless Bi-Directional Export: Once synthesized, Ascona can push completed tickets directly into Atlassian Jira Cloud, Jira Data Center, or auto-populate GitHub Issues & GitHub Projects boards via our CLI and MCP tools.

💻 Ascona Terminal CLI (`ascona`)

The Ascona CLI provides full headless functionality for engineering squads who work directly in their terminal, Neovim/VSCode, and GitHub Actions workflows.

Installation

# Install globally via npm
npm install -g @ascona/cli

# Verify installation
ascona --version
# Output: ascona-cli/2.4.1 darwin-arm64 node-v18.18.2

Initial Configuration & Authentication

Authenticate with your Ascona Cloud organization and connect your Atlassian Jira workspace:

# Authenticate via browser SSO
ascona auth login

# Set default target Jira Cloud workspace & project key
ascona config set jira.domain "your-company.atlassian.net"
ascona config set jira.project "ENG"
ascona config set estimation.scale "fibonacci"

CLI Command Reference

Command	Arguments	Description
`ascona parse <file>`	`--sync-jira`, `--dry-run`	Parses markdown or PDF PRD and prints decomposed Epics & Stories.
`ascona estimate <key>`	`--history <sprints>`	Calibrates Fibonacci story points based on commit history & API complexity.
`ascona gherkin <key>`	`--format <cucumber\|playwright>`	Generates executable Given-When-Then test cases for an existing Jira ticket.
`ascona sync`	`--board <id>`, `--sprint <id>`	Executes 2-way sync between local specification files and Jira boards.
`ascona export-github <file>`	`--repo <org/repo>`, `--create-issues`	Pushes decomposed Epics, Stories, and Gherkin AC directly into GitHub Issues & Projects.

Example: CI/CD GitHub Actions Pipeline

# .github/workflows/ascona-prd-check.yml
name: Ascona Spec Decomposition & Backlog Check
on:
  pull_request:
    paths:
      - 'specs/**.md'

jobs:
  validate-and-plan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Run Ascona Decomposition
        env:
          ASCONA_API_KEY: ${{ secrets.ASCONA_API_KEY }}
        run: |
          npx @ascona/cli parse ./specs/checkout-v2.md --sync-jira --project PAY

🔌 Model Context Protocol (MCP) Server

Ascona implements the official Model Context Protocol (MCP) specification, enabling AI coding assistants (like Cursor, Claude Desktop, Antigravity, and Claude Code) to interact directly with Jira backlogs without leaving the IDE.

Configuration in Cursor & Claude Desktop

Add the Ascona MCP server to your claude_desktop_config.json or .cursor/mcp.json:

{
  "mcpServers": {
    "ascona": {
      "command": "npx",
      "args": ["-y", "@ascona/mcp-server"],
      "env": {
        "ASCONA_API_KEY": "asc_live_9a8f27b84c1...",
        "JIRA_INSTANCE": "company.atlassian.net",
        "JIRA_PROJECT": "ENG"
      }
    }
  }
}

Available MCP Tool Signatures

1. `ascona_decompose_prd`

Takes raw specification text and decomposes it into an Epic, child Stories, Gherkin acceptance criteria, and calibrated story points.

// Tool Input Schema:
{
  "name": "ascona_decompose_prd",
  "description": "Decomposes a product specification into structured Jira Epics, Stories, and Gherkin scenarios",
  "parameters": {
    "type": "object",
    "properties": {
      "specificationText": {
        "type": "string",
        "description": "Full text or markdown of the feature requirement"
      },
      "projectKey": {
        "type": "string",
        "description": "Target Jira project key (e.g. 'ENG')"
      },
      "includeGherkin": {
        "type": "boolean",
        "default": true
      }
    },
    "required": ["specificationText", "projectKey"]
  }
}

2. `ascona_sync_jira`

Transmits decomposed issues to Atlassian Jira Cloud via authenticated REST endpoints.

// Tool Input Schema:
{
  "name": "ascona_sync_jira",
  "description": "Synchronizes decomposed backlog items directly into Jira Cloud / Data Center",
  "parameters": {
    "type": "object",
    "properties": {
      "epic": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "description": { "type": "string" }
        },
        "required": ["title"]
      },
      "stories": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "title": { "type": "string" },
            "storyPoints": { "type": "integer" },
            "gherkinCriteria": { "type": "string" },
            "issueType": { "type": "string", "default": "Story" }
          },
          "required": ["title", "storyPoints", "gherkinCriteria"]
        }
      }
    },
    "required": ["epic", "stories"]
  }
}

3. `ascona_calibrate_points`

Computes risk-weighted Fibonacci story points based on code complexity factors, database migrations, and 3rd-party API dependencies.

// Tool Input Schema:
{
  "name": "ascona_calibrate_points",
  "parameters": {
    "type": "object",
    "properties": {
      "taskSummary": { "type": "string" },
      "architecturalDomains": { "type": "array", "items": { "type": "string" } },
      "involvesDbMigration": { "type": "boolean" },
      "externalApiDependencies": { "type": "integer" }
    },
    "required": ["taskSummary"]
  }
}

⚡ REST API Signatures

Base URL: https://api.ascona.ai/v1

All requests must include the header: Authorization: Bearer <ASCONA_API_KEY>

POST /v1/decompose

Ingests raw specification text and returns structured Agile entities.

// REQUEST:
POST /v1/decompose HTTP/1.1
Host: api.ascona.ai
Authorization: Bearer asc_live_9a8f27b84c1...
Content-Type: application/json

{
  "spec": "Build an OAuth 2.0 PKCE flow with Redis token session caching and automated refresh token rotation.",
  "targetProject": "AUTH",
  "estimationStrategy": "bayesian_velocity"
}

// RESPONSE (200 OK):
{
  "epic": {
    "key": "AUTH-EPIC-12",
    "summary": "PKCE OAuth 2.0 Engine & Redis Session Cache",
    "description": "Decomposition of authorization server, token rotation, and storage."
  },
  "stories": [
    {
      "key": "AUTH-101",
      "summary": "Implement Authorization Code Grant with PKCE verification",
      "storyPoints": 5,
      "gherkin": "Scenario: Code verifier challenge mismatch\nGiven an authorization request with code_challenge\nWhen token exchange is requested with invalid code_verifier\nThen reject request with HTTP 400 invalid_grant"
    },
    {
      "key": "AUTH-102",
      "summary": "Redis Token Session Invalidation Pipeline",
      "storyPoints": 3,
      "gherkin": "Scenario: Refresh token reuse detection\nGiven an already consumed refresh token\nWhen presented to /oauth/token endpoint\nThen revoke all active sessions for user family and emit security alert"
    }
  ],
  "latencyMs": 420
}

POST /v1/jira/sync

Commits issues directly into Jira Cloud via Atlassian REST APIs.

// REQUEST:
POST /v1/jira/sync HTTP/1.1
Host: api.ascona.ai
Authorization: Bearer asc_live_9a8f27b84c1...
Content-Type: application/json

{
  "projectKey": "AUTH",
  "epicKey": "AUTH-EPIC-12",
  "issueKeys": ["AUTH-101", "AUTH-102"]
}

// RESPONSE (201 Created):
{
  "status": "SUCCESS",
  "createdIssues": [
    { "key": "AUTH-101", "id": "10482", "url": "https://org.atlassian.net/browse/AUTH-101" },
    { "key": "AUTH-102", "id": "10483", "url": "https://org.atlassian.net/browse/AUTH-102" }
  ],
  "durationMs": 840
}

🛡️ Enterprise Security & Data Governance

Ascona AI is built from the ground up for strict regulatory environments including Fintech, Healthcare, and enterprise SaaS.

Zero Data Retention (ZDR): Specs and prompts are held in ephemeral memory only for the duration of the inference call.
No Model Training: Customer data is never stored, retained, or utilized to train LLMs.
Encryption Standards: Data in transit is protected via TLS 1.3 with forward secrecy. Data at rest is encrypted with AES-256.
Role-Based Access Control: Fine-grained permission mapping adhering to organization SSO policies (Okta, Azure AD, Google Workspace).

🚀 Overview & Capabilities

Core Integration Surfaces

Ascona AI vs. GitHub Projects & Issues

💻 Ascona Terminal CLI (ascona)

Installation

Initial Configuration & Authentication

CLI Command Reference

Example: CI/CD GitHub Actions Pipeline

🔌 Model Context Protocol (MCP) Server

Configuration in Cursor & Claude Desktop

Available MCP Tool Signatures

1. ascona_decompose_prd

2. ascona_sync_jira

3. ascona_calibrate_points

⚡ REST API Signatures

POST /v1/decompose

POST /v1/jira/sync

🛡️ Enterprise Security & Data Governance

💻 Ascona Terminal CLI (`ascona`)

1. `ascona_decompose_prd`

2. `ascona_sync_jira`

3. `ascona_calibrate_points`