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

Variable	Required	Default	Description
JPI_API_TOKEN	Yes	-	Your JPI API token
JPI_BASE_URL	No	https://api.just-plan-it.com	JPI API base URL

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	Unit	Example
ProductionTimePerUnit	seconds	3600 = 1 hour
SetupTime	seconds	900 = 15 minutes
TeardownTime	seconds	600 = 10 minutes
TransferTime	seconds	300 = 5 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)

Tool	Description
jpi_api_info	Get API information and available endpoints

Components (9 tools)

Tool	Description
jpi_list_components	List all components
jpi_create_component	Create a new component
jpi_get_component	Get a component by GUID
jpi_update_component	Update a component
jpi_delete_component	Delete a component
jpi_get_component_task	Get a component task
jpi_add_component_task	Add a task to a component
jpi_update_component_task	Update a component task
jpi_delete_component_task	Delete a component task

Jobs (27 tools)

Tool	Description
jpi_list_jobs	List all jobs
jpi_list_jobs_summary	List jobs without task details (~80% smaller)
jpi_list_jobs_at_risk	List jobs at risk of missing due dates
jpi_create_job	Create a new job with tasks
jpi_get_job	Get a job by GUID
jpi_update_job	Update a job
jpi_delete_job	Delete a job
jpi_get_task	Get a job task
jpi_add_task	Add a task to a job
jpi_update_task	Update a job task
jpi_delete_task	Delete a job task
jpi_get_jcr	Get a Job Component Reference
jpi_add_jcr	Add a JCR to a job
jpi_update_jcr	Update a JCR
jpi_delete_jcr	Delete a JCR
jpi_create_jobs_batch	Create multiple jobs
jpi_update_jobs_batch	Update multiple jobs
jpi_delete_jobs_batch	Delete multiple jobs
jpi_add_tasks_batch	Add multiple tasks to a job
jpi_update_tasks_batch	Update multiple tasks
jpi_delete_tasks_batch	Delete multiple tasks
jpi_add_jcrs_batch	Add multiple JCRs
jpi_update_jcrs_batch	Update multiple JCRs
jpi_delete_jcrs_batch	Delete multiple JCRs
jpi_create_tasks_cross_jobs	Create tasks across multiple jobs
jpi_update_tasks_cross_jobs	Update tasks across multiple jobs
jpi_delete_tasks_cross_jobs	Delete tasks across multiple jobs

Job Templates (13 tools)

Tool	Description
jpi_list_templates	List all templates
jpi_create_template	Create a new template
jpi_get_template	Get a template by GUID
jpi_update_template	Update a template
jpi_delete_template	Delete a template
jpi_get_template_task	Get a template task
jpi_add_template_task	Add a task to a template
jpi_update_template_task	Update a template task
jpi_delete_template_task	Delete a template task
jpi_get_tcr	Get a Template Component Reference
jpi_add_tcr	Add a TCR to a template
jpi_update_tcr	Update a TCR
jpi_delete_tcr	Delete a TCR

JPI Events (2 tools)

Tool	Description
jpi_get_events	Get events (change log) after a timestamp
jpi_get_events_filtered	Get events filtered by type

Resource Categories (5 tools)

Tool	Description
jpi_list_resource_categories	List all categories
jpi_create_resource_category	Create a category
jpi_get_resource_category	Get a category
jpi_update_resource_category	Update a category
jpi_delete_resource_category	Delete a category

Resource Groups (5 tools)

Tool	Description
jpi_list_resource_groups	List all groups
jpi_create_resource_group	Create a group
jpi_get_resource_group	Get a group
jpi_update_resource_group	Update a group
jpi_delete_resource_group	Delete a group

Resources (5 tools)

Tool	Description
jpi_list_resources	List all resources
jpi_create_resource	Create a resource
jpi_get_resource	Get a resource
jpi_update_resource	Update a resource
jpi_delete_resource	Delete a resource

Settings (2 tools)

Tool	Description
jpi_get_settings	Get application settings
jpi_update_settings	Update settings

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

Value	Description
Quoted	Job is quoted but not ordered
Ordered	Job is ordered but not released
Released	Job is released for production
Standby	Job is on standby

Strategy

Value	Description
Asap	Schedule as soon as possible
Jit	Just-in-time scheduling
ASAP_PLUS	ASAP with buffer
JIT_PLUS	JIT with buffer

TaskStatus

Value	Description
Planned	Task is planned
Started	Task has started
Finished	Task is complete
None	No status
Standby	Task is on standby

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.