Skip to content

MCP Core Tools

Easy8 core tools are available from the built-in MCP server when the related service classes load successfully and the effective API user has the required permissions.

Every tool publishes a JSON schema through tools/list; clients should use that schema as the source of truth for accepted arguments and supported filters. Cross-field requirements are still validated by the tool at runtime.

easy8_projects_list

Lists visible projects.

Use it when the client needs to resolve a project before creating or filtering issues.

Arguments:

  • limit - maximum number of projects to return
  • offset - pagination offset
  • name - project name filter

easy8_users_me

Returns the effective Easy8 user for this MCP request.

Use it when the prompt contains terms like me, my, mine, or assigned to me and the client wants to resolve the current user before calling another tool.

Example request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "easy8_users_me",
    "arguments": {}
  }
}

Searches visible active users and returns IDs suitable for assignment.

Arguments:

  • limit - maximum number of users to return
  • offset - pagination offset
  • query - name, login, or numeric user ID to search
  • project_id - optional visible project ID; limits results to project members

easy8_issues_list

Lists visible issues.

For prompts such as Show me all issues which are assigned to me, call this tool with assigned_to_id: "me". The server resolves me through the effective API user described in User identity.

The response includes issue metadata, description, comments_count, start_date, due_date, tag_list, custom_fields, and nested reference objects for related records such as project, tracker, status, priority, author, and assigned_to. Each visible custom field contains id, name, and value; values can be arrays for multiple-value fields. List responses include offset, limit, and has_more metadata. When has_more is true, the response also includes next_offset. The response includes total_count only when include_total_count is true; counting broad result sets can be expensive.

Arguments:

  • limit - maximum number of issues to return
  • offset - pagination offset
  • project_id - filter by project
  • assigned_to_id - filter by assignee user ID, or use "me" for the effective current MCP user
  • status - high-level status filter, all, open, or closed
  • status_id - specific status ID or list of IDs
  • subject - subject text filter
  • due_date_period - relative due date filter
  • sort_by - sortable EasyIssueQuery column name, such as created_on or updated_on
  • sort_direction - sort direction, asc or desc
  • include_total_count - when true, include total_count; use only when the client needs an exact count

easy8_issues_get

Returns one visible issue by ID.

Arguments:

  • id - issue ID
  • include_journals - when true, include a paginated page of visible journal notes
  • journals_limit - maximum number of journal notes returned when include_journals is true
  • journals_offset - pagination offset for journal notes when include_journals is true

The response includes issue metadata, description, tag_list, custom_fields, and comments_count. Each visible custom field contains id, name, and value; values can be arrays for multiple-value fields. When include_journals is true, the response also includes journals, journals_total_count, journals_offset, and journals_limit.

easy8_issues_comments_list

Lists visible issue journal notes ordered from newest to oldest.

Arguments:

  • id - issue ID
  • limit - maximum number of comments
  • offset - pagination offset

The response includes comments, total_count, offset, and limit.

Issue attachment tools

Use these tools when the user asks to attach files to a task/issue, list files already attached to a task/issue, or read an attachment so the assistant can analyze its contents.

Tools:

  • easy8_issue_attachments_list - lists visible attachments on an issue
  • easy8_issue_attachments_upload - uploads content provided in the tool arguments as a new issue attachment
  • easy8_issue_attachments_read - reads one visible issue attachment or a selected attachment version, returning text, an image, or metadata for unsupported binary formats

