# MCP Client Portal

[![npm version](https://badge.fury.io/js/@artik0din/mcp-client-portal.svg)](https://www.npmjs.com/package/@artik0din/mcp-client-portal)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)

A lightweight [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for client relationship management (CRM). Perfect for freelancers, small businesses, and consultants who need simple yet effective client tracking.

## 🚀 Features

- **👥 Client Management** - Add, update, and organize client information
- **🔍 Advanced Search** - Find clients by name, company, email, or tags
- **📝 Notes & Interactions** - Track meetings, calls, emails, and conversations
- **🏷️ Tagging System** - Organize clients with custom tags
- **📊 Status Tracking** - Monitor client status (active, prospect, churned)
- **💾 Local Storage** - Simple JSON-based storage, no database required
- **🔒 Privacy-First** - All data stays on your machine
- **⚡ Zero Configuration** - Works out of the box

## 📦 Quick Start

### Install and Run

```bash
# Install globally
npm install -g @artik0din/mcp-client-portal

# Or run directly with npx
npx @artik0din/mcp-client-portal
```

### First Client

```bash
# Add your first client
add_client name="John Doe" email="john@example.com" company="Acme Corp" status="prospect" tags=["enterprise", "priority"]

# List all clients
list_clients

# Search for a client
search_clients query="john"
```

## 🛠️ MCP Client Setup

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "client-portal": {
      "command": "npx",
      "args": ["@artik0din/mcp-client-portal"]
    }
  }
}
```

### Other MCP Clients

The server communicates via stdio and follows the MCP protocol. Configure according to your client's requirements.

## 📋 Available Tools

### 👥 Client Management

| Tool | Description | Parameters |
|------|-------------|------------|
| `add_client` | Add new client | `name`, `email`, `company?`, `phone?`, `address?`, `status?`, `tags?` |
| `list_clients` | List all clients | `status?`, `tag?`, `limit?` |
| `get_client` | Get full client details | `client_id` |
| `search_clients` | Search clients | `query` |
| `update_client` | Update client info | `client_id`, `name?`, `email?`, `company?`, `phone?`, `address?`, `status?`, `tags?` |

### 📝 Notes & Interactions

| Tool | Description | Parameters |
|------|-------------|------------|
| `add_client_note` | Add note or interaction | `client_id`, `content`, `type?`, `subject?`, `date?`, `author?` |
| `list_client_interactions` | List interaction history | `client_id`, `type?`, `limit?` |

## 💡 Usage Examples

### Client Management

```bash
# Add a new client
add_client name="Sarah Johnson" email="sarah@techstart.io" company="TechStart Inc" phone="+1-555-0123" status="active" tags=["startup", "tech"]

# List active clients only
list_clients status="active"

# List clients with a specific tag
list_clients tag="enterprise"

# Update client status
update_client client_id="123-abc" status="churned"

# Search clients by company
search_clients query="TechStart"
```

### Notes & Interactions

```bash
# Add a simple note
add_client_note client_id="123-abc" content="Discussed Q4 requirements. Very interested in enterprise plan."

# Log a phone call
add_client_note client_id="123-abc" type="call" subject="Q4 Planning Call" content="45-minute call about scaling infrastructure. Next steps: send proposal by Friday." author="John Smith"

# Log an email interaction
add_client_note client_id="123-abc" type="email" subject="Proposal Follow-up" content="Sent detailed proposal. Waiting for feedback from technical team."

# Add a meeting with custom date
add_client_note client_id="123-abc" type="meeting" subject="Contract Negotiation" content="Discussed terms and pricing. Agreed on 10% discount for annual plan." date="2024-01-15T14:30:00Z"

# List all interactions for a client
list_client_interactions client_id="123-abc"

# List only phone calls
list_client_interactions client_id="123-abc" type="call"
```

### Advanced Workflows

```bash
# Get complete client profile
get_client client_id="123-abc"

# Find all prospects that need follow-up
list_clients status="prospect"

# Track high-value clients
list_clients tag="enterprise"

# Search across all fields
search_clients query="startup"
```

## 🏷️ Client Status Types

| Status | Description | Use Case |
|--------|-------------|----------|
| `prospect` | Potential client | Leads, initial contacts |
| `active` | Current client | Ongoing projects, contracts |
| `inactive` | Dormant client | Past clients, seasonal |
| `churned` | Lost client | Cancelled, competitors |

## 📝 Interaction Types

| Type | Description | Use Case |
|------|-------------|----------|
| `note` | General note | Internal observations, reminders |
| `email` | Email exchange | Email conversations, proposals |
| `call` | Phone/video call | Sales calls, check-ins |
| `meeting` | In-person/online meeting | Presentations, negotiations |
| `chat` | Instant messaging | Quick questions, Slack/Teams |
| `other` | Custom interaction | Social media, events, other |

## 💾 Data Storage

- **Local Storage**: Data stored in `~/.mcp-client-portal/clients.json`
- **JSON Format**: Human-readable and easily portable
- **No Database**: Zero setup complexity
- **Backup Ready**: Simply copy the JSON file
- **Privacy First**: No cloud dependencies

### Data Structure

```json
{
  "id": "unique-client-id",
  "name": "Client Name",
  "company": "Company Inc",
  "email": "client@company.com",
  "phone": "+1-555-0123",
  "status": "active",
  "tags": ["enterprise", "priority"],
  "notes": [
    {
      "id": "note-id",
      "content": "Note content",
      "author": "Your Name",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "interactions": [
    {
      "id": "interaction-id",
      "type": "call",
      "subject": "Q4 Planning",
      "summary": "Discussed requirements...",
      "date": "2024-01-15T14:00:00Z",
      "createdAt": "2024-01-15T14:05:00Z"
    }
  ]
}
```

## 🔧 Migration & Integration

### From Other CRMs

1. Export your data to CSV/JSON
2. Transform to match the client structure
3. Import by adding clients via the MCP tools
4. Bulk import scripts available in the repository

### To Database Systems

When you outgrow JSON storage:

1. Export data: `cp ~/.mcp-client-portal/clients.json backup.json`
2. Transform data for your target database
3. Update storage.ts to use database instead of JSON
4. Maintains same MCP interface

## 🏗️ Development

```bash
# Clone and setup
git clone https://github.com/artik0din/mcp-client-portal.git
cd mcp-client-portal
npm install

# Development mode
npm run dev

# Build for production
npm run build
```

## 📄 License

MIT © 2026 Kevin Valfin

## 🤝 Contributing

Contributions welcome! Please read the contributing guidelines and submit PRs to the main branch.

Feature requests:
- Custom fields
- Email integration
- Calendar sync
- Export/import tools
- Dashboard views

## 🐛 Issues

Found a bug? Please file an issue on [GitHub](https://github.com/artik0din/mcp-client-portal/issues) with:
- Node.js version
- Operating system
- Steps to reproduce
- Expected vs actual behavior

## 🔗 Links

- [Model Context Protocol](https://modelcontextprotocol.io)
- [Claude Desktop](https://claude.ai/desktop)
- [MCP Servers Registry](https://github.com/modelcontextprotocol/servers)