japex-mcp

A Model Context Protocol (MCP) server for TaskZilla / Japex — lets Claude pick up a task from your backlog and implement it autonomously through a structured Plan → Execute → Test → Review → Git workflow, powered by customisable skill files.

How It Works

When you ask Claude to work on a task, it calls a sequence of MCP tools that each launch a focused sub-agent:

implement_task  →  plan_task  →  execute_task  →  test_task  →  review_task  →  git_task
     │                │               │               │               │              │
 set IN_PROGRESS  planning sub-    backend/ui      testing        code review   commit + push
 list skills      agent explores   sub-agent       sub-agent      sub-agent     + mark DONE
                  codebase &       writes code     writes &       fixes issues
                  asks questions   & reports       runs tests     & reports

Each sub-agent receives a skill file as its system prompt. Skill files live in .japex/skills/ in your project directory. You can edit them or add new ones to match your stack's exact conventions.

Quick Start

1. Install globally

npm install -g japex-mcp

2. Add to Claude Code

claude mcp add --scope user japex-mcp cmd /c japex-mcp   # Windows
claude mcp add --scope user japex-mcp japex-mcp           # macOS / Linux

Or add directly to your MCP config:

Claude Code (~/.claude.json via claude mcp add, or manually):

{
  "mcpServers": {
    "japex-mcp": {
      "command": "cmd",
      "args": ["/c", "japex-mcp"]
    }
  }
}

Claude Desktop (claude_desktop_config.json):

"japex-mcp": {
  "command": "japex-mcp"
}

Cursor / Windsurf (~/.cursor/mcp.json or equivalent):

{
  "mcpServers": {
    "japex-mcp": {
      "command": "japex-mcp"
    }
  }
}

3. Initialise skills in your project

In the project directory you want to work in, ask Claude to run:

init_skills

This copies the default skill files into .japex/skills/ inside your project. You only need to do this once per project.

4. Sign in

On first use the server opens your browser for a Google sign-in. After that, the session is cached at ~/.japex/session.json and reused automatically.

5. Start working

Ask Claude: "Show me my Japex tasks and let's work on one."

Claude will call list_tasks, let you pick a task, then run the full workflow autonomously.

Skills

Skills are the core of the implementation workflow. Each phase uses a skill file as its sub-agent's system prompt.

Default skills

| File | Phase | Purpose | |------|-------|---------| | planning.md | Plan | Explores codebase, asks clarifying questions, produces an implementation plan | | backend.md | Execute | Implements server-side changes (Express, Prisma, auth middleware) | | ui.md | Execute | Implements frontend changes (React, Zustand, Tailwind) | | testing.md | Test | Finds or creates tests, runs the suite, fixes failures | | review.md | Review | Checks quality, performance, and security; fixes issues found |

Skill file format

Each skill is a Markdown file with optional YAML front-matter:

---
name: My Custom Skill
applies_to: graphql, resolvers, subscriptions
model: claude-sonnet-4-6
---

# My Custom Skill

## Role
You are an expert in ...

## Process
1. Read the task ...
2. Explore ...

| Front-matter field | Required | Description | |--------------------|----------|-------------| | name | No | Human-readable name shown in implement_task output | | applies_to | No | Comma-separated keywords — shown to Claude when picking skills | | model | No | Claude model to use for this sub-agent (default: claude-sonnet-4-6) |

Everything after the closing --- is used as the sub-agent's system prompt verbatim.

Editing a skill

Open .japex/skills/<skill-name>.md in your editor and modify it. Changes take effect on the next tool call — no restart needed.

# Example: open the backend skill in VS Code
code .japex/skills/backend.md

Adding a custom skill

Create any .md file in .japex/skills/. It will automatically appear in the skills table shown by implement_task.

# Example: add a GraphQL skill
cp .japex/skills/backend.md .japex/skills/graphql.md
# then edit .japex/skills/graphql.md

When calling execute_task, pass your skill's filename (without .md) in the skills array:

execute_task  task_id: "..."  skills: ["graphql"]

For a fullstack task, pass multiple skills and the sub-agent will apply both:

execute_task  task_id: "..."  skills: ["backend", "ui"]

Resetting to defaults

To reset a skill to its default, delete the file and re-run init_skills:

rm .japex/skills/backend.md
# then ask Claude to run init_skills

init_skills skips files that already exist, so only the deleted file will be re-created.

Tools

init_skills

Copies the default skill files into ./.japex/skills/ in the current working directory. Existing files are never overwritten. Safe to re-run to pick up newly shipped default skills.

Parameters: none

list_tasks

Fetches all non-DONE tasks assigned to the signed-in user across all projects.

Parameters: none

Returns: A markdown table with task number, title, project, priority, status, and due date. Task UUIDs are listed below the table for use with implement_task.

| S.No. | Task No. | Title          | Project | Priority | Status      | Due        |
|-------|----------|----------------|---------|----------|-------------|------------|
| 1     | TZ-042   | Fix login flow | Japex   | HIGH     | IN_PROGRESS | 2026-05-10 |

Task IDs (use with implement_task):
1. cmo...

implement_task

Fetches full task details, sets the task to IN_PROGRESS, and lists the available skills in .japex/skills/. Returns everything Claude needs to identify the right skill(s) and call plan_task.

Errors with a helpful message if .japex/skills/ hasn't been initialised yet.

Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | task_id | string | Task UUID from list_tasks |

plan_task

Launches an autonomous planning sub-agent (using planning.md) that:

• Reads the task description
• Explores the codebase with Read, Grep, and Glob
• Identifies ambiguities and asks clarifying questions
• Produces a structured implementation plan

