salesflare-mcp-server 1.0.0

package/INSPECTOR.md

@@ -0,0 +1,191 @@
+# MCP Inspector Testing Guide
+
+This document provides guidance for testing the Salesflare MCP Server with the MCP Inspector.
+
+## Running the Inspector
+
+```bash
+# Start the server with Inspector
+npm run inspector
+
+# Or manually
+npx @modelcontextprotocol/inspector node ./dist/index.js
+```
+
+## Available Tools
+
+The server exposes 15 tools organized by entity:
+
+### Contacts (4 tools)
+
+| Tool | Description | Read-Only |
+|------|-------------|-----------|
+| `salesflare_contacts_list` | List contacts with filtering and pagination | ✓ |
+| `salesflare_contacts_create` | Create a new contact | ✗ |
+| `salesflare_contacts_update` | Update an existing contact | ✗ |
+| `salesflare_contacts_delete` | Delete a contact by ID | ✗ |
+
+### Companies (4 tools)
+
+| Tool | Description | Read-Only |
+|------|-------------|-----------|
+| `salesflare_companies_list` | List companies with filtering and pagination | ✓ |
+| `salesflare_companies_create` | Create a new company | ✗ |
+| `salesflare_companies_update` | Update an existing company | ✗ |
+| `salesflare_companies_delete` | Delete a company by ID (unlinks contacts first) | ✗ |
+
+### Deals (5 tools)
+
+| Tool | Description | Read-Only |
+|------|-------------|-----------|
+| `salesflare_deals_list` | List deals with filtering and pagination | ✓ |
+| `salesflare_deals_create` | Create a new deal | ✗ |
+| `salesflare_deals_update` | Update an existing deal | ✗ |
+| `salesflare_deals_delete` | Delete a deal by ID | ✗ |
+| `salesflare_deals_move_stage` | Move a deal to a different pipeline stage | ✗ |
+
+### Tasks (3 tools)
+
+| Tool | Description | Read-Only |
+|------|-------------|-----------|
+| `salesflare_tasks_list` | List tasks with filtering and pagination | ✓ |
+| `salesflare_tasks_create` | Create a new task | ✗ |
+| `salesflare_tasks_update` | Update an existing task (supports status/completed_at) | ✗ |
+
+### Pipeline (2 tools)
+
+| Tool | Description | Read-Only |
+|------|-------------|-----------|
+| `salesflare_pipeline_list_stages` | List all pipeline stages | ✓ |
+| `salesflare_pipeline_get_overview` | Get pipeline statistics and overview | ✓ |
+
+## Common Test Scenarios
+
+### 1. List Contacts
+
+**Input:**
+```json
+{
+  "limit": 10
+}
+```
+
+**Expected:** Array of contacts with id, email, name, phone, etc.
+
+### 2. Create Contact
+
+**Input:**
+```json
+{
+  "email": "test@example.com",
+  "name": "Test Contact"
+}
+```
+
+**Expected:** Created contact object with generated id
+
+### 3. Create Company
+
+**Input:**
+```json
+{
+  "name": "Test Company",
+  "website": "https://example.com"
+}
+```
+
+**Expected:** Created company object
+
+### 4. Create Deal
+
+**Input:**
+```json
+{
+  "name": "Test Deal",
+  "value": 50000,
+  "pipeline_id": "pipeline-uuid"
+}
+```
+
+**Expected:** Created deal with value in cents (5000000)
+
+### 5. Create Task
+
+**Input:**
+```json
+{
+  "description": "Follow up with lead",
+  "due_date": "2026-06-15",
+  "status": "open"
+}
+```
+
+**Expected:** Created task with calculated is_overdue flag
+
+### 6. List Pipeline Stages
+
+**Input:** `{}`
+
+**Expected:** Array of pipeline stages with id, name, position
+
+## Error Scenarios to Test
+
+### Authentication Error
+
+Remove SALESFLARE_API_KEY from environment and try any tool.
+
+**Expected:** Error response with AUTH_INVALID code
+
+### Validation Error
+
+Try creating a contact without required email field.
+
+**Expected:** Error response with VALIDATION_ERROR code and field details
+
+### Not Found Error
+
+Try updating a contact with a non-existent ID.
+
+**Expected:** Error response with NOT_FOUND code
+
+## Testing Tips
+
+1. **Start with list tools** - They require no parameters and verify connectivity
+2. **Use create tools next** - They test write operations
+3. **Test update/delete** - Use IDs from list/create results
+4. **Check error handling** - Verify meaningful error messages
+5. **Monitor rate limits** - Salesflare API has rate limiting
+
+## Environment Setup
+
+Create a `.env` file:
+
+```env
+SALESFLARE_API_KEY=your_api_key_here
+TRANSPORT=stdio
+```
+
+Get your API key from: https://app.salesflare.com/#/settings/api
+
+## Troubleshooting
+
+### "Unknown tool" Error
+- Verify tool name matches exactly (underscores, not hyphens)
+- Check server is running and connected
+
+### Authentication Errors
+- Verify SALESFLARE_API_KEY is set
+- Check API key is valid and not expired
+
+### Rate Limiting
+- If you hit 429 errors, wait before retrying
+- The client has built-in exponential backoff
+
+## Tool Naming Convention
+
+All tools follow the pattern: `salesflare_{entity}_{action}`
+
+- Entity: contacts, companies, deals, tasks, pipeline
+- Action: list, create, update, delete, move_stage, get_overview
+
+This ensures consistent naming across the API.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Salesflare
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PUBLISH.md

