kiket-mcp-server by kiket-dev - MCP Server

Kiket MCP Server

Model Context Protocol (MCP) server that provides AI tools to interact with Kiket issues, comments, projects, and users. Enables Claude, GitHub Copilot, OpenAI Codex, Gemini, and other AI assistants to manage Kiket programmatically.

Features

16 MCP Prompts for guided workflows:
- Issue Management: create-issue, create-bug-report, create-feature, update-issue, bulk-update-issues, close-issue, delete-issue
- Milestone Management: create-milestone, plan-sprint, update-milestone, close-milestone, delete-milestone
- Analysis & Reporting: daily-standup, release-notes, backlog-review, project-overview
22 MCP Tools for comprehensive Kiket management:
- Issues (6 tools):
  - listIssues - List issues with filters
  - getIssue - Fetch single issue
  - createIssue - Create new issue
  - updateIssue - Update issue fields
  - transitionIssue - Move issue through workflow
  - getIssueSchema - Get available issue types, priorities, statuses
- Comments (4 tools):
  - listComments - List comments on issue
  - createComment - Add comment to issue
  - updateComment - Update existing comment
  - deleteComment - Delete comment
- Projects (5 tools):
  - listProjects - List all visible projects
  - getProject - Fetch single project
  - createProject - Create new project
  - updateProject - Update project settings
  - deleteProject - Archive/delete project
- Milestones (5 tools):
  - listMilestones - List milestones for a project
  - getMilestone - Get milestone details
  - createMilestone - Create new milestone/sprint
  - updateMilestone - Update milestone settings
  - deleteMilestone - Delete milestone
- Users (3 tools):
  - listUsers - List project members
  - getUser - Fetch user details
  - getCurrentUser - Get authenticated user
Dual Transport Support: WebSocket (Claude Desktop) and stdio (Codex, Copilot, Gemini)
Robust Error Handling: Detailed JSON-RPC error codes with helpful messages
Production Ready:
- Structured Logging: Winston-based logging with JSON output for production
- Rate Limiting: Automatic retry with exponential backoff (429, 5xx errors)
- Health Checks: HTTP endpoints for monitoring and Kubernetes readiness probes
Type-Safe: Full TypeScript with Zod validation
Comprehensive Tests: 85+ test cases with Vitest

Installation

NPM Global Install

npm install -g @kiket-dev/mcp-server

NPX (No Installation Required)

npx @kiket-dev/mcp-server

From Source

git clone https://github.com/kiket-dev/kiket-mcp-server.git
cd kiket-mcp-server
npm install
cp .env.example .env.local
# Edit .env.local with your KIKET_API_URL and KIKET_API_KEY
npm run dev

Quick Start

After installation, configure your environment variables and run the server:

# Set environment variables
export KIKET_API_URL="https://kiket.dev"
export KIKET_API_KEY="your-api-key-here"

# Run the server
kiket-mcp-server
# or
npx @kiket-dev/mcp-server

The server starts on:

WebSocket: ws://localhost:3001 (MCP protocol)
Health checks: http://localhost:8080 (HTTP)

Environment Variables

Variable	Default	Description
`KIKET_API_URL`	-	Base URL of Kiket instance (e.g. `https://www.kiket.dev`)
`KIKET_API_KEY`	-	Personal access token with issue permissions
`KIKET_PROJECT_KEY`	-	Default project for operations (optional)
`KIKET_VERIFY_SSL`	`true`	Set to `false` to skip TLS verification in dev
`MCP_TRANSPORT`	`websocket`	Transport mode: `websocket` or `stdio`
`MCP_PORT`	`3001`	WebSocket port (websocket mode only)
`HEALTH_PORT`	`8080`	Health check HTTP port (websocket mode only)
`LOG_LEVEL`	`info`	Logging level: `error`, `warn`, `info`, `debug`
`NODE_ENV`	`development`	Environment: `development` or `production`

Transport Modes

