Development Guide¶

Set up your local development environment.

Prerequisites¶

Go 1.24+: Install Go
Docker: Install Docker
Make: Usually pre-installed on macOS/Linux

Setup¶

1. Clone Repository¶

Bash

git clone https://github.com/nirholas/mcp-notify.git
cd mcp-notify

2. Install Dependencies¶

Bash

make setup

This installs:

Go module dependencies
Development tools (golangci-lint, etc.)
Git hooks

3. Start Services¶

Bash

# Start PostgreSQL and Redis
docker compose up -d postgres redis

# Or start everything including the app
make dev

4. Run the Application¶

Bash

# With hot reload
make dev

# Without hot reload
go run ./cmd/mcp-notify

Project Structure¶

Text Only

.
├── api/                 # OpenAPI specification
├── cmd/                 # Application entrypoints
│   ├── mcp-notify/       # Main server
│   ├── mcp-notify-cli/   # CLI tool
│   └── mcp-notify-mcp/  # MCP server
├── internal/            # Private packages
│   ├── api/             # HTTP server
│   ├── config/          # Configuration
│   ├── db/              # Database layer
│   ├── diff/            # Diff engine
│   ├── notifier/        # Notification senders
│   ├── poller/          # Registry poller
│   └── subscription/    # Subscription manager
├── pkg/                 # Public packages
│   ├── client/          # Go SDK
│   └── types/           # Shared types
├── web/                 # Frontend dashboard
└── docs/                # Documentation

Make Commands¶

Command	Description
`make build`	Build all binaries
`make test`	Run tests
`make lint`	Run linters
`make dev`	Start development server
`make docker`	Build Docker image
`make docs`	Serve documentation locally
`make clean`	Clean build artifacts

Configuration¶

Copy the example config:

Bash

cp config.example.yaml config.yaml

Key settings for development:

YAML

server:
  port: 8080

database:
  url: postgres://postgres:postgres@localhost:5432/mcp_notify?sslmode=disable

redis:
  url: redis://localhost:6379

log:
  level: debug
  format: text

Database¶

Migrations¶

Bash

# Run migrations
make migrate-up

# Rollback
make migrate-down

# Create new migration
make migrate-create name=add_new_table

Reset Database¶

Bash

docker compose down -v
docker compose up -d postgres
make migrate-up

Testing¶

Unit Tests¶

Bash

make test

# With coverage
make test-coverage

Integration Tests¶

Bash

# Requires running services
make test-integration

E2E Tests¶

Bash

# Start services first
make dev

# In another terminal
make test-e2e

Debugging¶

VS Code¶

Launch configuration is provided in .vscode/launch.json:

JSON

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch Server",
      "type": "go",
      "request": "launch",
      "mode": "debug",
      "program": "${workspaceFolder}/cmd/mcp-notify"
    }
  ]
}

Delve¶

Bash

dlv debug ./cmd/mcp-notify

Documentation¶

Serve Locally¶

Bash

# Install mkdocs
pip install mkdocs-material

# Serve
mkdocs serve

Build¶

Bash

mkdocs build

Git Workflow¶

Branch Naming¶

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation
refactor/ - Code refactoring

Commit Messages¶

Follow Conventional Commits:

Text Only

feat: add telegram notification channel
fix: resolve race condition in poller
docs: update installation guide
refactor: simplify diff engine logic

Pull Request Process¶

Create feature branch from main
Make changes with tests
Run make lint test
Push and create PR
Wait for CI and review
Squash and merge