Skip to content

Add missing contact import export tools#95

Merged
IgorDobryn merged 5 commits into
mainfrom
add-missing-contact-import-export-tools
May 27, 2026
Merged

Add missing contact import export tools#95
IgorDobryn merged 5 commits into
mainfrom
add-missing-contact-import-export-tools

Conversation

@IgorDobryn

@IgorDobryn IgorDobryn commented May 20, 2026

Copy link
Copy Markdown
Contributor

Motivation

Changes

  • create-contact-import — bulk-import contacts (returns an import job)
  • get-contact-import — get import job status + created/updated/over-limit counts
  • create-contact-export — export contacts matching AND-combined filters (returns an export job)
  • get-contact-export — get export job status; url is populated when finished

Summary by CodeRabbit

  • New Features

    • Added contact import (bulk uploads) with job status polling.
    • Added contact export (filter-based exports) with job polling and CSV download URL when ready.
  • Documentation

    • Documented import payload shape and export filter structure, including operator/value behavior.
  • Tests

    • Added test coverage for create/get contact import and export workflows.

Review Change Stack

@coderabbitai

coderabbitai Bot commented May 20, 2026

Copy link
Copy Markdown

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ea932ffb-4824-4bba-8fd3-208bfd93a2da

📥 Commits

Reviewing files that changed from the base of the PR and between dac605e and ddd9424.

📒 Files selected for processing (3)
  • src/tools/contactExports/__tests__/createContactExport.test.ts
  • src/tools/contactExports/schemas/createContactExport.ts
  • src/types/mailtrap.ts
🚧 Files skipped from review as they are similar to previous changes (3)
  • src/tools/contactExports/schemas/createContactExport.ts
  • src/tools/contactExports/tests/createContactExport.test.ts
  • src/types/mailtrap.ts

📝 Walkthrough

Walkthrough

Adds contact import and export MCP tools: types, JSON schemas, create/get handlers, Jest tests, server registration of four tools, and README/CLAUDE docs describing payloads and polling/download behavior.

Changes

Contact Import/Export Feature Addition

