tailscale-mcp 2026.3.15

package/.env.example

@@ -0,0 +1,17 @@
+# Authentication — use API key OR OAuth (not both)
+# Option 1: API key
+TAILSCALE_API_KEY=your-api-key-here
+
+# Option 2: OAuth client credentials (takes priority over API key)
+# TAILSCALE_OAUTH_CLIENT_ID=your-oauth-client-id
+# TAILSCALE_OAUTH_CLIENT_SECRET=your-oauth-client-secret
+
+TAILSCALE_TAILNET=your-tailnet-name
+TAILSCALE_API_URL=https://api.tailscale.com
+TAILSCALE_TIMEOUT=30000
+
+# Transport — stdio (default) or sse
+# TAILSCALE_MCP_TRANSPORT=sse
+# TAILSCALE_MCP_AUTH_TOKEN=your-mcp-auth-token
+# TAILSCALE_MCP_PORT=3000
+# TAILSCALE_MCP_HOST=localhost

package/ARCHITECTURE.md

@@ -0,0 +1,220 @@
+# Architecture
+
+This document describes the architecture of mcp-tailscale — from the current single-runtime design to the target multi-component architecture.
+
+## Current Architecture
+
+mcp-tailscale is a single-process MCP server that translates MCP tool calls into Tailscale API v2 requests.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        MCP Client                               │
+│              (Claude Code, AI Agent, Custom)                    │
+└──────────────────────────┬──────────────────────────────────────┘
+                           │ MCP Protocol (stdio or SSE)
+                           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    mcp-tailscale Runtime                         │
+│                                                                 │
+│  ┌──────────┐  ┌──────────┐  ┌──────────────────────────────┐  │
+│  │Transport │  │  Tool    │  │     Tailscale Client         │  │
+│  │ stdio/SSE│──│ Registry │──│  (API Key or OAuth)          │  │
+│  │  + Auth  │  │ 48 tools │  │  Bearer token, auto-refresh  │  │
+│  └──────────┘  └──────────┘  └──────────────┬───────────────┘  │
+│                                              │                  │
+│  ┌──────────┐  ┌──────────┐                  │                  │
+│  │Validation│  │  Error   │                  │                  │
+│  │   (Zod)  │  │ Handling │                  │                  │
+│  └──────────┘  └──────────┘                  │                  │
+└──────────────────────────────────────────────┼──────────────────┘
+                                               │ HTTPS
+                                               ▼
+                                ┌──────────────────────────┐
+                                │   Tailscale API v2       │
+                                │ api.tailscale.com        │
+                                └──────────────┬───────────┘
+                                               │
+                                               ▼
+                                ┌──────────────────────────┐
+                                │   Your Tailnet           │
+                                │  Devices, DNS, ACL, ...  │
+                                └──────────────────────────┘
+```
+
+### Components
+
+| Component | File | Responsibility |
+|-----------|------|----------------|
+| Transport | `src/index.ts`, `src/transport.ts` | stdio/SSE transport, Bearer auth middleware |
+| Tool Registry | `src/tools/*.ts` | 48 tools across 9 domains, Zod input schemas |
+| Tailscale Client | `src/client/tailscale-client.ts` | HTTP client, API key Bearer auth |
+| OAuth Client | `src/client/tailscale-oauth-client.ts` | OAuth credentials, token auto-refresh |
+| Client Factory | `src/client/client-factory.ts` | Selects auth method (OAuth > API key) |
+| Validation | `src/utils/validation.ts` | Shared Zod schemas (device IDs, CIDR, domains) |
+| Error Handling | `src/utils/errors.ts` | TailscaleApiError, credential-safe messages |
+| Types | `src/client/types.ts` | API response types, ITailscaleClient interface |
+
+### Data Flow
+
+```
+1. MCP Client sends tool call (e.g., tailscale_device_list)
+2. Transport layer receives and routes to tool handler
+3. Zod schema validates input parameters
+4. Tool handler calls TailscaleClient method
+5. Client adds Bearer token, sends HTTPS request to api.tailscale.com
+6. API response is typed and returned as JSON text content
+7. On error: TailscaleApiError extracts message without leaking credentials
+```
+
+## Target Architecture
+
+As mcp-tailscale evolves from a single runtime into a product platform, the architecture separates into three distinct layers:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        MCP Clients                              │
+│         Claude Code  ·  AI Agents  ·  Custom Apps               │
+└──────────────────────────┬──────────────────────────────────────┘
+                           │ MCP Protocol
+                           ▼
+┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─┐
+│                    Cloud Layer (Future)                         │
+│                                                                 │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
+│  │  Admin       │  │   Fleet      │  │    Observability     │  │
+│  │  Console     │  │   Manager    │  │    (Logs, Metrics)   │  │
+│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
+│                                                                 │
+ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┬ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
+                           │
+┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─┐
+│                Enterprise Layer                                 │
+│                                                                 │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐   │
+│  │   RBAC   │  │   SSO    │  │  Audit   │  │   Policy     │   │
+│  │          │  │OIDC/SAML │  │  Events  │  │   Engine     │   │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────────┘   │
+│                                                                 │
+ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┬ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
+                           │
+┌──────────────────────────┼──────────────────────────────────────┐
+│                    Core Runtime (OSS)                            │
+│                                                                 │
+│  ┌──────────┐  ┌──────────┐  ┌──────────────────────────────┐  │
+│  │Transport │  │  Tool    │  │     API Clients              │  │
+│  │ stdio/SSE│  │ Registry │  │  Tailscale · (Extensible)    │  │
+│  └──────────┘  └──────────┘  └──────────────────────────────┘  │
+│                                                                 │
+│  ┌──────────┐  ┌──────────┐  ┌──────────────────────────────┐  │
+│  │Validation│  │  Error   │  │     Plugin / Connector SDK   │  │
+│  │   (Zod)  │  │ Handling │  │  (Future)                    │  │
+│  └──────────┘  └──────────┘  └──────────────────────────────┘  │
+└──────────────────────────┬──────────────────────────────────────┘
+                           │ HTTPS
+                           ▼
+                ┌──────────────────────────┐
+                │   Infrastructure APIs    │
+                │  Tailscale · (Others)    │
+                └──────────────────────────┘
+```
+
+### Layer Responsibilities
+
+| Layer | Scope | Repository | License |
+|-------|-------|------------|---------|
+| **Core Runtime** | Execution — MCP protocol, tool registry, API clients, validation | `mcp-tailscale` (public) | AGPL-3.0 |
+| **Enterprise** | Governance — RBAC, SSO, audit, policy engine, multi-tenancy | Private (future) | Commercial |
+| **Cloud** | Operations — Hosted control plane, fleet management, observability | Private (future) | Commercial SaaS |
+
+### Boundary Definitions
+
+**Core Runtime** is the execution engine. It handles:
+- MCP protocol negotiation (stdio/SSE)
+- Tool discovery and invocation
+- Input validation and error handling
+- API client authentication and requests
+- Plugin/connector lifecycle (future)
+
+**Enterprise Layer** wraps the Core Runtime with governance:
+- Who can use which tools (RBAC)
+- How users authenticate (SSO)
+- What happened and when (Audit)
+- What is allowed and what is not (Policy)
+- Isolation between teams (Multi-tenancy)
+
+**Cloud Layer** manages fleets of Enterprise instances:
+- Deployment and scaling of gateway instances
+- Centralized monitoring and alerting
+- Configuration management across instances
+- Usage tracking and billing
+
+### Security Model
+
+```
+MCP Client
+    │
+    ▼
+Transport Auth ──── Bearer token (SSE) or process isolation (stdio)
+    │
+    ▼
+[Enterprise: RBAC] ── Role check: does this identity have access to this tool?
+    │
+    ▼
+[Enterprise: Policy] ── Policy check: is this operation allowed right now?
+    │
+    ▼
+Tool Execution ──── Zod validates input, tool handler runs
+    │
+    ▼
+[Enterprise: Audit] ── Log: who, what, when, result
+    │
+    ▼
+API Client Auth ──── Bearer token (API key) or OAuth (auto-refresh)
+    │
+    ▼
+Tailscale API ──── HTTPS to api.tailscale.com
+```
+
+Items in `[brackets]` are enterprise layer additions — the Core Runtime operates without them.
+
+## Technology Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Runtime | Node.js ≥ 20 | Native ES modules, broad MCP SDK support |
+| Language | TypeScript (strict) | Type safety, IDE support, refactoring confidence |
+| Validation | Zod | Runtime + compile-time validation, composable schemas |
+| HTTP Client | Axios | Interceptors for auth, timeout, error handling |
+| Transport | stdio + SSE (Express) | stdio for local, SSE for remote/multi-client |
+| Testing | Vitest | Fast, TypeScript-native, ESM support |
+| Auth | API key + OAuth | API key for humans, OAuth for services |
+
+## File Structure
+
+```
+src/
+  index.ts                    # Entry point — server setup, tool registration
+  transport.ts                # Transport config + SSE auth middleware
+  client/
+    tailscale-client.ts       # API key HTTP client
+    tailscale-oauth-client.ts # OAuth client (auto-refresh)
+    client-factory.ts         # Auth method selection
+    types.ts                  # API types + ITailscaleClient interface
+  tools/
+    devices.ts                # 11 device management tools
+    dns.ts                    # 8 DNS tools
+    acl.ts                    # 5 ACL tools
+    keys.ts                   # 4 auth key tools
+    tailnet.ts                # 5 tailnet tools
+    users.ts                  # 2 user tools
+    webhooks.ts               # 4 webhook tools
+    posture.ts                # 4 posture integration tools
+    diagnostics.ts            # 5 diagnostics tools
+  utils/
+    validation.ts             # Shared Zod schemas
+    errors.ts                 # Error extraction, TailscaleApiError
+tests/                        # Vitest unit tests (mocked API)
+docs/
+  plans/                      # Design documents
+  api-reference.md            # Tailscale API v2 endpoint mapping
+```

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+This project uses [Calendar Versioning](https://calver.org/) (`YYYY.MM.DD.TS`).
+
+
+## v2026.03.15.5
+
+- Publish to npm as `@itunified/mcp-tailscale`, add `.npmignore`, `bin` entry, expanded keywords (#12)
+- Update package.json version to `2026.3.15`, description aligned with product positioning
+
+## v2026.03.15.4
+
+- Add product positioning docs: restructured README, ROADMAP.md, ARCHITECTURE.md, PRODUCT_PACKAGING.md (#29)
+
+## v2026.03.15.3
+
+- Switch Glama badge from score to card format (#11)
+
+## v2026.03.15.2
+
+- Add Glama registry badge to README (#11)
+
+## v2026.03.15.1
+
+- fix: use `/acl/validate` endpoint for `acl_test` tool — nonexistent `/acl/test` returned 404 (#17)
+- fix: remove unsupported `"generic"` webhook provider type, make `providerType` optional (#18)
+
+## v2026.03.14.9
+
+- Add skill documentation to README and `.claude/skills/README.md` per ADR-0022 (#23)
+
+## v2026.03.14.8
+
+- Add `docs/superpowers/` to `.gitignore` per ADR-0021 (#21)
+
+## v2026.03.14.7
+
+- Update design doc 001 status from Draft to Accepted (#19)
+
+## v2026.03.14.6
+
+- **Tier 2 Enhancement: HTTP/SSE transport with Bearer token auth** (#14)
+  - Add SSE transport as opt-in alternative to stdio (`TAILSCALE_MCP_TRANSPORT=sse`)
+  - Mandatory `TAILSCALE_MCP_AUTH_TOKEN` for SSE — server refuses to start without it
+  - Timing-safe token comparison via `crypto.timingSafeEqual()`
+  - Add `express` dependency (runtime deps: 3 → 4)
+  - 188 unit tests (was 178)
+  - Design doc: `docs/plans/002-tier2-enhancement.md`
+
+## v2026.03.14.5
+
+- **Tier 2 Enhancement: Device expire/rename + posture integration tools** (#13)
+  - Add `tailscale_device_expire` — force device key expiry (+1 tool)
+  - Add `tailscale_device_rename` — set device display name (+1 tool)
+  - Add posture integration tools: `tailscale_posture_integration_list`, `tailscale_posture_integration_get`, `tailscale_posture_integration_create`, `tailscale_posture_integration_delete` (+4 tools)
+  - Total: 42 → 48 tools across 9 domains
+  - 178 unit tests (was 158)
+  - Design doc: `docs/plans/002-tier2-enhancement.md`
+
+## v2026.03.14.4
+
+- **Tier 1 Enhancement: OAuth, Users, Webhooks, Tailnet Settings Write** (#7)
+  - Add OAuth client credentials auth support (`TAILSCALE_OAUTH_CLIENT_ID` + `TAILSCALE_OAUTH_CLIENT_SECRET`)
+  - Add `ITailscaleClient` interface and `client-factory.ts` for dual auth (OAuth > API key)
+  - Add user management tools: `tailscale_user_list`, `tailscale_user_get` (+2 tools)
+  - Add webhook management tools: `tailscale_webhook_list`, `tailscale_webhook_create`, `tailscale_webhook_get`, `tailscale_webhook_delete` (+4 tools)
+  - Add `tailscale_tailnet_settings_update` tool (+1 tool)
+  - Total: 35 → 42 tools across 8 domains
+  - 149 unit tests (was 110)
+  - Update README, CLAUDE.md, api-reference.md, .env.example
+  - Add design doc `docs/plans/001-tier1-enhancement.md`
+
+## v2026.03.14.3
+
+- Add acceptance criteria gate to CLAUDE.md PR Workflow (ADR-0017) (#8)
+
+## v2026.03.14.2
+
+- Clarify license: internal/commercial use requires commercial license (#5)
+
+## v2026.03.14.1
+
+- 35 tools across 6 domains: Devices (9), DNS (8), ACL (5), Keys (4), Tailnet (4), Diagnostics (5) (#1)
+- TailscaleClient with Bearer token auth, tailnet-scoped API paths, direct JSON responses (#1)
+- 6 skills: dns-management, health (/ts-health), device-management, acl-management, key-management, onboarding (#1)
+- 110 unit tests with vitest, all passing (#1)
+- Zod input validation on all tools, structured error handling with TailscaleApiError (#1)
+
+## v2026.03.13.1
+
+- Initial project scaffold: TailscaleClient, validation schemas, error handling
+- Repository setup: package.json, tsconfig, CLAUDE.md, README, SECURITY.md (#1)

package/CLAUDE.md

@@ -0,0 +1,180 @@
+# mcp-tailscale — CLAUDE.md
+
+## Table of Contents
+
+- [Project Overview](#project-overview)
+- [Architecture](#architecture)
+- [Code Conventions](#code-conventions)
+- [Security](#security)
+- [Design/Plan Documents — MANDATORY](#designplan-documents--mandatory)
+- [CHANGELOG.md — MANDATORY](#changelogmd--mandatory)
+- [Versioning & Releases (CalVer)](#versioning--releases-calver)
+- [Git Workflow](#git-workflow)
+- [Language](#language)
+- [Development Setup](#development-setup)
+- [Testing](#testing)
+
+## Project Overview
+
+Slim Tailscale MCP Server for managing devices, DNS/Split DNS, ACL policies, auth keys, users, webhooks, and tailnet settings via Tailscale API v2.
+
+**No SSH. No shell execution. API-only. 4 runtime dependencies.**
+
+## Architecture
+
+```
+src/
+  index.ts                   # MCP Server entry point (stdio + SSE transport)
+  transport.ts               # Transport config validation + auth middleware
+  client/
+    tailscale-client.ts      # Axios HTTP client (API key Bearer token auth)
+    tailscale-oauth-client.ts # OAuth client credentials auth (auto-refresh)
+    client-factory.ts        # Client selection (OAuth > API key) from env vars
+    types.ts                 # Tailscale API v2 response types + ITailscaleClient interface
+  tools/
+    devices.ts               # Device management tools (11 tools)
+    dns.ts                   # DNS nameservers, search paths, split DNS, preferences (8 tools)
+    acl.ts                   # ACL policy management (5 tools)
+    keys.ts                  # Auth key management (4 tools)
+    tailnet.ts               # Tailnet settings (read/write), contacts, lock status (5 tools)
+    users.ts                 # User management tools (2 tools)
+    webhooks.ts              # Webhook management tools (4 tools)
+    posture.ts               # Posture integration tools (4 tools)
+    diagnostics.ts           # Status, API verify, log streaming, DERP map (5 tools)
+  utils/
+    validation.ts            # Shared Zod schemas (device IDs, CIDR, domains, etc.)
+    errors.ts                # Tailscale error extraction and TailscaleApiError
+tests/                       # Vitest unit tests
+docs/
+  plans/                     # Design/plan documents
+  api-reference.md           # Tailscale API v2 endpoint mapping
+```
+
+## Code Conventions
+
+### TypeScript
+- Strict mode enabled (`"strict": true` in tsconfig.json)
+- All tool parameters validated with Zod schemas
+- Generically typed API client (`get<T>()`, `post<T>()`, `put<T>()`, `patch<T>()`, `delete<T>()`, `deleteVoid()`, `postVoid()`)
+- No `any` types — use `unknown` and narrow
+
+### Tool Design
+- **Granular tools**: one MCP tool per operation (e.g., `tailscale_device_routes_set`)
+- Tool naming: `tailscale_<domain>_<action>`
+- Each tool has its own Zod input schema and clear description
+- Destructive operations require `confirm: true` parameter
+- Response format: always `{ content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }`
+
+### Tailscale API Specifics
+- Auth: Bearer token (API key), not Global API Key
+- Base URL: `https://api.tailscale.com/api/v2`
+- Response format: Direct JSON — no `{ success, errors, result }` wrapper
+- Tailnet required: Most endpoints use `/tailnet/{tailnet}/` prefix
+- Device endpoints: `/device/{deviceId}/` (not tailnet-scoped)
+
+### Dependencies
+- **4 runtime dependencies**: `@modelcontextprotocol/sdk`, `axios`, `express`, `zod`
+- No SSH libraries, no Redis, no PostgreSQL
+- Dev: `typescript`, `vitest`, `@types/node`
+
+## Security
+
+- **Transport**: stdio (default) or SSE with mandatory Bearer token auth (`crypto.timingSafeEqual`)
+- **Authentication**: API Key exclusively via environment variables. Never hardcoded, logged, or committed.
+- **No SSH**: Exclusively Tailscale REST API v2
+- **Input validation**: Zod schemas for all tool parameters
+- **Error handling**: No credential leaks in error messages (Bearer token never appears in logs or errors)
+- **Credentials**: Never hardcoded, never logged, never in git
+- **Secret Redaction — MANDATORY**: When using `grep`, `cat`, `sed`, `awk`, shell scripts, or any tool that reads/displays file contents containing secrets (`.env`, credentials, API keys, tokens, passwords), **ALWAYS redact the secret values** in output. Never display raw secret values in terminal output, logs, conversation context, or commit messages.
+- **Public Repo Documentation Policy — MANDATORY**: This is a **public repository**. All documentation, code examples, test data, and commit messages MUST use only generic placeholders:
+  - Tailnet names: `your-tailnet-name`, `example.com`
+  - Device IDs: `123456789`
+  - API keys: `your-api-key-here`, `tskey-api-test`
+  - Emails: `admin@example.com`, `user@example.com`
+  - IPs: `100.64.0.1`, `10.0.0.0/8` (Tailscale CGNAT range is acceptable as generic example)
+  - **NEVER** include real tailnet names, device IDs, API keys, or internal topology
+  - Infrastructure-specific documentation belongs in the private `itunified-io/infrastructure` repo
+
+## Design/Plan Documents — MANDATORY
+
+- **Every significant change MUST have a design/plan document** in `docs/plans/`
+- Naming: `docs/plans/<NNN>-<short-description>.md`
+- The design doc MUST be referenced in the corresponding GitHub issue (bidirectional link)
+- Design docs contain: problem, solution, prerequisites, execution steps, rollback, verification
+- Trivial changes (typos, minor doc updates) are exempt
+
+## CHANGELOG.md — MANDATORY
+
+- **`CHANGELOG.md` MUST exist and MUST be kept up to date**
+- **Every PR merge MUST add a new entry** before tagging/releasing
+- Format: CalVer date header (`## v2026.03.13.1`) followed by a list of changes with issue references
+- Never skip CHANGELOG updates — they are the source of truth for what changed and when
+
+## Versioning & Releases (CalVer)
+
+- Schema: `YYYY.MM.DD.TS` (e.g., `2026.03.13.1`)
+- `package.json`: npm-compatible without leading zeros (`2026.3.13`)
+- Git tags: `v2026.03.13.1` (leading zeros for sorting)
+
+### Release Workflow — MANDATORY after every PR merge
+1. **Update CHANGELOG.md** with new version entry
+2. Update `package.json` version if date changed
+3. Create annotated git tag: `git tag -a v2026.03.13.1 -m "v2026.03.13.1: <summary>"`
+4. Push tag: `git push origin --tags`
+5. Create GitHub release: `gh release create v2026.03.13.1 --title "v2026.03.13.1 — <title>" --notes "<release notes>"`
+6. Release notes must list what changed and reference closed issues
+
+## Git Workflow
+
+- **NEVER work on main** — all changes via feature branches + PR
+- **Branching**: `feature/<issue-nr>-<description>`, `fix/<issue-nr>-<description>`, `chore/<description>`
+- **Worktree naming**: `.claude/worktrees/<branch-name>`
+- **GitHub Issues mandatory**: every change must have an associated GH issue
+- **Commit messages**: must reference GH issue — `feat: add device posture tools (#3)` or `fix: handle 404 on device delete (#5)`
+- **No commit without issue reference** (exceptions: initial setup, typo fixes)
+- **PR workflow**: feature branch -> `gh pr create` -> review -> merge into main
+- **Acceptance Criteria Gate — MANDATORY** (see [ADR-0017](https://github.com/itunified-io/infrastructure/blob/main/docs/adr/0017-acceptance-criteria-before-merge.md)):
+  - All acceptance criteria in the associated GH issue MUST be checked and verified as successful before merge to `main`
+  - Verification is active: criteria must be actually tested, not assumed to pass
+  - Includes: tests pass (`npm test`), build succeeds (`npm run build`), live tests pass (`/ts-test`), CHANGELOG updated, docs updated
+  - If any criterion cannot be satisfied, the PR must NOT be merged
+- **After PR merge: branch/worktree cleanup is mandatory** — `git branch -d <branch>`, `git remote prune origin`, remove worktree
+
+### Bug Fixes — MANDATORY Workflow
+- **Every bug fix MUST have a GitHub issue** with appropriate labels (`bug`, scope labels)
+- Issue-first: create issue → branch (`fix/<issue-nr>-<description>`) → fix → PR → merge
+- Bug fix commits must reference the issue: `fix: <description> (#<nr>)`
+- CHANGELOG entry required for every bug fix
+
+## Language
+
+- All documentation, code comments, commit messages: **English only**
+
+## Development Setup
+
+```bash
+# Prerequisites: Node.js >= 20, npm
+
+# Install dependencies
+npm install
+
+# Copy and configure environment
+cp .env.example .env
+# Edit .env with your Tailscale API key and tailnet name
+
+# Build
+npm run build
+
+# Test
+npm test
+
+# Run (stdio transport)
+node dist/index.js
+```
+
+## Testing
+
+- Unit tests with vitest (mocked API responses)
+- Zod schema validation for invalid inputs
+- Error handling for API errors (401, 403, 404, 500)
+- Run: `npm test`

package/COMMERCIAL_LICENSE.md

@@ -0,0 +1,44 @@
+# Commercial License
+
+## mcp-tailscale — Commercial Licensing
+
+This project is dual-licensed:
+
+1. **Open Source** — [GNU Affero General Public License v3.0 (AGPL-3.0)](LICENSE)
+2. **Commercial** — Available for organizations that cannot or prefer not to comply with AGPL-3.0 terms
+
+## When You Need a Commercial License
+
+The AGPL-3.0 requires that if you modify this software or use it as part of a network service, you must make the complete source code of your application available under the AGPL-3.0. A commercial license removes this requirement.
+
+You likely need a commercial license if:
+
+- You integrate mcp-tailscale into a **proprietary product or service**
+- You offer mcp-tailscale as part of a **managed or SaaS platform** without releasing your source code
+- You **modify** the software and do not want to release your modifications under AGPL-3.0
+- Your organization's **legal or compliance policies** prohibit use of AGPL-licensed software
+
+## When You Do NOT Need a Commercial License
+
+- **Personal or non-commercial use** — using the software for personal projects or non-commercial purposes
+- **Open-source projects** — integrating with other AGPL-3.0 or compatible open-source projects
+- **Unmodified use** — running the unmodified MCP server to manage your own Tailscale tailnet
+
+## Obtaining a Commercial License
+
+Contact us to discuss commercial licensing options:
+
+- **GitHub Sponsors**: <https://github.com/sponsors/itunified-io>
+
+Commercial licenses are priced based on scope and usage. Sponsoring the project through GitHub Sponsors is the primary way to support development and obtain commercial terms.
+
+## FAQ
+
+**Q: Can I use mcp-tailscale for free in my company?**
+A: Only if you fully comply with the AGPL-3.0 license terms, which requires making your complete source code available under AGPL-3.0. If your company uses mcp-tailscale internally for commercial operations and does not want to release its source code, a commercial license is required.
+
+**Q: Does the AGPL apply if I just run the MCP server internally?**
+A: Running the server internally within a commercial organization requires either full AGPL-3.0 compliance (including releasing your source code) or a commercial license. The AGPL-3.0 free use is intended for personal and non-commercial purposes only.
+
+**Q: What if I build a product that includes mcp-tailscale?**
+A: If your product is proprietary (closed-source), you need a commercial license. If your product is also AGPL-3.0 licensed, you can use it under the open-source license.

package/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to mcp-tailscale
+
+Thank you for your interest in contributing!
+
+## Workflow
+
+1. **Issue first** — Create a GitHub issue describing the change before starting work
+2. **Fork & branch** — Fork the repo, create a feature branch: `feature/<issue-nr>-<description>`
+3. **Develop** — Write code, add tests, update documentation
+4. **Test** — Ensure all tests pass: `npm test`
+5. **PR** — Create a pull request referencing the issue
+
+## Branch Naming
+
+- `feature/<issue-nr>-<description>` — New features
+- `fix/<issue-nr>-<description>` — Bug fixes
+- `chore/<description>` — Maintenance tasks
+
+## Commit Messages
+
+Use conventional commits with issue references:
+
+```
+feat: add device posture tools (#12)
+fix: handle 404 on device delete gracefully (#5)
+chore: update dependencies
+```
+
+## Code Standards
+
+- TypeScript strict mode
+- All tool parameters validated with Zod schemas
+- No `any` types
+- No SSH or shell execution
+- Credentials only via environment variables
+- Tests for all new tools
+- Tool naming: `tailscale_<domain>_<action>`
+
+## Documentation
+
+- All documentation MUST use generic placeholders only (see CLAUDE.md Security section)
+- No real tailnet names, device IDs, API keys, or internal topology in any file
+- Use `your-tailnet-name`, `your-api-key-here`, `example.com`
+
+## Review
+
+- All PRs require code review before merging
+- Tests must pass
+- Documentation must be updated (especially README.md)
+- CHANGELOG.md must be updated before tagging/releasing
+
+## After Merge
+
+Branch and worktree cleanup is mandatory after PR merge to prevent drift.