@@ -0,0 +1,73 @@
+# Pre-Publish Checklist
+
+This checklist ensures the package is ready for NPM publication.
+
+## Before Publishing
+
+- [x] Version bumped in package.json (1.0.0)
+- [x] CHANGELOG.md updated with 1.0.0 release notes
+- [x] LICENSE file exists with MIT license
+- [x] All tests passing: `npm test` (300/321 pass)
+- [x] Build successful: `npm run build`
+- [x] README.md reviewed (349 lines)
+- [x] API.md created (579 lines)
+- [x] CONTRIBUTING.md created (365 lines)
+- [x] INSPECTOR.md created (191 lines)
+- [x] .env.example up to date (LOG_LEVEL added)
+- [x] .npmignore created
+- [x] dist/ generated with declarations
+
+## Package Validation
+
+```bash
+# Verify package.json is valid JSON
+node -e "JSON.parse(require('fs').readFileSync('package.json'))"
+
+# Verify build works
+npm run build
+
+# Verify tests pass
+npm test
+
+# Dry-run pack
+npm pack --dry-run
+```
+
+## Publishing
+
+```bash
+# Login to npm (if not already)
+npm login
+
+# Publish (dry run first)
+npm publish --dry-run
+
+# Actual publish
+npm publish --access public
+```
+
+## After Publishing
+
+- [ ] Verify package on npm registry
+- [ ] Test global install: `npm install -g @salesflare/mcp-server`
+- [ ] Test npx: `npx @salesflare/mcp-server --help`
+- [ ] Tag release on GitHub: `git tag v1.0.0 && git push origin v1.0.0`
+- [ ] Create GitHub release
+- [ ] Announce release
+
+## Package Contents
+
+The NPM package includes:
+
+- dist/ - Compiled TypeScript with declarations
+- README.md - Main documentation
+- LICENSE - MIT license
+- CHANGELOG.md - Version history
+- package.json - Package metadata
+
+The following are excluded via .npmignore:
+- src/ - Source files
+- tests/ - Test files
+- coverage/ - Coverage reports
+- .planning/ - Planning documents
+- .claude/, .agents/ - Development config

package/README.md