Layer / File(s) Summary
Type definitions for contact import/export
src/types/mailtrap.ts
Mailtrap TypeScript types define request/response shapes for contact import and export operations, including status enums, filter definitions, and item structures.
Contact import: schemas, handlers, tests
src/tools/contactImports/schemas/*, src/tools/contactImports/*.ts, src/tools/contactImports/__tests__/*
Contact import implementation includes JSON schema validation for bulk contact payloads (contacts with email, optional fields, include/exclude list IDs), async create/get handlers that call the Mailtrap client, barrel export, and Jest tests for success and error paths.
Contact export: schemas, handlers, tests
src/tools/contactExports/schemas/*, src/tools/contactExports/*.ts, src/tools/contactExports/__tests__/*
Contact export implementation includes JSON schema validation for filters (name, operator, conditional value), async create/get handlers that call the Mailtrap client, barrel export, and Jest tests covering finished/started/error states.
Server tool registration and wiring
src/server.ts
MCP server imports and registers the four new contact import/export tools with handlers and input schemas, annotating destructive operations.
User documentation
CLAUDE.md, README.md
Adds documentation for create-contact-import, get-contact-import, create-contact-export, and get-contact-export including payload shapes and job polling/download behavior.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

  • mailtrap/mailtrap-mcp#68: Introduced or modified usage of requireClient, which these new handlers call for "contact imports" / "contact exports".

Suggested reviewers

  • VladimirTaytor
  • piobeny
  • leonid-shevtsov

Poem

🐰 I hopped through types and tests with care,
Four tools now ready to import and share.
Filters, contacts, schemas in a row,
Job polls hum until the CSVs show.
A cheerful rabbit says: "Ship it — let's go!"

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name Status Explanation Resolution
Description check ⚠️ Warning The PR description includes a Changes section documenting the four tools added, but the Motivation section is empty and required sections like 'How to test' and 'Images and GIFs' are missing. Add content to the Motivation section explaining why these tools were needed, and include the 'How to test' section with test steps and checkboxes.
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title 'Add missing contact import export tools' clearly summarizes the main changeset, which adds four new contact import/export tool handlers and their supporting infrastructure.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch add-missing-contact-import-export-tools

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@IgorDobryn IgorDobryn requested review from DagonWat and Rabsztok May 20, 2026 09:09
@IgorDobryn IgorDobryn marked this pull request as ready for review May 20, 2026 09:09
@IgorDobryn

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented May 26, 2026

Copy link
Copy Markdown
✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Base automatically changed from add-missing-contact-field-tools to main May 26, 2026 14:33

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 6

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@CLAUDE.md`:
- Line 161: Update the create-contact-import documentation entry to explicitly
state which field value types are accepted in the import payload for the fields
property of create-contact-import (e.g., text/string, number, boolean, date) or
state the restriction if only string/number are allowed; ensure the wording
aligns with README.md (and the contact field types referenced at "contact
fields" line) so both docs consistently describe whether boolean and date values
are supported in imports and, if not supported, explain that they must be
serialized (e.g., as ISO date strings or boolean strings).

In `@README.md`:
- Line 799: The README currently states `fields` accepts string or number but
lacks clarification; update the README line about `fields` to explicitly say
imported field values are limited to string | number per the createContactImport
schema and the ContactImportFieldValue type, or if you intend to accept
boolean/date values then update the createContactImport validation/schema and
the ContactImportFieldValue union to include boolean and date (and ensure
corresponding parsing/serialization in the import handler such as
createContactImport and any consumers of ContactImportFieldValue).

In `@src/tools/contactExports/schemas/createContactExport.ts`:
- Around line 16-34: The schema currently forces "value" to be required for
every filter, which breaks semantics for operators like "is_empty" and
"is_not_empty"; update the schema for the filter object (the block containing
"operator" and "value") to only require ["name","operator"] and add a JSON
Schema conditional (if/then/else or oneOf) that: when "operator" is "is_empty"
or "is_not_empty" ensures "value" is absent/optional, and otherwise enforces
"value" is present and conforms to the existing description/type; adjust the
required array and add an "if": {"properties":{"operator":{"const":"is_empty"}}}
/ "then" and a similar branch for "is_not_empty" (or a combined enum), with an
"else" that requires "value".

In `@src/tools/contactExports/schemas/getContactExport.ts`:
- Around line 4-6: The export_id schema currently uses type: "number" which
permits decimals and negatives; update the export_id property in
getContactExport.ts to require an integer ID and be positive by changing type to
"integer" (or adding an integer constraint) and adding a minimum: 1 constraint
(e.g., type: "integer", minimum: 1) so only positive whole IDs are allowed.

In `@src/tools/contactImports/schemas/getContactImport.ts`:
- Around line 4-10: The schema's import_id currently uses type: "number" which
permits floats and negatives; update the getContactImport schema's import_id
definition to require an integer >= 1 by changing the type to "integer" and
adding "minimum": 1 (retain description, required array, and
additionalProperties: false) so only positive whole IDs validate.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 26914b66-c0d3-454a-a46b-4db283c11ea4

📥 Commits

Reviewing files that changed from the base of the PR and between 403ba00 and dac605e.

📒 Files selected for processing (18)
  • CLAUDE.md
  • README.md
  • src/server.ts
  • src/tools/contactExports/__tests__/createContactExport.test.ts
  • src/tools/contactExports/__tests__/getContactExport.test.ts
  • src/tools/contactExports/createContactExport.ts
  • src/tools/contactExports/getContactExport.ts
  • src/tools/contactExports/index.ts
  • src/tools/contactExports/schemas/createContactExport.ts
  • src/tools/contactExports/schemas/getContactExport.ts
  • src/tools/contactImports/__tests__/createContactImport.test.ts
  • src/tools/contactImports/__tests__/getContactImport.test.ts
  • src/tools/contactImports/createContactImport.ts
  • src/tools/contactImports/getContactImport.ts
  • src/tools/contactImports/index.ts
  • src/tools/contactImports/schemas/createContactImport.ts
  • src/tools/contactImports/schemas/getContactImport.ts
  • src/types/mailtrap.ts

Comment thread CLAUDE.md
Comment thread README.md
Comment thread src/tools/contactExports/schemas/createContactExport.ts
Comment thread src/tools/contactExports/schemas/getContactExport.ts
Comment thread src/tools/contactImports/schemas/createContactImport.ts
Comment thread src/tools/contactImports/schemas/getContactImport.ts
@IgorDobryn IgorDobryn merged commit 79b4883 into main May 27, 2026
2 checks passed
@IgorDobryn IgorDobryn deleted the add-missing-contact-import-export-tools branch May 27, 2026 06:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants