teamleader-mcp 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+# 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-01-31
+
+### Added
+
+#### CRM Module
+- **Companies** - Full CRUD operations
+  - `teamleader_companies_list` - List companies with filters (name, VAT, tags, status)
+  - `teamleader_company_info` - Get company details by ID
+  - `teamleader_company_create` - Create a new company
+  - `teamleader_company_update` - Update an existing company
+
+- **Contacts** - List and read operations
+  - `teamleader_contacts_list` - List contacts with filters
+  - `teamleader_contact_info` - Get contact details by ID
+
+#### Deals Module
+- **Deals** - Complete pipeline management
+  - `teamleader_deals_list` - List deals with filters (status, customer, phase)
+  - `teamleader_deal_info` - Get deal details by ID
+  - `teamleader_deal_create` - Create a new deal
+  - `teamleader_deal_update` - Update an existing deal
+  - `teamleader_deal_move` - Move deal to a different phase
+  - `teamleader_deal_win` - Mark deal as won
+  - `teamleader_deal_lose` - Mark deal as lost with optional reason
+
+#### Invoicing Module
+- **Invoices** - Complete invoice lifecycle
+  - `teamleader_invoices_list` - List invoices with filters
+  - `teamleader_invoice_info` - Get invoice details by ID
+  - `teamleader_invoice_draft` - Create a draft invoice
+  - `teamleader_invoice_send` - Send invoice via email
+  - `teamleader_invoice_book` - Book (finalize) a draft invoice
+  - `teamleader_invoice_delete` - Delete an invoice
+  - `teamleader_invoice_register_payment` - Register a payment
+
+- **Quotations** - Complete quotation management
+  - `teamleader_quotations_list` - List quotations
+  - `teamleader_quotation_info` - Get quotation details
+  - `teamleader_quotation_create` - Create a new quotation
+  - `teamleader_quotation_send` - Send quotation via email
+  - `teamleader_quotation_accept` - Mark quotation as accepted
+  - `teamleader_quotation_delete` - Delete a quotation
+  - `teamleader_quotation_download` - Get PDF download link
+
+#### Products Module
+- **Products** - Product catalog management
+  - `teamleader_products_list` - List products with filters
+  - `teamleader_product_info` - Get product details
+  - `teamleader_product_create` - Create a new product
+  - `teamleader_product_update` - Update a product
+
+#### Time Tracking Module
+- **Time Tracking** - Track billable and non-billable time
+  - `teamleader_timetracking_list` - List time entries
+  - `teamleader_timetracking_info` - Get time entry details
+  - `teamleader_timetracking_add` - Add a time entry
+  - `teamleader_timetracking_update` - Update a time entry
+  - `teamleader_timetracking_delete` - Delete a time entry
+
+#### Calendar Module
+- **Calendar Events** - Event management
+  - `teamleader_events_list` - List calendar events
+  - `teamleader_event_info` - Get event details
+  - `teamleader_event_create` - Create a new event
+
+#### Email Module
+- **Email Tracking** - Log emails to CRM entities
+  - `teamleader_email_track` - Log an email to an entity
+  - `teamleader_emails_list` - List tracked emails
+
+### Technical
+- Full TypeScript implementation with strict typing
+- Zod schemas for input validation
+- 259 unit tests with 100% pass rate
+- MCP SDK integration
+- OAuth 2.0 authentication support
+
+## [0.1.0] - 2026-01-30
+
+### Added
+- Initial project setup
+- Basic calendar, contacts, and email tracking tools
+- Teamleader API client with authentication
+- Test infrastructure with Vitest

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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/README.md

