Dex MCP Server

v1.0.0 is now released!

• See RELEASE-NOTES.md and GitHub Releases for highlights and upgrade info.
• How to upgrade:
  1. Pull the latest code: git pull --rebase origin main
  2. Ensure your .env file is present and contains a valid DEX_API_KEY.
  3. Use the kill-dex-mcp-server.sh script before agent startup if needed.
  4. See copilot-instructions.md for agent/CLI usage and best practices.

A Model Context Protocol (MCP) server that provides AI agents with comprehensive contact relationship management capabilities through the Dex API.

Features

🚀 Contact Management

• Create, Read, Update, Delete contacts with full details
• Search contacts by name, email, or company
• Comprehensive contact fields: name, company, job title, description, emails, phone numbers

📝 Note Management

• Contact-linked notes stored as timeline items
• Create, update, delete notes for any contact
• Search notes by content across all contacts
• Pagination support for large note collections

⏰ Reminder Management

• Set reminders linked to specific contacts
• Complete, update, delete reminders as needed
• Search reminders by text content
• Recurrence support for recurring follow-ups
• Due date tracking with proper date formatting

Installation

Prerequisites

• Node.js 18 or later
• Dex API account and API key

Setup

1. Clone this repository:

git clone https://github.com/alpabon73/dex-mcp-server.git
cd dex-mcp-server

2. Install dependencies:

npm install

3. Configure your Dex API key in src/index.ts:

const API_KEY = 'your-dex-api-key-here';

4. Build the server:

npm run build

Environment Variables

This project requires a Dex API key. Never commit your real API key to a public repository.

1. Copy .env.example to .env:

   cp .env.example .env
   

2. Edit .env and set your real Dex API key:

   DEX_API_KEY=your-dex-api-key-here
   

3. The server will not start unless DEX_API_KEY is set in your environment or .env file.

.env is already in .gitignore and will never be committed.

Usage

Standalone Usage

npm start

With AnythingLLM

Add to your MCP server configuration:

{
  "servers": {
    "dex-mcp": {
      "command": "/usr/local/bin/node",
      "args": ["/path/to/dex-mcp-server/dist/index.js"],
      "env": {}
    }
  }
}

Available Tools

Contact Tools (6)

• get_contacts - Retrieve contacts with pagination
• get_contact_by_id - Get specific contact details
• search_contacts - Search by name/company/email
• create_contact - Add new contacts
• update_contact - Modify existing contacts
• delete_contact - Remove contacts

Note Tools (6)

• get_notes_by_contact - Get all notes for a contact
• get_all_notes - Retrieve all notes with pagination
• search_notes - Search notes by content
• create_note - Add notes to contacts
• update_note - Modify existing notes
• delete_note - Remove notes

Reminder Tools (6)

• get_reminders_by_contact - Get contact reminders
• get_all_reminders - Retrieve all reminders with pagination
• search_reminders - Search reminders by text
• create_reminder - Set new reminders
• update_reminder - Modify existing reminders
• complete_reminder - Mark reminders as done
• delete_reminder - Remove reminders

Allowed Meeting Types for Notes

When creating a note, you may specify the meeting type using either the display name or the Dex API enum value. The following table shows the accepted values:

| Display Name | Dex API Enum Value | |-------------------|---------------------| | Note | note | | Call | call | | Email | email | | Text/Messaging | text_messaging | | Linkedin | linkedin | | Skype/Teams | skype_teams | | Slack | slack | | Coffee | coffee | | Networking | networking | | Party/Social | party_social | | Other | other | | Meal | meal | | Meeting | meeting | | Custom | custom |

You may use any of the above display names (case-insensitive, spaces and slashes allowed) or the exact enum value. The system will automatically map your input to the correct Dex API value.

Example Use Cases

• "Add John Smith from TechCorp as a new contact"
• "Set a reminder to follow up with Sarah next week"
• "Search for all notes about the ABC project"
• "Update Mike's job title to Senior Engineer"
• "Show me all pending reminders for this month"
• "Create a note about today's meeting with the client"

Development

Scripts

• npm run build - Compile TypeScript
• npm run dev - Run with ts-node for development
• npm run watch - Watch mode compilation
• npm start - Run compiled server

Architecture

• TypeScript for type safety
• Zod for schema validation
• Axios for HTTP requests to Dex API
• MCP SDK for protocol implementation

API Integration

This server integrates with the Dex API using:

• GraphQL endpoint: https://api.getdex.com/v1/graphql
• Timeline items for note storage
• Reminders table with contact junction
• Proper pagination and search capabilities

Code Quality & CI

This project uses TypeScript for type safety and ESLint for code linting. All code is automatically checked for type errors and lint issues in CI (see .github/workflows/ci.yml).

• Run type checks locally:

  npm run build # or npx tsc --noEmit
  

• Run linter locally:

  npm run lint
  

All pull requests must pass CI checks before merging.

Issue & PR Templates

• Bug reports and feature requests use GitHub issue templates for consistency.
• All pull requests use a PR template to ensure quality and documentation.

Security & Secrets

• Never commit secrets or API keys. .env is gitignored and secrets are loaded from environment variables.
• If a secret is ever committed, follow the repo's history-scrubbing protocol (see scrub-git-history.sh).

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run npm run lint and npm run build to check code quality
6. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues related to:

• Dex API: Check Dex documentation
• MCP Protocol: See MCP specification
• This server: Open an issue in this repository

How to report issues or contribute

• Found a bug or have a feature request? Open an issue
• Want to contribute? See CONTRIBUTING.md for guidelines.
• Security concerns? See SECURITY.md for responsible disclosure.
• For release notes and upgrade info, see RELEASE-NOTES.md and CHANGELOG.md.