┌─────────────────────────────────────────────────────────────────┐
│         Claude / ChatGPT / Gemini / Copilot / Cursor            │
└─────────────────────────────────────────────────────────────────┘
                                │
                                │ MCP Protocol (HTTP JSON-RPC)
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Skills MCP Hudu Server                        │
│                        localhost:3100                            │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │                      Express + MCP SDK                     │ │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐      │ │
│  │  │Companies │ │  Assets  │ │Passwords │ │ Articles │      │ │
│  │  │          │ │          │ │          │ │          │      │ │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘      │ │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐      │ │
│  │  │ Networks │ │Procedures│ │  Racks   │ │  Search  │      │ │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘      │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                │ Hudu REST API
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Hudu Platform                             │
│                  https://your-hudu-instance.com                  │
└─────────────────────────────────────────────────────────────────┘

# Clone the repository
git clone https://github.com/DevSkillsIT/Skills-MCP-Hudu.git
cd Skills-MCP-Hudu

# Configure environment
cp .env.example .env
nano .env  # Edit with your Hudu credentials

# Start with Docker Compose
docker-compose up -d

# Verify it's running
curl http://localhost:3100/health

# Clone and install
git clone https://github.com/DevSkillsIT/Skills-MCP-Hudu.git
cd Skills-MCP-Hudu
npm install

# Configure
cp .env.example .env
nano .env  # Edit with your Hudu credentials

# Build and run
npm run build
npm start

# Or development mode with hot reload
npm run dev

# Required Settings
HUDU_BASE_URL=https://your-company.huducloud.com
HUDU_API_KEY=your-api-key-here

# MCP Server Configuration
MCP_SERVER_PORT=3100
MCP_BEARER_TOKEN=your-secure-token  # Optional but recommended

# Optional Settings
HUDU_TIMEOUT=30000
HUDU_ALLOWED_COMPANY_IDS=ALL  # Or specific company IDs: 123,456
LOG_LEVEL=info

# Add MCP server
claude mcp add --transport http hudu http://localhost:3100/mcp

{
  "mcpServers": {
    "hudu": {
      "type": "streamable-http",
      "url": "http://localhost:3100/mcp"
    }
  }
}

{
  "mcpServers": {
    "hudu": {
      "httpUrl": "http://localhost:3100/mcp",
      "timeout": 30000
    }
  }
}

# Health check
curl http://localhost:3100/health

# Server info
curl http://localhost:3100/

# List available tools (requires valid setup)
curl -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Hudu, list all companies
Hudu, create a new company "Acme Corporation" with website acme.com
Hudu, show me all assets for company "Acme Corporation"
Hudu, search for articles about "firewall configuration"

Hudu, list all passwords for company "Acme Corporation"
Hudu, create a new password entry for "Office WiFi"
Hudu, search credentials containing "admin"

Hudu, list all procedures
Hudu, create a new procedure "Server Backup Checklist"
Hudu, show tasks for procedure ID 123

Hudu, list all networks
Hudu, show VLANs for company "Acme Corporation"
Hudu, list IP addresses in network ID 456
Hudu, document rack storage in datacenter

Hudu, show all expiring SSL certificates
Hudu, list domain expirations for company "Acme Corporation"
Hudu, show monitored websites and their DNS/SSL status
Hudu, add website monitoring for https://acme.com

Hudu, show recent activity logs for user admin@acme.com
Hudu, list all changes to assets in the last week
Hudu, who modified company "Acme Corporation" recently?

Hudu, list all Magic Dash widgets for company "Acme"
Hudu, create a dashboard widget showing backup status
Hudu, show relations between asset ID 100 and other entities

Hudu, search for "firewall" across all resources
Hudu, find anything related to "backup server"

Show me the contents of hudu://companies
Read hudu://assets/42
What does hudu://articles/15 contain?

Run the hudu_security_audit prompt for our infrastructure

# Access all companies (default)
HUDU_ALLOWED_COMPANY_IDS=ALL

# Access only company ID 123
HUDU_ALLOWED_COMPANY_IDS=123

# Access multiple companies
HUDU_ALLOWED_COMPANY_IDS=123,456,789

version: '3.8'

services:
  hudu-mcp:
    build: .
    container_name: skills-mcp-hudu
    restart: unless-stopped
    ports:
      - "3100:3100"
    environment:
      - HUDU_BASE_URL=${HUDU_BASE_URL}
      - HUDU_API_KEY=${HUDU_API_KEY}
      - MCP_SERVER_PORT=3100
      - MCP_BEARER_TOKEN=${MCP_BEARER_TOKEN}
      - HUDU_TIMEOUT=30000
      - LOG_LEVEL=info
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3100/health"]
      interval: 30s
      timeout: 10s
      retries: 3