WebSocket Mode (Default)

For clients like Claude Desktop that connect via WebSocket:

MCP_TRANSPORT=websocket npm run dev

Stdio Mode

For clients like OpenAI Codex, Gemini, GitHub Copilot that use stdin/stdout:

MCP_TRANSPORT=stdio npm run dev

Available Tools

Issue Management

listIssues

{
  "status": "open",
  "assignee_id": 42,
  "label": "bug",
  "project_key": "BACKEND",
  "search": "authentication",
  "page": 1,
  "per_page": 50
}

getIssue

{
  "id": 123  // or "PROJ-45"
}

createIssue

{
  "title": "Fix login bug",
  "description": "Users cannot log in",
  "project_key": "BACKEND",
  "priority": "high",
  "assignee_id": 42,
  "labels": ["bug", "security"]
}

updateIssue

{
  "id": 123,
  "title": "Updated title",
  "priority": "critical",
  "assignee_id": 99
}

transitionIssue

{
  "id": 123,
  "transition": "start_progress"
}

Comment Management

listComments

{
  "issue_id": 123
}

createComment

{
  "issue_id": 123,
  "body": "This is fixed in PR #456"
}

updateComment

{
  "issue_id": 123,
  "comment_id": 789,
  "body": "Updated comment text"
}

deleteComment

{
  "issue_id": 123,
  "comment_id": 789
}

Project Management

listProjects

{
  "page": 1,
  "per_page": 50
}

getProject

{
  "id": 5
}

createProject

{
  "name": "Platform Redesign",
  "description": "Complete platform UI/UX overhaul",
  "project_key": "REDESIGN",
  "github_repo_url": "https://github.com/org/platform-redesign",
  "visibility": "private",
  "start_date": "2025-01-01",
  "end_date": "2025-12-31",
  "lead_id": 42
}

updateProject

{
  "id": 5,
  "name": "Updated Project Name",
  "description": "Updated description",
  "visibility": "team"
}

deleteProject

{
  "id": 5
}

Milestone Management

listMilestones

{
  "project_id": 5,
  "status": "active"
}

getMilestone

{
  "project_id": 5,
  "milestone_id": 123
}

createMilestone

{
  "project_id": 5,
  "name": "Sprint 42",
  "description": "Q1 2025 release",
  "target_date": "2025-03-31",
  "status": "planning"
}

updateMilestone

{
  "project_id": 5,
  "milestone_id": 123,
  "name": "Sprint 42 - Extended",
  "target_date": "2025-04-15",
  "status": "active"
}

deleteMilestone

{
  "project_id": 5,
  "milestone_id": 123
}

User Management

listUsers

{
  "page": 1,
  "per_page": 50
}

getUser

{
  "id": 42
}

getCurrentUser

{}

Available Prompts

Prompts are guided templates that help AI assistants perform complex workflows. Use them to ensure consistent, well-structured interactions with Kiket.

Issue Management Prompts

Prompt	Description	Key Arguments
`create-issue`	Create a new issue with proper structure	`title` (required), `type`, `priority`, `description`
`create-bug-report`	Create a structured bug report	`title` (required), `steps`, `expected`, `actual`
`create-feature`	Create a feature/user story with acceptance criteria	`title` (required), `user_story`, `acceptance_criteria`, `breakdown`
`update-issue`	Update an existing issue	`issue_id` (required), `changes`
`bulk-update-issues`	Update multiple issues at once	`filter` (required), `action` (required)
`close-issue`	Close/resolve an issue	`issue_id` (required), `resolution`, `comment`
`delete-issue`	Delete an issue (with safety checks)	`issue_id` (required), `reason`

Milestone Management Prompts

