JPI MCP Server

Model Context Protocol (MCP) server for Just Plan It (JPI) API integration. This server enables AI assistants to interact with the JPI job scheduling and resource management system.

Features

• 69 MCP Tools covering all JPI API endpoints
• Full CRUD operations for all JPI entities
• Batch operations for efficient bulk updates
• Cross-job task operations
• Type-safe TypeScript implementation
• Comprehensive error handling

Quick Start

Prerequisites

• Node.js 18+
• A JPI API token (get from Just Plan It)

Claude Code CLI

claude mcp add jpi \
  --transport stdio \
  --env JPI_API_TOKEN=your-api-token-here \
  --scope user \
  -- npx -y jpi-mcp

Claude Desktop

Add to your Claude Desktop configuration file:

{
  "mcpServers": {
    "jpi": {
      "command": "npx",
      "args": ["-y", "jpi-mcp"],
      "env": {
        "JPI_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Direct CLI Usage

For other CLI tools or direct shell usage:

Unix/macOS/Linux:

JPI_API_TOKEN=your-token npx -y jpi-mcp

Windows PowerShell:

$env:JPI_API_TOKEN="your-token"; npx -y jpi-mcp

Windows CMD:

set JPI_API_TOKEN=your-token && npx -y jpi-mcp

Environment Variables

Architecture

jpi-mcp/
├── src/
│   ├── index.ts          # MCP server setup, 69 tool definitions, request handlers
│   ├── client.ts         # JpiClient class - HTTP client for JPI API v1
│   └── types/            # TypeScript types matching JPI API schemas
│       ├── index.ts      # Re-exports all types
│       ├── enums.ts      # OrderStatus, Strategy, TaskStatus, EventType, etc.
│       ├── schemas.ts    # Common schemas (Identifier, HyperLink, ResourceGroupConstraint)
│       ├── jobs.ts       # Job, Task, JobComponentReference types
│       ├── components.ts # Component, ComponentTask types
│       ├── templates.ts  # JobTemplate, TemplateTask, TemplateComponentReference types
│       ├── resources.ts  # Resource, ResourceGroup, ResourceCategory types
│       ├── settings.ts   # Application settings types
│       └── events.ts     # JPI event/change log types
└── package.json

Key Concepts

Jobs & Tasks

• Job: A production order or work order containing one or more tasks
• Task: A single operation within a job (e.g., cutting, welding, painting)
• Predecessors: Tasks that must complete before a task can start
• TaskConnections: Linked tasks for scheduling coordination

Components & References

• Component: A reusable template of tasks that can be referenced by jobs
• JCR (Job Component Reference): Links a component to a job, creating tasks automatically
• TCR (Template Component Reference): Links a component to a job template

Resource Hierarchy

Resource Categories
    └── Resource Groups
            └── Resources (machines, workers, etc.)

Time Units

IMPORTANT: All time fields in the JPI API are in SECONDS, not minutes.

Field Naming Convention

All API fields use PascalCase to match the JPI API exactly (e.g., DueDate, TaskNo, ResourceGroupConstraints).

Available Tools (69 Total)

Helper (1 tool)

Components (9 tools)

Jobs (27 tools)

Job Templates (13 tools)

JPI Events (2 tools)

Resource Categories (5 tools)

Resource Groups (5 tools)

Resources (5 tools)

Settings (2 tools)

Usage Examples

Create a Job with Tasks

{
  "Name": "Production Order 001",
  "JobNo": "PO-001",
  "DueDate": "2024-12-31T17:00:00",
  "ReleaseDate": "2024-12-01T08:00:00",
  "Strategy": "Asap",
  "OrderStatus": "Released",
  "Customer": "ACME Corp",
  "Quantity": 100,
  "Tasks": [
    {
      "TaskNo": "T010",
      "Name": "Laser Cutting",
      "ProductionTimePerUnit": 60,
      "SetupTime": 900,
      "ResourceGroupConstraints": [
        {
          "ResourceGroup": "resource-group-guid-here"
        }
      ]
    },
    {
      "TaskNo": "T020",
      "Name": "Welding",
      "ProductionTimePerUnit": 120,
      "PredecessorTaskNos": ["T010"],
      "ResourceGroupConstraints": [
        {
          "ResourceGroup": "welding-group-guid"
        }
      ]
    }
  ]
}

Update Task Status

{
  "jobGuid": "job-guid-here",
  "taskGuid": "task-guid-here",
  "TaskStatus": "Started"
}

Batch Create Jobs

{
  "jobs": [
    { "Name": "Job 1", "Tasks": [...] },
    { "Name": "Job 2", "Tasks": [...] },
    { "Name": "Job 3", "Tasks": [...] }
  ]
}

Enums & Types

OrderStatus

Strategy

TaskStatus

Error Handling

All tools return structured error responses:

{
  "error": true,
  "status": 400,
  "statusText": "Bad Request",
  "message": "JPI API Error: 400 Bad Request",
  "body": {
    "details": "Validation failed for field 'Name'"
  }
}

Development

Build

npm run build

Watch Mode

npm run dev

Run Locally

JPI_API_TOKEN=your-token npm start

From Source

git clone https://github.com/anthropics/jpi-mcp.git
cd jpi-mcp
npm install
npm run build
npm start

API Reference

This MCP server wraps the JPI REST API v1. For detailed API documentation:

• JPI API Swagger
• Just Plan It Website

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.