@efficy/tribecrm-mcp-server 0.3.0 → 0.4.1

package/README.md

@@ -24,6 +24,12 @@ Model Context Protocol (MCP) server for TribeCRM API integration. This server en
 - **Entity Type Definitions**: Access schema and field information for entity types
 - **Dynamic Resources**: Entity data exposed as MCP resources for context
 
+### Security Modes
+- **Read-Only Mode** (default): Secure by default - only allows querying and retrieving data
+- **Read-Write Mode**: Full access including create, update, and delete operations
+
+> ⚠️ **Breaking Change in v0.4.0**: The server now defaults to read-only mode for security. If you need write access, set `TRIBECRM_MODE=read-write` in your configuration.
+
 ## 📋 Prerequisites
 
 - Node.js 18 or higher
@@ -66,13 +72,16 @@ Add to your Claude Desktop config file:
         "TRIBECRM_AUTH_URL": "https://auth.tribecrm.nl",
         "TRIBECRM_CLIENT_ID": "your_client_id",
         "TRIBECRM_CLIENT_SECRET": "your_client_secret",
-        "TRIBECRM_ORGANIZATION_ID": "your_org_id"
+        "TRIBECRM_ORGANIZATION_ID": "your_org_id",
+        "TRIBECRM_MODE": "read-only"
       }
     }
   }
 }
 ```
 
+**Note**: Set `TRIBECRM_MODE` to `read-write` if you need to create, update, or delete entities.
+
 #### Using Local Installation
 
 ```json
@@ -86,7 +95,8 @@ Add to your Claude Desktop config file:
         "TRIBECRM_AUTH_URL": "https://auth.tribecrm.nl",
         "TRIBECRM_CLIENT_ID": "your_client_id",
         "TRIBECRM_CLIENT_SECRET": "your_client_secret",
-        "TRIBECRM_ORGANIZATION_ID": "your_org_id"
+        "TRIBECRM_ORGANIZATION_ID": "your_org_id",
+        "TRIBECRM_MODE": "read-only"
       }
     }
   }
@@ -108,6 +118,9 @@ Add to your Claude Desktop config file:
 - `TRIBECRM_CLIENT_ID` (required): OAuth2 Client ID
 - `TRIBECRM_CLIENT_SECRET` (required): OAuth2 Client Secret
 - `TRIBECRM_ORGANIZATION_ID` (optional): Organization UUID for multi-tenant setups
+- `TRIBECRM_MODE` (optional): Server operation mode - `read-only` (default) or `read-write`
+  - `read-only`: Only allows queries and data retrieval (get, query operations). Write tools are hidden.
+  - `read-write`: Allows full access including create, update, and delete operations.
 
 ## 📚 Available Tools
 
@@ -263,6 +276,48 @@ The server uses OAuth2 Client Credentials flow:
 3. Automatically refreshes token before expiry
 4. Includes token in all API requests
 