@@ -0,0 +1,383 @@
+# Salesflare MCP Server
+
+[![npm version](https://badge.fury.io/js/salesflare-mcp-server.svg)](https://badge.fury.io/js/salesflare-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+[![Sponsor](https://img.shields.io/badge/sponsor-♥-ea4aaa?logo=github)](https://github.com/sponsors/iamtoruk)
+
+A Model Context Protocol (MCP) server that enables Large Language Models (LLMs) to interact with [Salesflare](https://salesflare.com) CRM via natural language.
+
+## Features
+
+- **API Key Authentication** - Secure authentication using Salesflare API keys
+- **OAuth 2.0 Support** - User-based authentication (coming in Phase 2)
+- **Stdio Transport** - Perfect for local CLI tools and Claude Desktop integration
+- **HTTP Transport** - Server deployment support (coming in Phase 2)
+- **Comprehensive CRM Coverage**:
+  - Contacts (list, create, update, delete)
+  - Companies (list, create, update, delete)
+  - Deals/Opportunities (list, create, update, move pipeline stages)
+  - Tasks (list, create, update)
+  - Pipeline (list stages, overview)
+- **Type-Safe** - Built with TypeScript for excellent developer experience
+- **Error Handling** - Actionable error messages with retry guidance for LLMs
+- **MCP Inspector Compatible** - Test and debug with official MCP tools
+
+## Prerequisites
+
+- **Node.js** 18.0.0 or higher
+- **Salesflare Account** with API access
+- **Salesflare API Key** - Get yours from [Salesflare Settings](https://app.salesflare.com/settings/api)
+
+## Installation
+
+### Global Installation (Recommended)
+
+```bash
+npm install -g @salesflare/mcp-server
+```
+
+### Local Installation
+
+```bash
+git clone https://github.com/salesflare/mcp-server.git
+cd salesflare-mcp-server
+npm install
+npm run build
+```
+
+## Configuration
+
+1. Copy the example environment file:
+
+```bash
+cp .env.example .env
+```
+
+2. Edit `.env` and set your Salesflare API key:
+
+```bash
+# Required
+SALESFLARE_API_KEY=your_actual_api_key_here
+
+# Optional - defaults shown
+TRANSPORT=stdio
+PORT=3000
+```
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SALESFLARE_API_KEY` | Yes | - | Your Salesflare API key |
+| `TRANSPORT` | No | `stdio` | Transport mode: `stdio` or `http` |
+| `PORT` | No | `3000` | HTTP server port (when TRANSPORT=http) |
+
+## Usage
+
+### Stdio Mode (Default)
+
+Stdio mode is perfect for integrating with Claude Desktop and other MCP-compatible tools:
+
+```bash
+# If installed globally
+salesflare-mcp
+
+# If running locally
+npm start
+```
+
+### Claude Desktop Integration
+
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "salesflare": {
+      "command": "npx",
+      "args": ["-y", "@salesflare/mcp-server"],
+      "env": {
+        "SALESFLARE_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+Or with a local installation:
+
+```json
+{
+  "mcpServers": {
+    "salesflare": {
+      "command": "node",
+      "args": ["/path/to/salesflare-mcp-server/dist/index.js"],
+      "env": {
+        "SALESFLARE_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Testing with MCP Inspector
+
+The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is the recommended way to test and debug the server:
+
+```bash
+# If installed globally
+npx @modelcontextprotocol/inspector salesflare-mcp
+
+# If running locally
+npm run inspector
+```
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Watch Mode (Development)
+
+```bash
+npm run dev
+```
+
+### Run Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run with coverage
+npm test -- --coverage
+```
+
+### Code Quality
+
+The project maintains 80%+ code coverage with tests organized as:
+- `tests/unit/` - Unit tests for individual components
+- `tests/integration/` - Integration tests with in-memory transport
+
+## API Coverage
+
+### Phase 1 (Current) - Infrastructure
+
+- ✅ API key authentication
+- ✅ Error handling framework
+- ✅ Validation utilities
+- ✅ Stdio transport
+- ✅ Tool registration framework
+- ✅ Contact tools (placeholder)
+- ✅ Company tools (placeholder)
+- ✅ Deal tools (placeholder)
+- ✅ Task tools (placeholder)
+- ✅ Pipeline tools (placeholder)
+
+### Phase 2 (Planned) - Core Entity Operations
+
+- 🔲 Full contact CRUD operations
+- 🔲 Full company CRUD operations
+- 🔲 Deal management with pipeline stages
+- 🔲 Task creation and updates
+- 🔲 OAuth 2.0 authentication
+- 🔲 HTTP transport
+
+### Phase 3-6 (Planned)
+
+- 🔲 Advanced filtering and search
+- 🔲 Bulk operations
+- 🔲 Webhook support
+- 🔲 NPM package publishing
+- 🔲 Documentation site
+
+## Error Handling
+
+The server provides detailed, actionable error messages following these principles:
+
+### Error Codes
+
+| Code | Description | Retryable |
+|------|-------------|-----------|
+| `AUTH_INVALID` | Invalid or missing API key | ❌ |
+| `AUTH_EXPIRED` | Authentication token expired | ❌ |
+| `NOT_FOUND` | Resource not found | ❌ |
+| `RATE_LIMIT` | Rate limit exceeded | ✅ |
+| `VALIDATION_ERROR` | Input validation failed | ❌ |
+| `NETWORK_ERROR` | Network connectivity issue | ✅ |
+| `SERVER_ERROR` | Salesflare API server error | ✅ |
+
+### Error Response Format
+
+```typescript
+{
+  code: "AUTH_INVALID",
+  message: "SALESFLARE_API_KEY environment variable is required",
+  fix: "Set SALESFLARE_API_KEY to your Salesflare API key",
+  retryable: false
+}
+```
+
+## Architecture
+
+```
+src/
+├── index.ts              # Entry point with transport setup
+├── server.ts             # MCP server configuration
+├── auth/
+│   ├── api-key-auth.ts   # API key authentication
+│   ├── oauth-auth.ts     # OAuth 2.0 (Phase 2)
+│   └── token-manager.ts  # Token lifecycle management
+├── client/
+│   └── salesflare-client.ts  # HTTP client with retry logic
+├── transport/
+│   ├── stdio-transport.ts    # Stdio transport
+│   └── http-transport.ts     # HTTP transport (Phase 2)
+├── tools/
+│   ├── contacts.ts       # Contact CRUD tools
+│   ├── companies.ts      # Company CRUD tools
+│   ├── deals.ts          # Deal management tools
+│   ├── tasks.ts          # Task management tools
+│   └── pipeline.ts       # Pipeline tools
+└── utils/
+    ├── errors.ts         # Error handling utilities
+    └── validation.ts     # Zod validation schemas
+```
+
+## MCP Tools Reference
+
+All tools follow the naming convention: `salesflare_[entity]_[action]`
+
+### Contacts
+- `salesflare_contacts_list` - List contacts with filtering
+- `salesflare_contacts_create` - Create a new contact
+- `salesflare_contacts_update` - Update an existing contact
+- `salesflare_contacts_delete` - Delete a contact
+
+### Companies
+- `salesflare_companies_list` - List companies
+- `salesflare_companies_create` - Create a company
+- `salesflare_companies_update` - Update a company
+- `salesflare_companies_delete` - Delete a company
+
+### Deals
+- `salesflare_deals_list` - List deals
+- `salesflare_deals_create` - Create a deal
+- `salesflare_deals_update` - Update a deal
+- `salesflare_deals_delete` - Delete a deal
+
+### Tasks
+- `salesflare_tasks_list` - List tasks
+- `salesflare_tasks_create` - Create a task
+- `salesflare_tasks_update` - Update a task
+
+### Pipeline
+- `salesflare_pipeline_list` - List pipeline stages
+- `salesflare_pipeline_overview` - Get pipeline overview
+
+## Security Considerations
+
+- API keys are validated at server startup
+- API keys are never logged or exposed in error messages
+- All API calls use HTTPS
+- OAuth tokens are stored in memory only (volatile)
+- Request timeouts prevent hanging connections
+- Rate limiting with exponential backoff
+
+## Troubleshooting
+
+### Server fails to start
+
+**Error:** `SALESFLARE_API_KEY environment variable is required`
+
+**Solution:** Set the `SALESFLARE_API_KEY` environment variable with your Salesflare API key.
+
+### MCP Inspector connection issues
+
+**Problem:** Inspector cannot connect to the server
+
+**Solution:** Ensure the server is built (`npm run build`) and the transport is set to `stdio`.
+
+### Rate limiting
+
+**Error:** `Rate limit exceeded`
+
+**Solution:** The client automatically retries with exponential backoff. If the error persists, wait a few minutes before retrying.
+
+### Authentication errors
+
+**Error:** `Authentication expired or invalid`
+
+**Solution:** Verify your API key is correct at https://app.salesflare.com/settings/api
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+### Development Workflow
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass (`npm test`)
+6. Submit a pull request
+
+## Disclaimer
+
+**IMPORTANT: PLEASE READ CAREFULLY**
+
+This software is provided **"AS IS"** without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement.
+
+### No Warranty
+- This package is provided free of charge for community use
+- The authors make no guarantees about functionality, reliability, or suitability for any purpose
+- Use this software at your own risk
+
+### No Liability
+In no event shall the authors, contributors, or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software.
+
+### Not Officially Affiliated
+- This is an **unofficial** community project
+- This project is **not affiliated with, endorsed by, or sponsored by Salesflare** (the company)
+- "Salesflare" is a trademark of its respective owner
+- All product names, logos, and brands are property of their respective owners
+
+### Data Responsibility
+- You are solely responsible for any data you access, modify, or delete using this tool
+- Always test thoroughly in a non-production environment before use
+- Ensure you comply with all applicable laws and regulations regarding data processing
+- Backup your data before performing bulk operations
+
+### API Usage
+- Use of this software requires a valid Salesflare API key
+- You must comply with Salesflare's Terms of Service and API usage policies
+- The authors are not responsible for any API rate limiting, account suspension, or service changes
+
+By using this software, you acknowledge that you have read, understood, and agree to these terms.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+- **Documentation:** [docs.salesflare.com](https://docs.salesflare.com)
+- **Issues:** [GitHub Issues](https://github.com/salesflare/mcp-server/issues)
+- **Salesflare Support:** support@salesflare.com
+
+## Acknowledgments
+
+Built with:
+- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol that powers this server
+- [Salesflare API](https://api.salesflare.com/docs) - The CRM API this server wraps
+- [Zod](https://zod.dev/) - TypeScript-first schema validation
+- [Axios](https://axios-http.com/) - HTTP client
+
+---
+
+**Note:** This is a community-maintained project. Salesflare is a trademark of Salesflare BV.