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:

License

MIT

Contributing

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