# Build and start
docker-compose up -d --build

# View logs
docker-compose logs -f hudu-mcp

# Stop
docker-compose down

# Rebuild without cache
docker-compose build --no-cache

# Check status
docker-compose ps

# .env
LOG_LEVEL=debug

docker-compose logs -f hudu-mcp

# Logs are written to stdout/stderr
npm start 2>&1 | tee hudu-mcp.log

pm2 logs hudu-mcp

# Clone repository
git clone https://github.com/DevSkillsIT/Skills-MCP-Hudu.git
cd Skills-MCP-Hudu

# Install dependencies
npm install

# Start development server (hot reload)
npm run dev

# Run linting
npm run lint

# Type checking
npm run type-check

# Build for production
npm run build

# Run all tests (179 tests, 12 suites)
npm test

# Run with verbose output
NODE_OPTIONS='--experimental-vm-modules' npx jest --verbose

# Type checking
npm run type-check

# Lint code
npm run lint

# Build project
npm run build

Skills-MCP-Hudu/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP HTTP server + instructions + resource handlers
│   ├── hudu-client.ts        # Hudu API client (941 lines, all endpoints + fetchAll)
│   ├── resources.ts          # MCP Resources handler (6 hudu:// URIs) — NEW
│   ├── types.ts              # TypeScript definitions + HuduPagedResponse<T>
│   ├── utils/
│   │   └── html-stripper.ts  # HTML cleanup: stripHtml, truncate, escapeMarkdown — NEW
│   ├── formatters/
│   │   ├── markdown.ts       # 29 Markdown formatters for all entity types — NEW
│   │   └── response-formatter.ts  # Global interceptor: Markdown for all 43 tools — NEW
│   └── tools/
│       ├── working-index.ts  # Primary tool registry (43 tools)
│       ├── base.ts           # Response helpers
│       ├── schema-utils.ts   # Shared schemas and properties
│       ├── companies.ts      # Company management (2 tools)
│       ├── assets.ts         # Asset inventory (2 tools)
│       ├── articles.ts       # Knowledge base articles (2 tools)
│       ├── passwords.ts      # Password vault (2 tools)
│       ├── procedures.ts     # Procedures and tasks (4 tools)
│       ├── folders.ts        # Folder organization (2 tools)
│       ├── networks.ts       # Networks, VLANs, IPs (8 tools)
│       ├── storage.ts        # Uploads, racks, photos (8 tools)
│       ├── expirations.ts    # Expiration tracking (1 tool) — NEW
│       ├── websites.ts       # Website monitoring (2 tools) — NEW
│       ├── asset-layouts.ts  # Asset layout templates (2 tools) — NEW
│       ├── activity-logs.ts  # Activity audit logs (1 tool) — NEW
│       ├── relations.ts      # Entity relations (2 tools) — NEW
│       ├── magic-dash.ts     # Dashboard widgets (2 tools) — NEW
│       ├── admin.ts          # Instance administration (1 tool)
│       ├── search.ts         # Global unified search (1 tool)
│       └── navigation.ts     # Quick navigation (1 tool)
├── src/__tests__/            # 179 tests across 12 suites — NEW
│   ├── utils/                # html-stripper tests
│   ├── formatters/           # markdown + response-formatter tests
│   ├── tools/                # Tool executor tests (6 files)
│   ├── integration/          # Registry + annotation compliance tests
│   └── resources.test.ts     # MCP Resources tests
├── dist/                     # Compiled JavaScript (generated)
├── jest.config.ts            # Jest configuration (ESM + ts-jest) — NEW
├── tsconfig.test.json        # TypeScript config for tests — NEW
├── hudu.json                 # Hudu OpenAPI spec (reference)
├── Dockerfile                # Multi-stage Docker build
├── docker-compose.yml        # Docker Compose configuration
├── package.json              # Node.js dependencies
├── tsconfig.json             # TypeScript configuration
├── .env.example              # Environment template
├── .gitignore                # Git ignore rules
├── LICENSE                   # MIT License
└── README.md                 # This file

feat: add new feature
fix: correct bug
docs: update documentation
refactor: improve code structure
test: add tests
chore: update dependencies
style: formatting changes
perf: performance improvements