salesflare-mcp-server 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-06-02
+
+### Added
+
+- Initial release of Salesflare MCP Server
+- API key authentication support
+- Stdio and HTTP Streamable transports
+- Contact management (list, create, update, delete)
+- Company management (list, create, update, delete) with contact unlinking
+- Deal management (list, create, update, delete, move_stage)
+- Task management (list, create, update) with overdue detection
+- Pipeline operations (list stages, overview with statistics)
+- Comprehensive test suite with 300+ unit tests
+- MCP Inspector compatibility
+- Full API documentation (API.md)
+- Contributing guide (CONTRIBUTING.md)
+- MCP Inspector testing guide (INSPECTOR.md)
+
+### Technical
+
+- TypeScript with strict mode
+- Zod for schema validation
+- Axios for HTTP client with retry logic
+- Express for HTTP transport
+- Jest for testing
+- 80%+ code coverage for core modules
+
+### Notes
+
+- Requires Node.js >= 18.0.0
+- Requires Salesflare API key
+- OAuth 2.0 planned for Phase 2
+
+## [Unreleased]
+
+### Planned
+
+- OAuth 2.0 authentication
+- Webhook support
+- Bulk operations
+- Advanced filtering
+

package/CLAUDE.md

@@ -0,0 +1,117 @@
+# CLAUDE.md — Salesflare MCP Server
+
+This file contains GSD workflow guidance and project context for Claude/OpenCode when working on this project.
+
+## Project Overview
+
+**Salesflare MCP Server** — A Model Context Protocol server enabling LLMs to interact with Salesflare CRM via natural language.
+
+- **Language:** TypeScript
+- **Transport:** stdio + HTTP Streamable
+- **Auth:** API Key + OAuth 2.0
+- **Status:** Phase 1 (Infrastructure & Auth)
+
+## Quick Links
+
+- `.planning/PROJECT.md` — Project context, requirements, decisions
+- `.planning/REQUIREMENTS.md` — Detailed requirements with traceability
+- `.planning/ROADMAP.md` — 6-phase execution plan
+- `.planning/STATE.md` — Current status and blockers
+- `.planning/config.json` — Workflow settings
+
+## GSD Commands Available
+
+- `/gsd-discuss-phase [N]` — Gather context before planning
+- `/gsd-plan-phase [N]` — Create detailed plan for phase
+- `/gsd-execute-phase [N]` — Execute phase plan
+- `/gsd-verify-work [N]` — Verify phase completion
+- `/gsd-progress` — Check overall project status
+
+## Development Guidelines
+
+### TypeScript Standards
+- Strict mode enabled
+- Use Zod for all input validation
+- Async/await for all async operations
+- Proper error handling with actionable messages
+
+### MCP Patterns
+- Tool naming: `salesflare_[entity]_[action]` (e.g., `salesflare_contacts_list`)
+- Input schemas: Use Zod with descriptive field names
+- Output: Return both text and structured data where applicable
+- Annotations: Mark readOnly/destructive/idempotent hints
+
+### API Client Patterns
+- Base URL: `https://api.salesflare.com`
+- Headers: `Authorization: Bearer {token}`
+- Rate limiting: Implement exponential backoff
+- Error handling: Map API errors to MCP error responses
+
+### Testing
+- MCP Inspector: `npx @modelcontextprotocol/inspector`
+- Unit tests: Jest with mocked API
+- Integration tests: Live API with test account
+
+## Architecture
+
+```
+src/
+├── index.ts              # Entry point, transport setup
+├── server.ts             # MCP server configuration
+├── client/
+│   └── salesflare.ts     # Salesflare API client
+├── tools/
+│   ├── contacts.ts       # Contact tools
+│   ├── companies.ts      # Company tools
+│   ├── deals.ts          # Deal tools
+│   ├── tasks.ts          # Task tools
+│   └── pipeline.ts       # Pipeline tools
+├── auth/
+│   ├── api-key.ts        # API key auth
+│   └── oauth.ts          # OAuth 2.0 flow
+└── utils/
+    ├── errors.ts         # Error handling
+    └── pagination.ts     # Pagination helpers
+```
+
+## Environment Variables
+
+```env
+SALESFLARE_API_KEY=         # For API key auth
+SALESFLARE_CLIENT_ID=       # For OAuth
+SALESFLARE_CLIENT_SECRET=   # For OAuth
+SALESFLARE_REDIRECT_URI=    # For OAuth
+TRANSPORT=stdio|http         # Transport mode
+PORT=3000                   # HTTP port (if http transport)
+```
+
+## Building
+
+```bash
+npm install
+npm run build
+npm run test
+```
+
+## Running
+
+```bash
+# stdio mode (for MCP Inspector)
+npm start
+
+# HTTP mode
+TRANSPORT=http npm start
+```
+
+## Dependencies
+
+- `@modelcontextprotocol/server` — MCP SDK
+- `zod` — Schema validation
+- `axios` — HTTP client
+- `typescript` — Type checking
+- `jest` — Testing
+
+---
+
+*Last updated: 2025-05-15*
+*GSD Version: 1.0*

package/CONTRIBUTING.md