Returns the plan. Claude presents it to you; you answer any questions and approve before execution begins.

Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | task_id | string | Task UUID |

execute_task

Launches an autonomous execution sub-agent using the specified skill(s). The sub-agent reads the approved plan and implements it — creating and modifying files in the project directory.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | task_id | string | Yes | Task UUID | | skills | string[] | Yes | Skill file names to apply, e.g. ["backend"], ["backend","ui"] | | context | string | No | The approved plan text from plan_task — paste it here so the sub-agent has it |

test_task

Launches an autonomous testing sub-agent (using testing.md) that:

• Finds changed files via git diff
• Locates existing test files for the changed code
• Adds tests for new functionality or creates new test files if none exist
• Runs the full test suite and fixes every failure
• Reports pass/fail counts

Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | task_id | string | Task UUID |

review_task

Launches an autonomous code review sub-agent (using review.md) that reviews every changed file against a quality, performance, and security checklist, fixes any issues found, and reports the results.

Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | task_id | string | Task UUID |

git_task

Creates (or checks out) a feature/<slug>-<taskNumber> branch, stages all changes, commits with a standardised message, pushes to origin, marks the task DONE on Japex, and adds a comment with the branch name and commit SHA.

Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | task_id | string | Task UUID |

complete_task

Marks a task as DONE on Japex without committing. Use this if you prefer to commit manually or skip git_task.

Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | task_id | string | Task UUID |

list_projects

Lists all Japex projects the signed-in user is a member of.

Parameters: none

Returns:

| # | Project | Status | Project ID |
|---|---------|--------|------------|
| 1 | Japex   | ACTIVE | cmo...     |

create_task

Creates a new task on Japex, optionally with subtasks in a single call.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | project_id | string | Yes | Project ID from list_projects | | title | string | Yes | Task title | | description | string | No | Task description (markdown supported) | | priority | string | No | LOW, MEDIUM (default), or HIGH | | due_date | string | No | ISO date, e.g. "2026-05-01" | | assignee_id | string | No | User ID to assign the task to | | parent_id | string | No | Parent task ID — creates this as a subtask | | subtasks | array | No | Subtasks to create under this task |

Each subtasks entry accepts: title (required), description, priority, due_date.

Authentication

On first use, the server opens your default browser for a Google sign-in flow. After authentication the session is saved to ~/.japex/session.json and reused on subsequent calls. If the access token expires it is refreshed automatically; if the refresh token is invalid the sign-in flow re-runs.

Configuration

| Environment Variable | Default | Purpose | |----------------------|---------|---------| | JAPEX_API_URL | https://japex.forsysinc.com | Override the Japex backend URL | | TASKZILLA_API_URL | (fallback) | Legacy alias for JAPEX_API_URL |

Technical Reference

Architecture

MCP Client (Claude Code)
        │  JSON-RPC 2.0 over stdio
        ▼
  bin/run.js  ──► tsx ──► src/mcp-server.ts
                               │
                    ┌──────────┼──────────┬──────────┐
                    ▼          ▼          ▼          ▼
               auth.ts      api.ts    types.ts  src/skills/
           (OAuth/session) (axios)  (interfaces) (markdown)
                                                    │
                                          read at runtime
                                          into sub-agents
                                                    │
                                          @anthropic-ai/claude-agent-sdk
                                          query() → Claude sub-agents
                                          (plan / execute / test / review)

• bin/run.js — thin launcher; resolves tsx and mcp-server.ts relative to itself using import.meta.url.
• src/mcp-server.ts — MCP server; registers all tools; helpers for loading skills and running sub-agents.
• src/skills/ — default skill markdown files shipped with the package; copied to project .japex/skills/ by init_skills.
• src/auth.ts — Google OAuth CLI flow; session persisted at ~/.japex/session.json.
• src/api.ts — Axios wrapper around the Japex REST API.
• src/types.ts — TaskSummary (list fields) and Task (full record).

Sub-agent behaviour

Phase tools spawn Claude sub-agents via @anthropic-ai/claude-agent-sdk's query() function. Each sub-agent:

• Receives the skill file body as its system prompt
• Receives task context (title, description, project) as the user message
• Runs in bypassPermissions mode so it can read/write files and run shell commands without prompting
• Works in process.cwd() — the directory Claude Code was launched from

The outer Claude session orchestrates the phases; sub-agents do the actual file work.

API Endpoints Used

| Method | Path | Used by | |--------|------|---------| | GET | /api/users/me/tasks | list_tasks | | GET | /api/tasks/:id | implement_task, plan_task, execute_task, test_task, review_task, git_task | | PUT | /api/tasks/:id | implement_task, git_task, complete_task | | GET | /api/projects | list_projects | | POST | /api/tasks/projects/:projectId/tasks | create_task | | POST | /api/tasks/:id/comments | git_task | | POST | /api/auth/refresh | token refresh |

Runtime Dependencies

| Package | Purpose | |---------|---------| | @anthropic-ai/claude-agent-sdk | Launch Claude sub-agents for each workflow phase | | @modelcontextprotocol/sdk | MCP server + stdio transport | | axios | HTTP client for Japex API | | zod | Tool parameter schema | | open | Opens browser for OAuth flow | | tsx | TypeScript runtime (no build step) |

Publishing

cd agent/
npm login          # one-time, requires npm account
npm publish        # publishes as japex-mcp

The files field in package.json includes src/ which covers src/skills/. DevDependencies are excluded at runtime.

License

Internal — Forsys Inc.