Prompt	Description	Key Arguments
`create-milestone`	Create a new milestone/sprint	`title` (required), `start_date`, `due_date`, `description`
`plan-sprint`	Plan a sprint with capacity and issue selection	`sprint_name` (required), `capacity`, `goals`, `duration`
`update-milestone`	Update milestone details	`milestone_id` (required), `changes`
`close-milestone`	Close a milestone and handle incomplete issues	`milestone_id` (required), `incomplete_action`
`delete-milestone`	Delete a milestone	`milestone_id` (required), `issue_action`

Analysis & Reporting Prompts

Prompt	Description	Key Arguments
`daily-standup`	Generate daily standup summary	`user`, `days`
`release-notes`	Generate release notes from completed issues	`milestone` (required), `format`
`backlog-review`	Review and clean up backlog	`project_key`, `stale_days`
`project-overview`	Get comprehensive project overview	`project_key`

Using Prompts

Prompts are invoked via the prompts/get MCP method. Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "prompts/get",
  "params": {
    "name": "create-bug-report",
    "arguments": {
      "title": "Login button not responding",
      "steps": "1. Go to login page\n2. Enter credentials\n3. Click login button",
      "expected": "User should be logged in",
      "actual": "Nothing happens",
      "priority": "high"
    }
  }
}

The prompt returns a structured message that guides the AI through the workflow, including which tools to call and in what order.

Client Configuration

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Using NPX (Recommended - No Installation Required):

{
  "mcpServers": {
    "kiket": {
      "command": "npx",
      "args": [
        "@kiket-dev/kiket-mcp-server"
      ],
      "env": {
        "KIKET_API_URL": "https://kiket.dev",
        "KIKET_API_KEY": "your-api-key-here",
        "KIKET_PROJECT_KEY": "BACKEND"
      }
    }
  }
}

Using Global Install:

{
  "mcpServers": {
    "kiket": {
      "command": "kiket-mcp-server",
      "args": [],
      "env": {
        "KIKET_API_URL": "https://kiket.dev",
        "KIKET_API_KEY": "your-api-key-here",
        "KIKET_PROJECT_KEY": "BACKEND"
      }
    }
  }
}

Using Local Development:

{
  "mcpServers": {
    "kiket": {
      "command": "node",
      "args": [
        "--loader",
        "ts-node/esm",
        "/path/to/kiket/mcp-server/src/server.ts"
      ],
      "env": {
        "KIKET_API_URL": "https://kiket.dev",
        "KIKET_API_KEY": "your-api-key-here",
        "KIKET_PROJECT_KEY": "BACKEND"
      }
    }
  }
}

OpenAI Codex / o3-mini CLI

Edit ~/.config/openai/mcp.json:

{
  "servers": {
    "kiket": {
      "command": "npx",
      "args": [
        "@kiket-dev/mcp-server"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "KIKET_API_URL": "https://kiket.dev",
        "KIKET_API_KEY": "your-api-key-here"
      }
    }
  }
}

GitHub Copilot CLI

Edit ~/.config/github-copilot/mcp.json:

{
  "servers": {
    "kiket": {
      "command": "npx",
      "args": [
        "@kiket-dev/mcp-server"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "KIKET_API_URL": "https://kiket.dev",
        "KIKET_API_KEY": "your-api-key-here"
      }
    }
  }
}

Gemini CLI (aistudio)

Edit ~/.config/aistudio/mcp_servers.json:

{
  "kiket": {
    "command": "npx",
    "args": [
      "@kiket-dev/mcp-server"
    ],
    "env": {
      "MCP_TRANSPORT": "stdio",
      "KIKET_API_URL": "https://kiket.dev",
      "KIKET_API_KEY": "your-api-key-here"
    }
  }
}

Health Checks

The health check server (WebSocket mode only) provides endpoints for monitoring:

Liveness Probe - Is the server running?

curl http://localhost:8080/health

{
  "status": "ok",
  "timestamp": "2025-01-10T12:00:00.000Z",
  "uptime": 3600.5
}

Readiness Probe - Can the server handle requests?

curl http://localhost:8080/ready

