# Makefile Reference Guide
Complete reference for all Makefile commands in the Twenty CRM MCP Server project.
## Table of Contents
- [Setup & Configuration](#setup--configuration)
- [Development Commands](#development-commands)
- [Testing Commands](#testing-commands)
- [Build Commands](#build-commands)
- [Docker Commands](#docker-commands)
- [Kubernetes Commands](#kubernetes-commands)
- [Maintenance Commands](#maintenance-commands)
- [Utility Commands](#utility-commands)
- [Common Workflows](#common-workflows)
## Setup & Configuration
### `make help`
Display all available commands with descriptions.
```bash
make help
```
### `make setup`
Initial project setup - installs dependencies and creates `.env` file from template.
```bash
make setup
```
**What it does:**
- Runs `npm install`
- Creates `.env` from `.env.example` (if not exists)
- Prompts you to configure Twenty API key
**First-time setup:**
```bash
make setup
nano .env # Add your TWENTY_API_KEY
```
### `make check-env`
Verify environment variables are properly configured.
```bash
make check-env
```
**Checks:**
- `.env` file exists
- `TWENTY_API_KEY` is set (not placeholder)
### `make info`
Display project and system information.
```bash
make info
```
**Shows:**
- Image name and tag
- Port configurations
- Environment status
- Installed tool versions (Node, Docker, kubectl, k3d)
## Development Commands
### `make dev`
Start development server with auto-reload and MCP Inspector.
```bash
make dev
```
**What it does:**
1. Checks environment configuration
2. Builds TypeScript project
3. Starts server on port 5008
4. Opens MCP Inspector
**Access:**
- Server: http://localhost:5008
- MCP Inspector: http://localhost:6274
### `make start`
Start production server (no auto-reload).
```bash
make start
```
Use this for production-like testing.
### `make watch`
Watch for file changes and auto-rebuild (requires `fswatch` or `inotifywait`).
```bash
make watch
```
**Note:** Install file watching tool first:
- macOS: `brew install fswatch`
- Linux: `apt-get install inotify-tools`
### `make inspect`
Open MCP Inspector only (server must be running).
```bash
make inspect
```
Opens http://localhost:6274 in your browser.
## Testing Commands
### `make test`
Run all tests once.
```bash
make test
```
Equivalent to: `npm test`
### `make test-watch`
Run tests in watch mode (auto-rerun on changes).
```bash
make test-watch
```
Great for TDD workflow.
### `make test-coverage`
Run tests with coverage report.
```bash
make test-coverage
```
Generates coverage report in `coverage/` directory.
### `make test-ui`
Open interactive test UI.
```bash
make test-ui
```
Opens Vitest UI for visual test exploration.
## Build Commands
### `make build`
Build TypeScript project to JavaScript.
```bash
make build
```
**Output:** `build/` directory
### `make all`
Run full build pipeline: install → build → test.
```bash
make all
```
Use this to verify everything works.
### `make ci`
Run CI pipeline: install → build → lint → test.
```bash
make ci
```
Simulates CI/CD environment checks.
## Docker Commands
### `make docker-build`
Build Docker image.
```bash
make docker-build
```
**Creates:** `twenty-crm-mcp-server:latest`
### `make docker-run`
Build and run Docker container.
```bash
make docker-run
```
**What it does:**
1. Builds Docker image (if needed)
2. Runs container in detached mode
3. Maps port 5008:8080
4. Loads environment from `.env` file
**Container name:** `twenty-crm-mcp-server`
### `make docker-stop`
Stop and remove Docker container.
```bash
make docker-stop
```
### `make docker-clean`
Stop container and remove Docker image.
```bash
make docker-clean
```
Use this for complete cleanup.
### `make docker-logs` / `make logs`
Show Docker container logs (follow mode).
```bash
make docker-logs
# or
make logs
```
Press `Ctrl+C` to exit.
### `make docker-shell`
Open interactive shell in running container.
```bash
make docker-shell
```
Useful for debugging.
## Kubernetes Commands
### `make k3d-setup`
Create local k3d cluster (one-time setup).
```bash
make k3d-setup
```
**Creates cluster:** `twenty-crm-cluster`
**Requirements:** k3d installed
### `make k3d-delete`
Delete local k3d cluster.
```bash
make k3d-delete
```
### `make k3d-import`
Build Docker image and import to k3d cluster.
```bash
make k3d-import
```
Required before deploying to k3d.
### `make k8s-secret`
Create Kubernetes secret for Twenty API key.
```bash
make k8s-secret
```
**Creates:** `twenty-crm-secrets` secret in default namespace
Reads `TWENTY_API_KEY` from `.env` file.
### `make k8s-deploy` / `make deploy`
Full deployment to Kubernetes.
```bash
make deploy
```
**What it does:**
1. Builds and imports image to k3d
2. Creates API key secret
3. Applies k8s/deployment.yaml
4. Shows deployment status
### `make k8s-status`
Check Kubernetes deployment status.
```bash
make k8s-status
```
**Shows:**
- Deployment status
- Pod status
- Service status
### `make k8s-logs`
Show logs from Kubernetes pod.
```bash
make k8s-logs
```
Follows logs in real-time.
### `make k8s-shell`
Open shell in Kubernetes pod.
```bash
make k8s-shell
```
### `make k8s-restart`
Restart Kubernetes deployment.
```bash
make k8s-restart
```
Triggers rolling restart.
### `make k8s-delete`
Delete Kubernetes deployment.
```bash
make k8s-delete
```
## Maintenance Commands
### `make clean`
Clean build artifacts.
```bash
make clean
```
**Removes:**
- `build/` directory
- `coverage/` directory
- `node_modules/.cache/`
### `make clean-all`
Clean everything including node_modules.
```bash
make clean-all
```
**Warning:** Requires reinstall after this.
### `make update`
Update npm dependencies.
```bash
make update
```
Runs `npm update`.
### `make audit`
Run npm security audit.
```bash
make audit
```
### `make audit-fix`
Automatically fix security vulnerabilities.
```bash
make audit-fix
```
### `make lint`
Run code linter (if ESLint is configured).
```bash
make lint
```
### `make format`
Format code (if Prettier is installed).
```bash
make format
```
## Utility Commands
### `make health`
Check server health endpoint.
```bash
make health
```
Queries http://localhost:5008/health
**Response:** JSON with server status
### `make install`
Install npm dependencies only.
```bash
make install
```
Runs `npm install`.
## Common Workflows
### First-Time Setup
```bash
# 1. Initial setup
make setup
# 2. Configure API key
nano .env
# 3. Verify configuration
make check-env
# 4. Start development
make dev
```
### Daily Development
```bash
# Start server
make dev
# In another terminal - run tests
make test-watch
# Make changes, server auto-reloads
```
### Testing Changes
```bash
# Run all tests
make test
# Check coverage
make test-coverage
# Build to verify
make build
```
### Docker Development
```bash
# Build and run in Docker
make docker-run
# Check logs
make docker-logs
# Check health
make health
# Stop when done
make docker-stop
```
### Kubernetes Deployment
```bash
# First-time setup
make k3d-setup
# Deploy
make deploy
# Check status
make k8s-status
# View logs
make k8s-logs
# Access locally (port-forward)
kubectl port-forward svc/twenty-crm-mcp-server-service 5008:80
```
### Full CI Pipeline
```bash
# Run complete CI checks
make ci
# Or step by step:
make install
make build
make lint
make test
```
### Cleanup
```bash
# Clean build artifacts
make clean
# Stop Docker container
make docker-stop
# Delete k8s deployment
make k8s-delete
# Delete k3d cluster
make k3d-delete
```
### Troubleshooting
```bash
# Check environment
make check-env
# View system info
make info
# Clean and rebuild
make clean-all
make setup
make build
# Check server health
make health
# View logs
make docker-logs # for Docker
make k8s-logs # for Kubernetes
```
## Environment Variables
The Makefile uses these environment variables:
| Variable | Default | Description |
|----------|---------|-------------|
| `IMAGE_NAME` | `twenty-crm-mcp-server` | Docker image name |
| `IMAGE_TAG` | `latest` | Docker image tag |
| `PORT` | `5008` | External port |
| `DOCKER_PORT` | `8080` | Container internal port |
| `K3D_CLUSTER` | `twenty-crm-cluster` | k3d cluster name |
| `NAMESPACE` | `default` | Kubernetes namespace |
Override with environment variables:
```bash
PORT=9000 make dev
IMAGE_TAG=v1.0.0 make docker-build
NAMESPACE=production make deploy
```
## Tips & Best Practices
### 1. Always check environment first
```bash
make check-env
```
### 2. Use `make help` when in doubt
```bash
make help
```
### 3. Clean build for troubleshooting
```bash
make clean && make build
```
### 4. Check logs for errors
```bash
make docker-logs # or make k8s-logs
```
### 5. Use `make info` to verify setup
```bash
make info
```
### 6. Test before deploying
```bash
make test && make docker-run
```
### 7. Keep dependencies updated
```bash
make update
make audit
```
## Quick Reference
**Setup:** `make setup`
**Dev:** `make dev`
**Test:** `make test`
**Build:** `make build`
**Docker:** `make docker-run`
**Deploy:** `make deploy`
**Status:** `make k8s-status`
**Logs:** `make logs` or `make k8s-logs`
**Clean:** `make clean`
**Help:** `make help`
**Info:** `make info`
## Getting More Help
- Run `make help` for command list
- Run `make info` for system information
- See [README.md](README.md) for detailed documentation
- See [QUICKSTART.md](QUICKSTART.md) for step-by-step guide
- Check logs with `make docker-logs` or `make k8s-logs`