+## 🧪 Testing
+
+The project has comprehensive unit tests with >95% code coverage.
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage report
+npm run test:coverage
+
+# Run tests with UI
+npm run test:ui
+```
+
+### Test Coverage
+
+| File | Coverage | Details |
+|------|----------|---------|
+| client.ts | 100% | All API client methods tested |
+| types.ts | - | Type definitions (no runtime coverage needed) |
+| index.ts | - | Server initialization (tested separately) |
+
+**Coverage Standards**:
+- Lines: 95%+
+- Functions: 95%+
+- Branches: 95%+
+- Statements: 95%+
+
+### Writing Tests
+
+Tests are written using [Vitest](https://vitest.dev/) and follow these conventions:
+- Test files: `*.test.ts` in `src/` directory
+- Comprehensive mocking of external dependencies (axios)
+- Clear test descriptions using describe/it blocks
+- Both positive and negative test cases
+
 ## 🛠️ Development
 
 ### Project Structure

package/dist/client.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client.test.d.ts.map

package/dist/client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.d.ts","sourceRoot":"","sources":["../src/client.test.ts"],"names":[],"mappings":""}

package/dist/client.test.js

@@ -0,0 +1,547 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import axios from 'axios';
+import { TribeCRMClient } from './client.js';
+// Mock axios
+vi.mock('axios');
+const mockedAxios = vi.mocked(axios, true);
+describe('TribeCRMClient', () => {
+    let client;
+    let config;
+    beforeEach(() => {
+        // Reset mocks before each test
+        vi.clearAllMocks();
+        // Setup test configuration
+        config = {
+            apiUrl: 'https://api-test.tribecrm.nl',
+            authUrl: 'https://auth-test.tribecrm.nl',
+            clientId: 'test-client-id',
+            clientSecret: 'test-client-secret',
+            organizationId: 'test-org-id',
+            mode: 'read-write',
+        };
+        // Mock axios.create to return a mocked instance
+        mockedAxios.create = vi.fn().mockReturnValue({
+            get: vi.fn(),
+            post: vi.fn(),
+            delete: vi.fn(),
+            defaults: {
+                headers: {
+                    common: {},
+                },
+            },
+        });
+        client = new TribeCRMClient(config);
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe('Authentication', () => {
+        it('should authenticate successfully with valid credentials', async () => {
+            const mockToken = {
+                access_token: 'test-access-token',
+                token_type: 'bearer',
+                expires_in: 86399,
+                scope: 'read write offline',
+            };
+            // Mock OAuth token request
+            mockedAxios.post = vi.fn().mockResolvedValue({
+                data: mockToken,
+            });
+            // Mock getCurrentEmployee to trigger authentication
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockResolvedValue({
+                data: { ID: 'test-employee-id', Name: 'Test User' },
+            });
+            const result = await client.getCurrentEmployee();
+            expect(mockedAxios.post).toHaveBeenCalledWith('https://auth-test.tribecrm.nl/oauth2/token', expect.any(URLSearchParams), expect.objectContaining({
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                },
+            }));
+            expect(result).toEqual({ ID: 'test-employee-id', Name: 'Test User' });
+        });
+        it('should include organization_id in auth request when provided', async () => {
+            const mockToken = {
+                access_token: 'test-token',
+                token_type: 'bearer',
+                expires_in: 86399,
+                scope: 'read write offline',
+            };
+            mockedAxios.post = vi.fn().mockResolvedValue({
+                data: mockToken,
+            });
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockResolvedValue({
+                data: { ID: 'test-id' },
+            });
+            await client.getCurrentEmployee();
+            const authCall = mockedAxios.post.mock.calls[0];
+            const params = authCall[1];
+            expect(params.get('organization_id')).toBe('test-org-id');
+        });
+        it('should handle authentication failure', async () => {
+            mockedAxios.post = vi.fn().mockRejectedValue({
+                response: {
+                    data: {
+                        error: 'invalid_client',
+                        error_description: 'Invalid credentials',
+                    },
+                },
+            });
+            await expect(client.getCurrentEmployee()).rejects.toThrow('Authentication failed: Invalid credentials');
+        });
+        it('should reuse existing token if not expired', async () => {
+            const mockToken = {
+                access_token: 'test-token',
+                token_type: 'bearer',
+                expires_in: 86399,
+                scope: 'read write offline',
+            };
+            mockedAxios.post = vi.fn().mockResolvedValue({
+                data: mockToken,
+            });
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockResolvedValue({
+                data: { ID: 'test-id' },
+            });
+            // First call - should authenticate
+            await client.getCurrentEmployee();
+            expect(mockedAxios.post).toHaveBeenCalledTimes(1);
+            // Second call - should reuse token
+            await client.getCurrentEmployee();
+            expect(mockedAxios.post).toHaveBeenCalledTimes(1); // Still only 1
+        });
+        it('should refresh token when expired', async () => {
+            const mockToken = {
+                access_token: 'test-token',
+                token_type: 'bearer',
+                expires_in: 0, // Expires immediately
+                scope: 'read write offline',
+            };
+            mockedAxios.post = vi.fn().mockResolvedValue({
+                data: mockToken,
+            });
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockResolvedValue({
+                data: { ID: 'test-id' },
+            });
+            // First call
+            await client.getCurrentEmployee();
+            expect(mockedAxios.post).toHaveBeenCalledTimes(1);
+            // Wait for token to expire
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            // Second call - should refresh token
+            await client.getCurrentEmployee();
+            expect(mockedAxios.post).toHaveBeenCalledTimes(2);
+        });
+    });
+    describe('getEntity', () => {
+        beforeEach(async () => {
+            // Setup authentication
+            mockedAxios.post = vi.fn().mockResolvedValue({
+                data: {
+                    access_token: 'test-token',
+                    token_type: 'bearer',
+                    expires_in: 86399,
+                    scope: 'read write offline',
+                },
+            });
+        });
+        it('should get entity by ID successfully', async () => {
+            const mockEntity = {
+                ID: 'entity-123',
+                Name: 'Test Organization',
+                Type: 'Relation_Organization',
+            };
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockResolvedValue({
+                data: mockEntity,
+            });
+            const result = await client.getEntity('Relation_Organization', 'entity-123');
+            expect(axiosInstance.get).toHaveBeenCalledWith('/v1/odata/Relation_Organization(entity-123)', { params: {} });
+            expect(result).toEqual(mockEntity);
+        });
+        it('should include expand parameter when provided', async () => {
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockResolvedValue({
+                data: { ID: 'test-id' },
+            });
+            await client.getEntity('Relation_Organization', 'entity-123', 'Address');
+            expect(axiosInstance.get).toHaveBeenCalledWith('/v1/odata/Relation_Organization(entity-123)', { params: { $expand: 'Address' } });
+        });
+        it('should include select parameter when provided', async () => {
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockResolvedValue({
+                data: { ID: 'test-id' },
+            });
+            await client.getEntity('Relation_Organization', 'entity-123', undefined, 'Name,Email');
+            expect(axiosInstance.get).toHaveBeenCalledWith('/v1/odata/Relation_Organization(entity-123)', { params: { $select: 'Name,Email' } });
+        });
+        it('should include both expand and select parameters', async () => {
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockResolvedValue({
+                data: { ID: 'test-id' },
+            });
+            await client.getEntity('Relation_Organization', 'entity-123', 'Address', 'Name,Email');
+            expect(axiosInstance.get).toHaveBeenCalledWith('/v1/odata/Relation_Organization(entity-123)', { params: { $expand: 'Address', $select: 'Name,Email' } });
+        });
+    });
+    describe('createEntity', () => {
+        beforeEach(async () => {
+            mockedAxios.post = vi.fn().mockResolvedValue({
+                data: {
+                    access_token: 'test-token',
+                    token_type: 'bearer',
+                    expires_in: 86399,
+                    scope: 'read write offline',
+                },
+            });
+        });
+        it('should create entity successfully', async () => {
+            const entityData = {
+                Name: 'New Organization',
+                Email: 'test@example.com',
+            };
+            const mockCreatedEntity = {
+                ID: 'new-entity-id',
+                ...entityData,
+            };
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.post = vi.fn().mockResolvedValue({
+                data: mockCreatedEntity,
+            });
+            const result = await client.createEntity('Relation_Organization', entityData);
+            expect(axiosInstance.post).toHaveBeenCalledWith('/v1/odata/Relation_Organization', entityData);
+            expect(result).toEqual(mockCreatedEntity);
+        });
+        it('should not include ID in create request', async () => {
+            const entityData = {
+                Name: 'New Organization',
+            };
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.post = vi.fn().mockResolvedValue({
+                data: { ID: 'new-id', ...entityData },
+            });
+            await client.createEntity('Relation_Organization', entityData);
+            const callData = axiosInstance.post.mock.calls[0][1];
+            expect(callData).not.toHaveProperty('ID');
+        });
+    });
+    describe('updateEntity', () => {
+        beforeEach(async () => {
+            mockedAxios.post = vi.fn().mockResolvedValue({
+                data: {
+                    access_token: 'test-token',
+                    token_type: 'bearer',
+                    expires_in: 86399,
+                    scope: 'read write offline',
+                },
+            });
+        });
+        it('should update entity successfully', async () => {
+            const updateData = {
+                Name: 'Updated Organization',
+            };
+            const mockUpdatedEntity = {
+                ID: 'entity-123',
+                ...updateData,
+            };
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.post = vi.fn().mockResolvedValue({
+                data: mockUpdatedEntity,
+            });
+            const result = await client.updateEntity('Relation_Organization', 'entity-123', updateData);
+            expect(axiosInstance.post).toHaveBeenCalledWith('/v1/odata/Relation_Organization', { ...updateData, ID: 'entity-123' });
+            expect(result).toEqual(mockUpdatedEntity);
+        });
+        it('should include ID in update request payload', async () => {
+            const updateData = {
+                Name: 'Updated Name',
+            };
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.post = vi.fn().mockResolvedValue({
+                data: { ID: 'entity-123', ...updateData },
+            });
+            await client.updateEntity('Relation_Organization', 'entity-123', updateData);
+            const callData = axiosInstance.post.mock.calls[0][1];
+            expect(callData).toHaveProperty('ID', 'entity-123');
+        });
+    });
+    describe('deleteEntity', () => {
+        beforeEach(async () => {
+            mockedAxios.post = vi.fn().mockResolvedValue({
+                data: {
+                    access_token: 'test-token',
+                    token_type: 'bearer',
+                    expires_in: 86399,
+                    scope: 'read write offline',
+                },
+            });
+        });
+        it('should delete entity successfully', async () => {
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.delete = vi.fn().mockResolvedValue({});
+            await client.deleteEntity('Relation_Organization', 'entity-123');
+            expect(axiosInstance.delete).toHaveBeenCalledWith('/v1/odata/Relation_Organization(entity-123)');
+        });
+        it('should not return data on successful delete', async () => {
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.delete = vi.fn().mockResolvedValue({});
+            const result = await client.deleteEntity('Relation_Organization', 'entity-123');
+            expect(result).toBeUndefined();
+        });
+    });
+    describe('queryEntities', () => {
+        beforeEach(async () => {
+            mockedAxios.post = vi.fn().mockResolvedValue({
+                data: {
+                    access_token: 'test-token',
+                    token_type: 'bearer',
+                    expires_in: 86399,
+                    scope: 'read write offline',
+                },
+            });
+        });
+        it('should query entities with no filters', async () => {
+            const mockResults = {
+                value: [{ ID: '1', Name: 'Entity 1' }],
+            };
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockResolvedValue({
+                data: mockResults,
+            });
+            const result = await client.queryEntities('Relation_Organization');
+            expect(axiosInstance.get).toHaveBeenCalledWith('/v1/odata/Relation_Organization', {
+                params: {},
+            });
+            expect(result).toEqual(mockResults);
+        });
+        it('should include filter parameter', async () => {
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockResolvedValue({
+                data: { value: [] },
+            });
+            await client.queryEntities('Relation_Organization', {
+                filter: "contains(Name, 'test')",
+            });
+            expect(axiosInstance.get).toHaveBeenCalledWith('/v1/odata/Relation_Organization', {
+                params: { $filter: "contains(Name, 'test')" },
+            });
+        });
+        it('should include select parameter', async () => {
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockResolvedValue({
+                data: { value: [] },
+            });
+            await client.queryEntities('Relation_Organization', {
+                select: 'ID,Name',
+            });
+            expect(axiosInstance.get).toHaveBeenCalledWith('/v1/odata/Relation_Organization', {
+                params: { $select: 'ID,Name' },
+            });
+        });
+        it('should include expand parameter', async () => {
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockResolvedValue({
+                data: { value: [] },
+            });
+            await client.queryEntities('Relation_Organization', {
+                expand: 'Address',
+            });
+            expect(axiosInstance.get).toHaveBeenCalledWith('/v1/odata/Relation_Organization', {
+                params: { $expand: 'Address' },
+            });
+        });
+        it('should include orderby parameter', async () => {
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockResolvedValue({
+                data: { value: [] },
+            });
+            await client.queryEntities('Relation_Organization', {
+                orderby: 'Name desc',
+            });
+            expect(axiosInstance.get).toHaveBeenCalledWith('/v1/odata/Relation_Organization', {
+                params: { $orderby: 'Name desc' },
+            });
+        });
+        it('should include pagination parameters (top and skip)', async () => {
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockResolvedValue({
+                data: { value: [] },
+            });
+            await client.queryEntities('Relation_Organization', {
+                top: 10,
+                skip: 20,
+            });
+            expect(axiosInstance.get).toHaveBeenCalledWith('/v1/odata/Relation_Organization', {
+                params: { $top: 10, $skip: 20 },
+            });
+        });
+        it('should include count parameter', async () => {
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockResolvedValue({
+                data: { value: [], '@odata.count': 42 },
+            });
+            await client.queryEntities('Relation_Organization', {
+                count: true,
+            });
+            expect(axiosInstance.get).toHaveBeenCalledWith('/v1/odata/Relation_Organization', {
+                params: { $count: 'true' },
+            });
+        });
+        it('should include all query parameters together', async () => {
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockResolvedValue({
+                data: { value: [] },
+            });
+            await client.queryEntities('Relation_Organization', {
+                filter: "contains(Name, 'test')",
+                select: 'ID,Name',
+                expand: 'Address',
+                orderby: 'Name asc',
+                top: 10,
+                skip: 20,
+                count: true,
+            });
+            expect(axiosInstance.get).toHaveBeenCalledWith('/v1/odata/Relation_Organization', {
+                params: {
+                    $filter: "contains(Name, 'test')",
+                    $select: 'ID,Name',
+                    $expand: 'Address',
+                    $orderby: 'Name asc',
+                    $top: 10,
+                    $skip: 20,
+                    $count: 'true',
+                },
+            });
+        });
+    });
+    describe('getCurrentEmployee', () => {
+        beforeEach(async () => {
+            mockedAxios.post = vi.fn().mockResolvedValue({
+                data: {
+                    access_token: 'test-token',
+                    token_type: 'bearer',
+                    expires_in: 86399,
+                    scope: 'read write offline',
+                },
+            });
+        });
+        it('should get current employee without expand', async () => {
+            const mockEmployee = {
+                ID: 'employee-123',
+                Name: 'Test Employee',
+            };
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockResolvedValue({
+                data: mockEmployee,
+            });
+            const result = await client.getCurrentEmployee();
+            expect(axiosInstance.get).toHaveBeenCalledWith('/v1/odata/GetCurrentEmployee()', {
+                params: {},
+            });
+            expect(result).toEqual(mockEmployee);
+        });
+        it('should include expand parameter when provided', async () => {
+            const mockEmployee = {
+                ID: 'employee-123',
+                Person: {
+                    ID: 'person-123',
+                    Name: 'Test Person',
+                },
+            };
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockResolvedValue({
+                data: mockEmployee,
+            });
+            const result = await client.getCurrentEmployee('Person');
+            expect(axiosInstance.get).toHaveBeenCalledWith('/v1/odata/GetCurrentEmployee()', {
+                params: { $expand: 'Person' },
+            });
+            expect(result).toEqual(mockEmployee);
+        });
+    });
+    describe('listEntityTypes', () => {
+        beforeEach(async () => {
+            mockedAxios.post = vi.fn().mockResolvedValue({
+                data: {
+                    access_token: 'test-token',
+                    token_type: 'bearer',
+                    expires_in: 86399,
+                    scope: 'read write offline',
+                },
+            });
+        });
+        it('should return hardcoded entity types', async () => {
+            const result = await client.listEntityTypes();
+            expect(result).toBeInstanceOf(Array);
+            expect(result.length).toBeGreaterThan(0);
+            expect(result).toContainEqual(expect.objectContaining({
+                code: 'Relation_Organization',
+                name: 'Organizations',
+            }));
+            expect(result).toContainEqual(expect.objectContaining({
+                code: 'Relation_Person',
+                name: 'Persons',
+            }));
+        });
+        it('should return entities with required fields', async () => {
+            const result = await client.listEntityTypes();
+            result.forEach((entityType) => {
+                expect(entityType).toHaveProperty('code');
+                expect(entityType).toHaveProperty('name');
+                expect(entityType).toHaveProperty('fields');
+                expect(Array.isArray(entityType.fields)).toBe(true);
+            });
+        });
+        it('should handle metadata fetch errors gracefully', async () => {
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockRejectedValue(new Error('Metadata fetch failed'));
+            const result = await client.listEntityTypes();
+            // Should return empty array on error
+            expect(result).toBeInstanceOf(Array);
+            expect(result.length).toBe(0);
+        });
+    });
+    describe('Error Handling', () => {
+        beforeEach(async () => {
+            mockedAxios.post = vi.fn().mockResolvedValue({
+                data: {
+                    access_token: 'test-token',
+                    token_type: 'bearer',
+                    expires_in: 86399,
+                    scope: 'read write offline',
+                },
+            });
+        });
+        it('should handle network errors', async () => {
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockRejectedValue(new Error('Network error'));
+            await expect(client.getEntity('Relation_Organization', 'entity-123')).rejects.toThrow('Network error');
+        });
+        it('should handle API errors with error messages', async () => {
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockRejectedValue({
+                response: {
+                    data: {
+                        error: {
+                            message: 'Entity not found',
+                        },
+                    },
+                },
+            });
+            await expect(client.getEntity('Relation_Organization', 'entity-123')).rejects.toThrow();
+        });
+        it('should handle HTTP status errors', async () => {
+            const axiosInstance = client.axiosInstance;
+            axiosInstance.get = vi.fn().mockRejectedValue({
+                response: {
+                    status: 404,
+                    statusText: 'Not Found',
+                },
+            });
+            await expect(client.getEntity('Relation_Organization', 'entity-123')).rejects.toThrow();
+        });
+    });
+});
+//# sourceMappingURL=client.test.js.map