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.

---

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).

Environment Variable	Description
EASYJOB_API_BASE_URL	Required. The absolute URL to the easyJOB app (e.g., https://easy4.because-software.com/drid/app).
EASYJOB_USERNAME	The easyJOB login name (used for password grant token lookup & user ID resolution).
EASYJOB_PASSWORD	The easyJOB password (used for password grant token lookup).
EASYJOB_CLIENT_ID	OAuth Client ID (if using client credentials flow or required for password flow).
EASYJOB_CLIENT_SECRET	OAuth Client Secret (if using client credentials flow).
EASYJOB_TOKEN_URL	Optional. Custom OAuth Token URL (defaults to ${EASYJOB_API_BASE_URL}/oauth/token).
EASYJOB_API_TOKEN	Optional. A static, long-lived bearer token (bypasses automatic auth flows).

---

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.