@@ -0,0 +1,399 @@
+# Contributing to Salesflare MCP Server
+
+Thank you for your interest in contributing! This guide will help you get started with development.
+
+## Development Setup
+
+### Prerequisites
+
+- **Node.js** >= 18.0.0
+- **npm** >= 9.0.0
+- **Git**
+
+### Clone and Install
+
+```bash
+git clone https://github.com/salesflare/mcp-server.git
+cd mcp-server
+npm install
+```
+
+### Configure Environment
+
+```bash
+# Copy environment template
+cp .env.example .env
+
+# Edit .env with your credentials
+SALESFLARE_API_KEY=your_api_key_here
+TRANSPORT=stdio
+```
+
+Get your API key from: https://app.salesflare.com/settings/api
+
+### Build the Project
+
+```bash
+# Build once
+npm run build
+
+# Watch mode (rebuilds on changes)
+npm run dev
+```
+
+### Verify Setup
+
+```bash
+# Run tests
+npm test
+
+# Start the server
+npm start
+```
+
+## Project Structure
+
+```
+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
+├── 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
+├── types/
+│   ├── contact.ts        # Contact types
+│   ├── company.ts        # Company types
+│   ├── deal.ts           # Deal types
+│   ├── task.ts           # Task types
+│   └── pipeline.ts       # Pipeline types
+└── utils/
+    ├── errors.ts         # Error handling utilities
+    └── validation.ts     # Zod validation schemas
+
+tests/
+├── unit/                 # Unit tests
+│   ├── contacts-*.test.ts
+│   ├── companies-*.test.ts
+│   ├── deals-*.test.ts
+│   ├── tasks-*.test.ts
+│   ├── pipeline-*.test.ts
+│   └── validation.test.ts
+└── integration/          # Integration tests
+    └── server.test.ts
+```
+
+## Running Tests
+
+### All Tests
+
+```bash
+npm test
+```
+
+### With Coverage
+
+```bash
+npm test -- --coverage
+```
+
+Coverage reports are generated in `coverage/` directory.
+
+### Watch Mode
+
+```bash
+npm test -- --watch
+```
+
+### Specific Test File
+
+```bash
+npm test -- contacts-list.test.ts
+```
+
+### Integration Tests
+
+```bash
+# Requires SALESFLARE_API_KEY to be set
+npm run test:integration
+```
+
+## Testing with MCP Inspector
+
+The MCP Inspector is the best way to test tool behavior:
+
+```bash
+# Start with Inspector
+npm run inspector
+```
+
+This opens a web interface where you can:
+- Browse all available tools
+- Test tool inputs
+- View responses
+- Debug errors
+
+See [INSPECTOR.md](INSPECTOR.md) for detailed testing scenarios.
+
+## Code Style
+
+### TypeScript
+
+- **Strict mode** enabled
+- Use **explicit types** where inference is unclear
+- Use **interface** for object shapes, **type** for unions/aliases
+- Prefix private methods with `_`
+
+### Error Handling
+
+All errors must use the `SalesflareError` class:
+
+```typescript
+import { SalesflareError, ErrorCode } from '../utils/errors.js';
+
+// Validation errors
+throw new SalesflareError(
+  'Email is required',
+  ErrorCode.VALIDATION_ERROR,
+  400,
+  { field: 'email' },
+  false
+);
+
+// API errors (retryable)
+throw new SalesflareError(
+  'Rate limit exceeded',
+  ErrorCode.RATE_LIMIT,
+  429,
+  {},
+  true
+);
+```
+
+### Validation
+
+Use Zod for all input validation:
+
+```typescript
+import { z } from 'zod';
+
+const createContactSchema = z.object({
+  email: z.string().email(),
+  name: z.string().optional(),
+});
+
+// Validate
+const result = createContactSchema.safeParse(input);
+if (!result.success) {
+  // Handle validation errors
+}
+```
+
+### Async/Await
+
+Use async/await for all asynchronous operations:
+
+```typescript
+// Good
+async function fetchContacts(): Promise<Contact[]> {
+  const response = await client.get('/contacts');
+  return response.items;
+}
+
+// Avoid
+function fetchContacts(): Promise<Contact[]> {
+  return client.get('/contacts').then(r => r.items);
+}
+```
+
+## Adding New Tools
+
+### 1. Define Types
+
+Create or update `src/types/{entity}.ts`:
+
+```typescript
+export interface MyEntity {
+  id: string;
+  name: string;
+  created_at: string;
+}
+
+export interface MyEntityCreateInput {
+  name: string;
+}
+```
+
+### 2. Create Validation Schema
+
+Add to `src/utils/validation.ts`:
+
+```typescript
+export const createMyEntitySchema = z.object({
+  name: z.string().min(1),
+});
+```
+
+### 3. Implement Tool
+
+Create or update `src/tools/{entity}.ts`:
+
+```typescript
+const myEntityTools: Tool[] = [
+  {
+    name: 'salesflare_myentities_create',
+    description: 'Create a new entity',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+      },
+      required: ['name'],
+    },
+  },
+];
+
+// Handler
+async function handleMyEntityCreate(args: unknown) {
+  // Validate input
+  // Call API
+  // Return formatted response
+}
+```
+
+### 4. Register Tool
+
+Update `src/server.ts`:
+
+```typescript
+import { registerMyEntityTools } from './tools/myentity.js';
+
+// In createServer function:
+registerMyEntityTools(server, client);
+```
+
+### 5. Add Tests
+
+Create `tests/unit/myentities-create.test.ts`:
+
+```typescript
+import { describe, it, expect, jest, beforeEach } from '@jest/globals';
+import { registerMyEntityTools } from '../../src/tools/myentity.js';
+
+describe('salesflare_myentities_create', () => {
+  // Test setup...
+  
+  it('should create entity successfully', async () => {
+    // Test implementation
+  });
+  
+  it('should handle validation errors', async () => {
+    // Test validation
+  });
+});
+```
+
+### 6. Update Documentation
+
+- Add tool to [API.md](API.md)
+- Add example to [INSPECTOR.md](INSPECTOR.md)
+- Update README.md tool list if needed
+
+## Submitting PRs
+
+### Before Submitting
+
+1. **All tests must pass**
+   ```bash
+   npm test
+   ```
+
+2. **Code coverage maintained**
+   - New code should have tests
+   - Overall coverage should stay above 80%
+
+3. **Build succeeds**
+   ```bash
+   npm run build
+   ```
+
+4. **TypeScript compiles without errors**
+   ```bash
+   npx tsc --noEmit
+   ```
+
+### PR Checklist
+
+- [ ] Tests added for new functionality
+- [ ] All tests pass
+- [ ] Build succeeds
+- [ ] Code follows style guidelines
+- [ ] Documentation updated
+- [ ] Commit messages follow conventional format
+
+### Commit Message Format
+
+We use conventional commits:
+
+```
+type(scope): description
+
+Examples:
+feat(contacts): add phone number validation
+fix(api): handle 429 rate limit errors
+docs(readme): update installation instructions
+test(deals): add edge case tests for value conversion
+refactor(client): extract retry logic to separate function
+```
+
+Types:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `test`: Adding or updating tests
+- `refactor`: Code refactoring
+- `chore`: Build/config changes
+
+### PR Process
+
+1. **Fork the repository**
+2. **Create a feature branch** (`git checkout -b feature/my-feature`)
+3. **Make your changes**
+4. **Commit with descriptive messages**
+5. **Push to your fork**
+6. **Submit a Pull Request**
+
+## Release Process
+
+Releases are managed by maintainers:
+
+1. Version bump in `package.json`
+2. Update `CHANGELOG.md`
+3. Create git tag
+4. Publish to npm
+5. Create GitHub release
+
+## Questions?
+
+- **General questions:** Open a GitHub Discussion
+- **Bug reports:** Open a GitHub Issue
+- **Security issues:** Email security@salesflare.com
+
+## Code of Conduct
+
+- Be respectful and inclusive
+- Focus on constructive feedback
+- Help others learn and grow
+
+Thank you for contributing!

