easyJOB Model Context Protocol (MCP) Server

A clean, stable, and highly configurable Model Context Protocol (MCP) server for the easyJOB REST API.

This server manages dynamic OAuth authentication token fetching and caching, simplifies complex multi-query workflows (such as looking up user and job IDs to record time), and provides full read/write access to easyJOB via generic endpoints.

Features

• Automated Token Management: Fetches and caches the OAuth bearer token, refreshing it automatically in-memory.

• Specific Tools:

  • get_user_id — Lookup internal user IDs by username/login name.

  • search_jobs — Match jobs by name, short name, or job number.

  • track_time — Directly post a time record (hours logged) to a job.

• Generic CRUD/Query Tools:

  • query_entities — Run complex FetchsonQuery filter operations.

  • create_or_update_entity — Create or update any table entity.

  • delete_entity — Delete an entity by ID.

Related MCP server: OAuth MCP Server

Installation & Setup

1. Install Dependencies

Run the following command inside this directory to install the @modelcontextprotocol/sdk:

npm install

2. Configuration (Environment Variables)

The server reads its configuration from environment variables. You can set these in your terminal, a .env file (if running locally/testing), or directly in your MCP client's configuration (e.g., Claude Desktop).

Integration in Claude Desktop

To configure the server in Claude Desktop, edit your claude_desktop_config.json configuration file:

On Linux/macOS: ~/.config/Claude/claude_desktop_config.json or ~/Library/Application Support/Claude/claude_desktop_config.json

Add the server config:

{
  "mcpServers": {
    "easyjob": {
      "command": "node",
      "args": ["/absolute/path/to/jolly-hypatia/index.js"],
      "env": {
        "EASYJOB_API_BASE_URL": "https://easy4.because-software.com/drid/app",
        "EASYJOB_USERNAME": "your_username",
        "EASYJOB_PASSWORD": "your_password",
        "EASYJOB_CLIENT_ID": "optional_client_id",
        "EASYJOB_CLIENT_SECRET": "optional_client_secret"
      }
    }
  }
}

Restart Claude Desktop after editing the configuration.

Available Tools

1. get_user_id

• Description: Get the internal easyJOB User ID for the user configured in the environment (EASYJOB_USERNAME).

• Arguments: None. (Resolves strictly to the authenticated user context for security).

2. search_jobs

• Description: Search for jobs by name, short name, or job number.

• Arguments:

  • query (string, required): Wildcard search term.

3. track_time

• Description: Log working hours on a specific job in easyJOB. Creates a TimeRecording entry strictly for the configured user timesheet.

• Arguments:

  • job_id (integer, required): Internal ID of the Job.

  • amount (number, required): Time in hours (e.g., 1.5 or 0.25).

  • description (string, required): Work description.

  • date (string, optional): Date in YYYY-MM-DD format (defaults to today).

  • time_recording_type_id (integer, optional): Custom work type ID (from Activity/Leistung table).

4. query_entities

• Description: Run a custom FetchsonQuery.

• Arguments:

  • query (object, required): A FetchsonQuery JSON definition.

5. create_or_update_entity

• Description: Create or update any entity in easyJOB.

• Arguments:

  • entity (string, required): Entity name (e.g., 'Task').

  • data (object, required): Entity fields and values.

• Note: Creating or updating TimeRecording entities via this tool is disabled for security. Use track_time instead.

6. delete_entity

• Description: Delete an entity by ID.

• Arguments:

  • entity (string, required): Entity name.

  • id (integer, required): Target entity ID.

Available Prompts

1. import-hours

• Description: A guided prompt template to help the AI dry-run map, verify, and import a batch of working hours (timesheet) into easyJOB.

• Arguments:

  • hoursList (string, required): The list or table of working hours to log.

Available Resources

1. easyjob://docs/skill

• Description: The complete integration guide and safety protocols (content of SKILL.md) read dynamically from disk.

2. easyjob://user/profile

• Description: Dynamically retrieves the profile, department details, and status of the currently authenticated user from the easyJOB database.