{
  "ready": true,
  "timestamp": "2025-01-10T12:00:00.000Z"
}

Detailed Health Check

curl http://localhost:8080/health/details

{
  "status": "healthy",
  "timestamp": "2025-01-10T12:00:00.000Z",
  "checks": {
    "api": {
      "healthy": true,
      "latency": 45
    }
  }
}

Error Handling

The server provides detailed JSON-RPC error codes:

Code	Error Type	Description
`-32001`	Authentication Error	Invalid or missing API key
`-32002`	Authorization Error	Insufficient permissions
`-32003`	Not Found	Resource doesn't exist
`-32004`	Validation Error	Invalid input data
`-32005`	Rate Limit	Too many requests
`-32006`	Server Error	Kiket API error
`-32603`	Internal Error	Unexpected server error

Example error response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32003,
    "message": "Issue not found: 999",
    "data": null
  }
}

Production Features

Structured Logging

The server uses Winston for structured logging with different output formats for development and production:

Development Mode: Colorized, human-readable logs

LOG_LEVEL=debug NODE_ENV=development npm run dev

Production Mode: JSON-formatted logs for log aggregation

LOG_LEVEL=info NODE_ENV=production npm start

Log Levels:

error: Only errors
warn: Warnings and errors
info: General information (default)
debug: Detailed debugging information

All requests are logged with:

Request ID (UUID)
Method name
Tool name (for tools/call)
Duration (milliseconds)
Error details (if applicable)

Rate Limiting

Automatic retry with exponential backoff for transient failures:

Retriable Errors:

429 (Rate Limit): Respects Retry-After header if provided
5xx (Server Errors): Retries with exponential backoff
Network errors: ECONNRESET, ENOTFOUND, ECONNREFUSED, timeouts

Configuration:

Max retries: 3
Base delay: 1000ms
Max delay: 30000ms
Jitter: 0-25% of delay (prevents thundering herd)

Backoff Formula: delay = min(baseDelay * 2^attempt + jitter, maxDelay)

Example retry sequence:

Initial failure
Retry after ~1000ms (1s + jitter)
Retry after ~2000ms (2s + jitter)
Retry after ~4000ms (4s + jitter)
Final failure

All API requests are automatically wrapped with rate limiting - no configuration needed!

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm test -- --coverage

# Lint code
npm run lint

# Build TypeScript
npm run build

# Start in dev mode
npm run dev

Docker Deployment

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 3001 8080

CMD ["node", "dist/server.js"]

docker build -t kiket-mcp-server .
docker run -p 3001:3001 -p 8080:8080 \
  -e KIKET_API_URL=https://www.kiket.dev \
  -e KIKET_API_KEY=sk-... \
  kiket-mcp-server

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: kiket-mcp-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: kiket-mcp-server
  template:
    metadata:
      labels:
        app: kiket-mcp-server
    spec:
      containers:
      - name: mcp-server
        image: kiket-mcp-server:latest
        ports:
        - containerPort: 3001
          name: websocket
        - containerPort: 8080
          name: health
        env:
        - name: KIKET_API_URL
          valueFrom:
            secretKeyRef:
              name: kiket-credentials
              key: api-url
        - name: KIKET_API_KEY
          valueFrom:
            secretKeyRef:
              name: kiket-credentials
              key: api-key
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 10

Testing

The server includes comprehensive tests:

Error handling (19 tests)
MCP protocol (10 tests)
Kiket client (3 tests)
Issue tools (7 tests)
Project tools (9 tests)
User tools (7 tests)

Run tests:

npm test

CI/CD

GitHub Actions automatically:

Runs tests on push/PR
Lints code
Builds TypeScript
Publishes to GitHub Packages on release
Attaches tarball to GitHub releases

License

MIT

Support

Documentation: https://docs.kiket.dev/extensions/mcp-server
Issues: https://github.com/kiket-dev/kiket-mcp-server/issues
Slack: https://kiket.dev/slack