Important behavior:

  • Do not pass local file paths to easy8_issue_attachments_upload; the Easy8 server cannot read files from the client machine.
  • To upload a local file, the client-side assistant must read the file content first, then pass that content as content.
  • Use content_encoding: "plain" for text and content_encoding: "base64" for binary files.
  • When the attachment ID is unknown, use easy8_issue_attachments_list first.
  • easy8_issue_attachments_read keeps JSON metadata in the first MCP text block, result.content[0].text.
  • In content_format: "auto", files detected as image/* from their bytes using Marcel return the complete original image as a separate standard MCP image block with type: "image", base64 data, and the detected mimeType. The metadata reports analysis_supported: true. Image data is not embedded in the metadata JSON or encoded as another text block.
  • The image path has no size limit and does not create thumbnails, resize, convert, or truncate images. max_bytes does not limit images in auto mode.
  • Text-like files return content_encoding: "plain" and may be truncated according to max_bytes. Explicit content_format: "text" forces UTF-8 text reading, with invalid bytes replaced, even for images or other binary files; the text byte limit applies in this mode.
  • Unsupported non-image binary files, such as PDFs and spreadsheets, still return metadata only with analysis_supported: false in auto mode.
  • Client/provider payload limits and image-format support are external constraints; this code does not bypass them. Reading original image bytes requires memory proportional to the file size, plus the base64 representation. See Attachment read troubleshooting.

Read arguments:

  • id - required issue ID
  • attachment_id - required Attachment.id by default; an AttachmentVersion.id when version is true
  • version - optional boolean, defaults to false; set to true for an attachment-version URL such as /attachments/789?version=true, passing 789 as attachment_id
  • content_format - auto (default) or text
  • max_bytes - text-read limit in bytes, defaults to 262144 (256 KiB), capped at 1048576 (1 MiB); applies only to text-like reads and explicit content_format: "text"

The version flag selects the ID namespace explicitly. There is no fallback from Attachment to AttachmentVersion or vice versa, even if the same numeric ID exists in both tables. The server scopes lookup to the visible issue and checks the parent attachment and selected version permissions; possession of an ID or URL does not grant access.

For a selected version, response metadata keeps attachment.id as the parent Attachment.id. attachment.version_id identifies the selected AttachmentVersion record, and attachment.version is its version number. File metadata and returned bytes come from that selected version, not the current parent file. Privacy (is_private) remains that of the parent attachment.

All IDs in the examples below are synthetic and do not establish any real issue/attachment relationship.

Example upload request:

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "easy8_issue_attachments_upload",
    "arguments": {
      "id": 123,
      "filename": "analysis.md",
      "content": "# Analysis\n\nSummary from the assistant.",
      "content_encoding": "plain",
      "content_type": "text/markdown",
      "description": "Generated analysis"
    }
  }
}

Example read request:

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "easy8_issue_attachments_read",
    "arguments": {
      "id": 123,
      "attachment_id": 456,
      "content_format": "auto",
      "max_bytes": 262144
    }
  }
}

Example version read request, assuming the synthetic URL /attachments/789?version=true belongs to a version of attachment 456 on issue 123:

{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "tools/call",
  "params": {
    "name": "easy8_issue_attachments_read",
    "arguments": {
      "id": 123,
      "attachment_id": 789,
      "version": true,
      "content_format": "auto"
    }
  }
}

For the image response layout, see Attachment image content.

easy8_issues_create

Creates a new issue.

Arguments include:

  • project selectors: project_id, projectId, project, project_name, project_identifier
  • subject aliases: subject, title, name
  • issue fields: tracker_id, description, description_format, assigned_to_id, priority_id, status_id, parent_issue_id, parent_id, start_date, due_date
  • custom fields: custom_fields

Notes:

  • the issue subject is required
  • a project selector is required
  • permissions are checked with standard Easy8 authorization
  • required custom fields are validated server-side
  • parent_issue_id creates a subtask; parent_id is accepted as an alias when parent_issue_id is absent

easy8_issues_update

Updates an existing issue.

Arguments include:

  • id - issue ID
  • subject
  • description
  • assigned_to_id
  • priority_id
  • status_id
  • parent_issue_id - moves the issue under another issue; use null to remove the parent
  • parent_id - alias for parent_issue_id when parent_issue_id is absent
  • start_date
  • due_date
  • custom_fields - array of { "id": integer, "value": string | integer | array } values
  • notes - appends a new comment to the issue journal
  • description_format and notes_format - set to markdown when sending Markdown text

Changing a custom field follows the normal issue update flow and records a journal entry when the value changes.

Project workflow tools

  • easy8_projects_get
  • easy8_projects_create
  • easy8_projects_update
  • easy8_projects_archive
  • easy8_projects_unarchive
  • easy8_projects_close
  • easy8_projects_reopen
  • easy8_projects_copy

easy8_projects_get returns visible project custom_fields as { "id", "name", "value" } objects. Values can be arrays for multiple-value fields.

Project member tools

  • easy8_project_members_list
  • easy8_project_members_add
  • easy8_project_members_update

Project version tools

  • easy8_project_versions_list
  • easy8_project_versions_get
  • easy8_project_versions_create
  • easy8_project_versions_update

Project issue category tools

  • easy8_project_issue_categories_list
  • easy8_project_issue_categories_create
  • easy8_project_issue_categories_update

Metadata and issue workflow tools

  • easy8_issue_statuses_list
  • easy8_issue_priorities_list
  • easy8_trackers_list
  • easy8_time_entry_activities_list
  • easy8_custom_fields_list
  • easy8_issues_transition_options
  • easy8_issues_comments_create
  • easy8_issue_attachments_list
  • easy8_issue_attachments_upload
  • easy8_issue_attachments_read
  • easy8_issue_relations_list
  • easy8_issue_relations_create

easy8_time_entry_activities_list

Lists time entry activities allowed for a project or issue context.

Use it before easy8_time_entries_create when the client does not already know the correct activity_id. This is especially important when correcting or splitting wrongly logged time into multiple entries on different projects, because each project can allow a different set of time entry activities.

Arguments:

  • project_id - project context for activity lookup
  • issue_id - issue context for activity lookup; the issue project is used
  • active - when omitted, only active activities are returned
  • limit - maximum number of activities
  • offset - pagination offset

When both issue_id and project_id are provided, the project must match the issue project. The response includes time_entry_activities, project_id, issue_id when an issue was used, and default_activity_id when Easy8 can resolve one.

Time entry tools

  • easy8_time_entries_list
  • easy8_time_entries_get
  • easy8_time_entries_create
  • easy8_time_entries_update

easy8_time_entries_create

Creates a time entry using Easy8 safe attributes and permissions.

Required runtime context:

  • provide either issue_id or project_id
  • provide hours and spent_on
  • provide activity_id unless Easy8 can resolve a default or fixed issue activity

Recommended client flow:

  1. Resolve the target issue or project.
  2. Call easy8_time_entry_activities_list with that issue_id or project_id.
  3. Use one returned time_entry_activities[].id as activity_id in easy8_time_entries_create.

If activity_id is missing and Easy8 cannot resolve a default, the tool returns a tool-level error that tells the client to call easy8_time_entry_activities_list and includes visible candidate activity IDs.