io.github.g-digital-by-Garrigues/gocertius

Creates a new case file — the top-level container for all related operations (evidence, notifications, dossiers, chats). Call this first before any other operation. Generate a UUID v4 for `id`. For `useCaseId`, use the general GoCertius use case: `063a016a-1d62-4b7b-a24f-7cf4d1d289bf` unless a specific use case is required. Returns caseFileId needed for all subsequent calls.

Retrieves details of a specific case file. Requires: caseFileId. Use to verify a case file exists before creating evidence groups, dossiers, or notifications.

Lists all case files in your GoCertius account. Pass userId (from session_login or session_info) to scope results to your account. Returns paginated list with IDs, names, and status.

Creates a certificate of a range of messages from a certified chat. Requires: chat_create → chatId, personal caseFileId, chat_get → registeredAt, and messages already present in the Telegram channel. Generate a UUID v4 for `id`. Do not use createdAt as a substitute for registeredAt; if registeredAt is missing, the chat is not ready to certify. Specify chatMessagesFrom and chatMessagesTo as ISO timestamps (chatMessagesFrom must be AFTER registeredAt). ASYNC: poll chat_certificate_get until status === CERTIFIED.

Retrieves a certified chat certificate including its status, message range, and PDF download URL. Prerequisites: the certificate must have been created with chat_certificate_create. Returns documentUrl when status is CERTIFIED. Example: chat_certificate_get({ caseFileId: '...', chatId: '...', id: '...' })

Creates a certified chat channel (Telegram). IMPORTANT: Chats can only be created in the user's personal case file (created automatically when the GoCertius account was opened). Do not use a manually created case file — use session_info → case_file_list to find the personal case file (oldest createdAt, owned by the user). Generate a UUID v4 for `id`. Set service to Telegram. Returns immediately and the chat may start in status `creating`; call chat_get and wait until it is registered/active before requesting the invitation URL or certificates.

Retrieves details of a certified chat. Requires: personal caseFileId and chat_create → chatId. Returns status, participants, and registeredAt timestamp. After chat_create, poll chat_get until status is active/registered and registeredAt is present; createdAt is not enough for certificate creation.

Returns the Telegram invitation URL for a certified chat. Requires: chat_create → chatId and the personal caseFileId. Do not call while chat_get still shows status `creating`; wait until the chat is registered/active, otherwise the API can answer Chat not found. Share the returned invitationUrl with participants so they can join the certified channel.

Certifies a DRAFT dossier, locking in all its associated evidence groups. The dossier must be in DRAFT status. After certification it transitions to CERTIFIED and a tamper-evident PDF is generated. Prerequisites: the dossier must exist (dossier_create) and have evidence groups linked. Use dossier_group_certify instead if you want to create + certify in one step from a single evidence group. Example: dossier_certify({ caseFileId: '...', dossierId: '...' })

Creates a dossier to aggregate certified evidence groups into a single tamper-evident PDF. Requires: case_file_create → caseFileId. Evidence groups must be in CLOSED status before linking. Generate a UUID v4 string for `id`. Returns dossierId. After creation, link evidence with dossier_evidence_link, then certify with dossier_certify.

Deletes a dossier. Available in DRAFT status (to discard before certification) or in CERTIFIED status (to permanently remove the certified dossier). Irreversible. Requires: caseFileId and dossierId.

Returns the download URL for the certified dossier PDF. Requires: dossier_certify (CERTIFIED status), caseFileId, dossierId.

Removes an evidence item from a dossier. Only available while dossier is in DRAFT status. Requires: caseFileId, dossierId, evidenceId.

Retrieves details of a specific evidence item linked to a dossier. Requires: caseFileId, dossierId, evidenceId.

Links specific evidence items to a DRAFT dossier. Call once per case file containing evidences to link. After linking all evidences, call dossier_certify to finalize. For a single-group dossier, use dossier_group_certify instead (one step). Example: dossier_evidence_link({ caseFileId: '...', dossierId: '...', caseFileToLinkId: '...', ids: ['ev-uuid-1', 'ev-uuid-2'] })

Lists all evidence items linked to a dossier. Requires: caseFileId and dossierId.

Lists evidence items that are available to be linked to a dossier (CLOSED groups not yet linked). Requires: caseFileId and dossierId.

Retrieves the full details of a specific dossier including status, linked evidence, and download URLs. Use to check current state or get certificate download URLs after CERTIFIED. Requires: caseFileId and dossierId.

Creates AND certifies a dossier from a single sealed evidence group in one call (express path). Requires: evidence_seal (CLOSED status), case_file_create → caseFileId, evidence_group_create → evidenceGroupId. Generate a UUID v4 string for `id`. Use when you have exactly one sealed evidence group and don't need multi-group aggregation. Returns dossierId immediately with CERTIFYING status → poll until CERTIFIED.

Lists all dossiers in a case file with their status and metadata. Use to find an existing dossierId or monitor certification progress. Requires: caseFileId. Returns paginated list with IDs, names, status, and creation dates.

Returns the download URL for the full dossier package (PDF + evidence files). Requires: dossier_certify (CERTIFIED status), caseFileId, dossierId.

Returns an HTML preview URL of a dossier before certification. Requires: caseFileId and dossierId.

Lists available dossier templates. No prerequisites. Returns template IDs and their translations per language. Use the returned id as dossierTemplateId in dossier_create.

Updates the metadata of an existing dossier (name, template fields, expiry). Requires: dossier_create → dossierId, caseFileId. Only available while dossier is in DRAFT status.

Updates the visibility (public/private) of a certified dossier. Requires: dossier_certify (CERTIFIED status), caseFileId, dossierId.

Registers a NEW evidence record inside an evidence group. Requires: evidence_group_create → evidenceGroupId, case_file_create → caseFileId. Generate a UUID v4 for `id`. Compute the SHA-256 hex hash of the file BEFORE calling. Normal INTERNAL flow: call evidence_create with custodyType INTERNAL and NO fileUrl; the API returns uploadFileUrl, a presigned S3 URL. You MUST PUT the exact file bytes to uploadFileUrl, then verify with evidence_get/evidence_list, and ONLY THEN call evidence_seal. Do not seal an evidence group until every INTERNAL evidence file has been uploaded. Convenience flow: if you pass `fileUrl` (public HTTPS, no redirects, under 1 GiB), this tool downloads that URL and PUTs the bytes to uploadFileUrl for you. EXTERNAL flow: use custodyType EXTERNAL only when you intentionally register hash-only evidence; still generate a fresh UUID for each evidence. If an INTERNAL evidence creation/upload failed and you want to retry as EXTERNAL, create a NEW evidence id; do not reuse an id whose outcome is unknown. WARNING: the API sometimes returns {code:'EvidenceCreateError'} even when the evidence was successfully persisted — always verify with evidence_list before retrying.

Retrieves a specific evidence record. Requires: evidence_create → evidenceId, evidence_group_create → evidenceGroupId, case_file_create → caseFileId. Returns status (COMPLETED|IN_PROCESS|ERROR), hash, and tspTimestamp when certified.

Creates an evidence group inside a case file. Requires: case_file_create → caseFileId. Generate a UUID v4 for `id`. Set evidenceType to FILE, PHOTO, VIDEO, or WEB_PLUGIN. Returns evidenceGroupId. One group can contain multiple evidence records.

Lists all evidence groups in a case file with their current status (OPEN, CLOSING, CLOSED). Use to find an existing group or check which groups are ready for sealing. Requires: caseFileId.

Lists all evidence records in a specific evidence group. Use to review uploaded documents before sealing the group, or to find a specific evidenceId. Requires: caseFileId and evidenceGroupId. Returns paginated list with IDs, titles, status, and timestamps.

Seal and certify an evidence group. Closes the group to new additions and triggers async timestamping. Returns immediately — the group transitions OPEN → CLOSING → CLOSED. Poll evidence_group_list until status is CLOSED before linking to a dossier.

Uploads a local file as evidence in one step: computes its SHA-256, registers the evidence record (custodyType INTERNAL = GoCertius stores the file), and uploads the bytes to S3 — no manual hashing or PUT needed. Internally this follows the required GoCertius sequence: create INTERNAL evidence → receive uploadFileUrl (presigned S3 URL) → PUT file bytes → return uploaded:true. Requires: case_file_create → caseFileId, evidence_group_create → evidenceGroupId. Provide EXACTLY ONE of `filePath` (absolute local path, stdio/local mode only) or `contentBase64` (base64-encoded file content, ~10 MB max). Use evidence_upload when the file is on the local machine; use evidence_create when you already have the SHA-256 hash, need to inspect/use uploadFileUrl manually, or have a public fileUrl. After this tool succeeds, verify with evidence_get/evidence_list and only then call evidence_seal. If this tool fails before returning an evidence id, check evidence_list before retrying; if retrying manually, use evidence_create with a fresh UUID. Local files must be under 1 GiB.

Creates or retrieves a PDF certificate for a specific notification receiver. Requires notification_request_send and notification_receiver_add. Generate a UUID v4 for `id` the first time and reuse that id when polling. This tool is idempotent: it first lists existing certificates for the receiver and, if `id` already exists, returns it instead of creating it again. If the certificate status is CERTIFIED, the response includes documentUrl when available. If it is CERTIFYING, poll this same tool with the same id.

Performs the notification_document_add operation. Review the API documentation for full field details.

Adds a recipient to a notification request. Requires: notification_request_create → notificationRequestId, case_file_create → caseFileId. The `id` can be a UUID v4 or custom string (e.g. your internal user ID). Returns receiverId — save it for notification_certificate_get. Add all receivers before calling notification_request_send.

Creates a certified notification request. Requires: case_file_create → caseFileId. Generate a UUID v4 for `id`. Set language to en_GB or es_ES. Returns notificationRequestId. Add at least one receiver with notification_receiver_add before sending. IMPORTANT: The `content` field must be valid HTML — plain text without HTML tags will not render on the recipient landing page. Only the following HTML formats are supported: paragraphs (<p>), bold (<strong>), italic (<em>), unordered lists (<ul><li>), ordered lists (<ol><li>). Do not use other HTML tags or CSS. Avoid special typographic characters (em dashes, smart quotes) in `subject`; use standard ASCII equivalents (hyphen, straight quotes) instead.

Trigger delivery of a certified notification to all added recipients. Returns immediately — delivery is async. Poll notification_request_status until status is DELIVERED before retrieving certificates.

Checks the delivery status of a certified notification. Requires: notificationRequestId, caseFileId. Returns status (CREATING|DRAFT|IN_PROCESS|SENT|PARTIALLY_READ|FULLY_READ|PARTIALLY_ANSWERED|FULLY_ANSWERED). Poll until status is SENT or beyond. Do not call notification_certificate_get while status is CREATING, DRAFT, or IN_PROCESS.

Returns the authenticated user's own profile. Works on EVERY auth flow (user key or email/password) because it identifies the caller from the session token alone — no email needed. Its `id` field IS your userId (UUID): the value required by case_file_list and every /users/{userId}/... operation. Prefer this over session_info when you need the userId, and it is the ONLY way to obtain it on a user-key deployment (MCP_AUTH_USER_KEY), where no email is configured. Also returns companyId (needed to subscribe to the notifications SSE stream) and defaultCaseFileId (the personal case file — the one chats must use). No parameters.

Returns the authenticated user's session info including userId and session type (Password or UserKey). Use this to retrieve the userId (UUID) required by case_file_list and other user-scoped operations. Works on both auth flows: with a user key (MCP_AUTH_USER_KEY) it resolves identity via profile_get (GET /profile → `id`), since no email is configured; with MCP_AUTH_EMAIL it queries /session-info. profile_get is the canonical way to obtain the userId and returns more (companyId, defaultCaseFileId). Prerequisites: a valid session (call session_login first if needed). Example: session_info() → { userId: '...uuid...', type: 'Password' }

Authenticate with GoCertius. Credentials are read from the server environment: if MCP_AUTH_USER_KEY is set it is exchanged for a session token; otherwise MCP_AUTH_EMAIL + MCP_AUTH_PASSWORD are used. The server manages authentication automatically — call this only to force a re-login or after a 401.