package/FIX_PLAN.md

@@ -0,0 +1,70 @@
+# Salesflare MCP Tool Fixes - Action Plan
+
+## Test Results Summary
+- **Date**: 2025-06-02
+- **Total Tests**: 17
+- **Passed**: 8 (47.1%)
+- **Failed**: 9 (52.9%)
+
+## Issues by Category
+
+### 1. DEALS - Wrong Endpoint
+**Error**: `Resource not found: /deals`
+
+**Root Cause**: Salesflare API uses `/opportunities` not `/deals`
+
+**Fix**: Update `src/tools/deals.ts` line 270:
+```typescript
+// Change from:
+}>('/deals', { params: queryParams });
+
+// To:
+}>('/opportunities', { params: queryParams });
+```
+
+---
+
+### 2. TASKS - Schema Validation Errors
+**Errors**:
+- `Validation error: "page" is not allowed`
+- `Validation error: "status" is not allowed`
+
+**Root Cause**: Task Zod schemas are too restrictive
+
+**Fix**: Update `src/utils/validation.ts`:
+
+For task list schema, allow:
+- `page` and `limit` for pagination
+- `status` filter
+
+For task create schema:
+- Remove `.strict()` to allow optional fields like `status`
+- Or explicitly add `status` to schema
+
+---
+
+### 3. PIPELINE - Response Format Issues
+**Error**: `Cannot read properties of undefined (reading 'map')`
+
+**Root Cause**: Pipeline API returns different response format than expected
+
+**Fix**: Update `src/tools/pipeline.ts`:
+
+Add defensive checks for response format:
+```typescript
+const pipelines = Array.isArray(response) ? response : response.items || [];
+const stages = Array.isArray(response) ? response : response.items || [];
+```
+
+---
+
+## Quick Fixes Priority
+
+1. **HIGH**: Fix deals endpoint (`/deals` → `/opportunities`)
+2. **HIGH**: Fix task validation schemas
+3. **MEDIUM**: Fix pipeline response handling
+
+## Expected Result After Fixes
+- Success rate should increase from 47% to ~90%+
+- All list operations should work
+- Create operations should work for contacts, companies, deals, tasks