@@ -0,0 +1,458 @@
+<p align="center">
+  <img src="https://www.teamleader.eu/hs-fs/hubfs/Logos/logo-teamleader-focus.png" alt="Teamleader Focus" width="300">
+</p>
+
+<h1 align="center">Teamleader MCP Server</h1>
+
+<p align="center">
+  <strong>Control Teamleader Focus with natural language through the Model Context Protocol</strong>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#tools">Tools</a> •
+  <a href="#examples">Examples</a> •
+  <a href="#contributing">Contributing</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/teamleader-mcp"><img src="https://img.shields.io/npm/v/teamleader-mcp" alt="npm version"></a>
+  <img src="https://img.shields.io/badge/tools-42-blue" alt="42 Tools">
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License">
+  <img src="https://img.shields.io/badge/MCP-compatible-purple" alt="MCP Compatible">
+  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node >= 18">
+</p>
+
+---
+
+## What is this?
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that connects AI assistants like Claude to [Teamleader Focus](https://www.teamleader.eu/) - the all-in-one CRM, invoicing, and project management platform.
+
+**Instead of clicking through menus, just ask:**
+
+```
+"Find all open deals for Acme Corporation"
+"Create an invoice for 20 hours of consulting at €125/hour"
+"Schedule a meeting with Sarah from TechStart next Tuesday at 2pm"
+"Log 3 hours to the website project with description: frontend development"
+```
+
+---
+
+## Screenshots
+
+<!-- TODO: Add screenshots before public launch -->
+
+<p align="center">
+  <i>🖼️ Screenshots coming soon</i>
+</p>
+
+<details>
+<summary>Screenshot placeholders</summary>
+
+| Description | Image |
+|-------------|-------|
+| Claude Desktop with deal lookup | `screenshots/deal-lookup.png` |
+| Invoice creation conversation | `screenshots/invoice-creation.png` |
+| Multi-step workflow example | `screenshots/workflow.png` |
+| Claude Desktop config | `screenshots/config.png` |
+
+</details>
+
+---
+
+## Features
+
+### 🏢 CRM
+- **Companies** - List, search, create, and update companies
+- **Contacts** - Full contact management with company linking
+- **Deals** - Pipeline management, move phases, win/lose tracking
+
+### 💰 Finance
+- **Invoices** - Draft, send, book, register payments
+- **Quotations** - Create, send, accept, download PDFs
+- **Products** - Product catalog management
+
+### ⏱️ Operations
+- **Time Tracking** - Log hours, manage entries, billable tracking
+- **Calendar Events** - Create and manage meetings linked to contacts/deals
+- **Email Tracking** - Log emails to entities
+
+### 🔐 Security
+- OAuth 2.0 with automatic token refresh
+- Secure credential storage
+- Rate limiting respect
+
+---
+
+## Quick Start
+
+### 1. Authenticate with Teamleader
+
+```bash
+npx teamleader-mcp auth
+```
+
+This opens a browser for OAuth login. Your credentials are saved automatically.
+
+### 2. Configure Claude Desktop
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "teamleader": {
+      "command": "npx",
+      "args": ["-y", "teamleader-mcp"]
+    }
+  }
+}
+```
+
+### 3. Start Using!
+
+Restart Claude Desktop and ask: *"What Teamleader tools do you have access to?"*
+
+---
+
+## Installation
+
+### Prerequisites
+- Node.js 18 or higher
+- A Teamleader Focus account
+- OAuth 2.0 credentials from [Teamleader Marketplace](https://marketplace.focus.teamleader.eu/build)
+
+### Via npx (Recommended)
+No installation needed - runs directly:
+```bash
+npx teamleader-mcp auth    # One-time OAuth setup
+npx teamleader-mcp          # Start the MCP server
+```
+
+### Global Install
+```bash
+npm install -g teamleader-mcp
+teamleader-mcp auth
+```
+
+### From Source
+```bash
+git clone https://github.com/Weichie-com/teamleader-mcp.git
+cd teamleader-mcp
+npm install
+npm run build
+```
+
+---
+
+## OAuth Setup
+
+### 1. Register Your Integration
+
+1. Go to [Teamleader Marketplace](https://marketplace.focus.teamleader.eu/build)
+2. Create a new integration
+3. Note your `client_id` and `client_secret`
+4. Set redirect URI: `http://localhost:3000/callback`
+5. Required scopes: `contacts`, `companies`, `deals`, `invoices`, `products`, `timetracking`, `events`, `users`
+
+### 2. Generate Tokens
+
+The easiest way:
+```bash
+node scripts/generate-token.js
+```
+
+Or manually via OAuth authorization code flow - see [OAUTH_CLAUDE_SETUP.md](OAUTH_CLAUDE_SETUP.md).
+
+### 3. Configure Environment
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+```bash
+TEAMLEADER_ACCESS_TOKEN=your_access_token
+TEAMLEADER_CLIENT_ID=your_client_id
+TEAMLEADER_CLIENT_SECRET=your_client_secret
+TEAMLEADER_REFRESH_TOKEN=your_refresh_token
+```
+
+---
+
+## Tools
+
+This server provides **42 tools** across all major Teamleader Focus features:
+
+### Companies (4 tools)
+| Tool | Description |
+|------|-------------|
+| `teamleader_companies_list` | List/search companies |
+| `teamleader_company_info` | Get company details |
+| `teamleader_company_create` | Create a company |
+| `teamleader_company_update` | Update a company |
+
+### Contacts (2 tools)
+| Tool | Description |
+|------|-------------|
+| `teamleader_contacts_list` | List/search contacts |
+| `teamleader_contact_info` | Get contact details |
+
+### Deals (7 tools)
+| Tool | Description |
+|------|-------------|
+| `teamleader_deals_list` | List deals with filters |
+| `teamleader_deal_info` | Get deal details |
+| `teamleader_deal_create` | Create a deal |
+| `teamleader_deal_update` | Update a deal |
+| `teamleader_deal_move` | Move to different phase |
+| `teamleader_deal_win` | Mark as won |
+| `teamleader_deal_lose` | Mark as lost |
+
+### Invoices (7 tools)
+| Tool | Description |
+|------|-------------|
+| `teamleader_invoices_list` | List invoices |
+| `teamleader_invoice_info` | Get invoice details |
+| `teamleader_invoice_draft` | Create draft invoice |
+| `teamleader_invoice_update` | Update invoice |
+| `teamleader_invoice_send` | Send via email |
+| `teamleader_invoice_book` | Book/finalize |
+| `teamleader_invoice_register_payment` | Register payment |
+| `teamleader_invoice_delete` | Delete invoice |
+
+### Quotations (7 tools)
+| Tool | Description |
+|------|-------------|
+| `teamleader_quotations_list` | List quotations |
+| `teamleader_quotation_info` | Get quotation details |
+| `teamleader_quotation_create` | Create quotation |
+| `teamleader_quotation_update` | Update quotation |
+| `teamleader_quotation_send` | Send via email |
+| `teamleader_quotation_accept` | Mark as accepted |
+| `teamleader_quotation_delete` | Delete quotation |
+| `teamleader_quotation_download` | Get PDF link |
+
+### Products (4 tools)
+| Tool | Description |
+|------|-------------|
+| `teamleader_products_list` | List products |
+| `teamleader_product_info` | Get product details |
+| `teamleader_product_create` | Create product |
+| `teamleader_product_update` | Update product |
+
+### Time Tracking (5 tools)
+| Tool | Description |
+|------|-------------|
+| `teamleader_timetracking_list` | List time entries |
+| `teamleader_timetracking_info` | Get entry details |
+| `teamleader_timetracking_add` | Add time entry |
+| `teamleader_timetracking_update` | Update entry |
+| `teamleader_timetracking_delete` | Delete entry |
+
+### Calendar Events (3 tools)
+| Tool | Description |
+|------|-------------|
+| `teamleader_events_list` | List events |
+| `teamleader_event_info` | Get event details |
+| `teamleader_event_create` | Create event |
+
+### Email Tracking (2 tools)
+| Tool | Description |
+|------|-------------|
+| `teamleader_emails_list` | List tracked emails |
+| `teamleader_email_track` | Log an email |
+
+---
+
+## Examples
+
+### Natural Language → Actions
+
+**"Find all open deals worth more than €10,000"**
+```
+→ teamleader_deals_list(status: ["open"])
+→ Filters results by value
+```
+
+**"Create an invoice for Acme Corp: 20 hours consulting at €125/hour, 30 days payment term"**
+```
+→ teamleader_companies_list(term: "Acme Corp")
+→ teamleader_invoice_draft(customer_id: "...", grouped_lines: [...])
+```
+
+**"Schedule a meeting with John from DataFlow next Tuesday at 2pm"**
+```
+→ teamleader_contacts_list(term: "John DataFlow")
+→ teamleader_event_create(title: "Meeting", starts_at: "...", contact_ids: [...])
+```
+
+### Direct Tool Calls
+
+```bash
+# List open deals
+mcporter call teamleader.teamleader_deals_list status='["open"]'
+
+# Get company info
+mcporter call teamleader.teamleader_company_info id="uuid-here"
+
+# Create a time entry
+mcporter call teamleader.teamleader_timetracking_add \
+  started_at="2026-01-31T09:00:00+01:00" \
+  ended_at="2026-01-31T12:00:00+01:00" \
+  description="Development work"
+```
+
+---
+
+## Configuration Options
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `TEAMLEADER_ACCESS_TOKEN` | Yes | OAuth access token |
+| `TEAMLEADER_CLIENT_ID` | No* | OAuth client ID |
+| `TEAMLEADER_CLIENT_SECRET` | No* | OAuth client secret |
+| `TEAMLEADER_REFRESH_TOKEN` | No* | OAuth refresh token |
+| `TEAMLEADER_TOKEN_STORAGE` | No | Custom token storage path |
+
+*Required for automatic token refresh (recommended)
+
+### Token Refresh Modes
+
+**Static Mode:** Only `ACCESS_TOKEN` set. Token expires after 1 hour. Manual refresh needed.
+
+**Auto Refresh Mode (Recommended):** All four OAuth variables set. Tokens refresh automatically 5 minutes before expiry.
+
+---
+
+## Troubleshooting
+
+<details>
+<summary><strong>Server hangs or times out</strong></summary>
+
+Make sure your config includes the `args` array:
+
+```json
+{
+  "command": "node",
+  "args": ["/path/to/teamleader-mcp/dist/index.js"]  // ← Required!
+}
+```
+</details>
+
+<details>
+<summary><strong>"Unknown tool" error</strong></summary>
+
+Tool names are prefixed with `teamleader_`. Use `teamleader_deal_info`, not `get-deal`.
+
+Run `mcporter list teamleader` to see all tools.
+</details>
+
+<details>
+<summary><strong>401 Unauthorized</strong></summary>
+
+Access tokens expire after 1 hour. Set up automatic refresh with all OAuth variables, or manually refresh your token.
+</details>
+
+<details>
+<summary><strong>Rate limiting errors</strong></summary>
+
+Teamleader allows 200 requests/minute. The server respects rate limit headers. Wait and retry, or reduce request frequency.
+</details>
+
+---
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+
+# Test
+npm test              # Watch mode
+npm run test:run      # Single run
+
+# Lint
+npm run lint
+```
+
+---
+
+## Contributing
+
+We welcome contributions! Here's how to help:
+
+### Bug Reports & Feature Requests
+- Open an issue with a clear description
+- Include steps to reproduce for bugs
+- For features, explain the use case
+
+### Pull Requests
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Make your changes
+4. Run tests: `npm test`
+5. Commit: `git commit -m 'Add amazing feature'`
+6. Push: `git push origin feature/amazing-feature`
+7. Open a Pull Request
+
+### Code Style
+- TypeScript with strict mode
+- Prettier for formatting
+- ESLint for linting
+- Descriptive commit messages
+
+### Adding New Tools
+1. Add the tool definition in `src/tools/`
+2. Implement the handler
+3. Add tests in `tests/`
+4. Update this README
+
+---
+
+## Roadmap
+
+- [x] npm package publication
+- [ ] Project management tools (milestones, tasks)
+- [ ] Webhook support for real-time updates
+- [ ] Batch operations
+- [ ] More filter options
+- [ ] Credit notes support
+
+See [ROADMAP.md](ROADMAP.md) for details.
+
+---
+
+## Related Resources
+
+- [Teamleader Focus API Documentation](https://developer.teamleader.eu/)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Teamleader Marketplace](https://marketplace.focus.teamleader.eu/)
+- [Claude Desktop](https://claude.ai/download)
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file.
+
+---
+
+## Acknowledgments
+
+Built with ❤️ using the [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic.
+
+---
+
+<p align="center">
+  <sub>Made by <a href="https://weichie.com">Weichie</a> • Star ⭐ if you find this useful!</sub>
+</p>

package/dist/auth/auth-server.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Local HTTP server for OAuth callback
+ *
+ * Starts a temporary server to receive the OAuth callback,
+ * exchanges the code for tokens, and shuts down.
+ */
+import { type OAuthConfig } from './oauth.js';
+export interface AuthServerResult {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+}
+/**
+ * Start a local server and wait for the OAuth callback
+ */
+export declare function startAuthServer(config: OAuthConfig, port?: number): Promise<AuthServerResult>;
+//# sourceMappingURL=auth-server.d.ts.map

package/dist/auth/auth-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-server.d.ts","sourceRoot":"","sources":["../../src/auth/auth-server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAyB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAErE,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE,MAAa,GAClB,OAAO,CAAC,gBAAgB,CAAC,CAsE3B"}