Skills-MCP-Hudu: Instructions file for Claude Code

CLAUDE.md — MCP Hudu Server

You are Claude Code. Generate and maintain a production-ready MCP server that wraps the Hudu API from hudu.json (Swagger/OpenAPI).

Objective

Ship an MVP MCP server that:

• Conforms to the LATEST MCP specification (always current version - NO legacy versions).
• ALWAYS uses the LATEST official MCP TypeScript SDK: @modelcontextprotocol/sdk (update immediately when new versions available)
• EXCLUSIVELY uses Streamable HTTP Transport on port 3100 - NO STDIO, NO SSE, HTTP ONLY.
• Implements the resource+action pattern (predictable verbs across domains).
• Runs reliably in Docker, with health/readiness endpoints.
• Handles partial API access gracefully (typed errors, warnings, next steps).
• Uses .env for all Hudu config (no secrets in code).
• MANDATORY: Always update to latest packages - security and compatibility requirement.

---

Environment & Configuration

Create a .env file from .env.example:

HUDU_BASE_URL=https://your-hudu.example.com
HUDU_API_KEY=your-api-key
HUDU_TIMEOUT=30000
MCP_SERVER_PORT=3100
LOG_LEVEL=info

Fail fast if required vars are missing. No hard-coded secrets.

---

Connection from Claude Code (HTTP ONLY)

ONLY HTTP transport is supported - no STDIO configuration:

Add MCP server to Claude Code:

claude mcp add --transport http hudu http://127.0.0.1:3100/mcp

Alternative Claude Desktop config:

{
  "mcpServers": {
    "hudu": {
      "transport": "http",
      "url": "http://127.0.0.1:3100/mcp"
    }
  }
}

IMPORTANT: Never configure STDIO transport. This server only supports HTTP.

---

Deliverables (what you should generate)

• src/server.ts — MCP HTTP server wiring (Streamable transport), health endpoints:
  • GET /health (liveness)
  • GET / (server info)
  • ALL /mcp (MCP endpoint)
• src/hudu-client.ts — Hudu API client with typed methods
• src/tools/* — 55 tools com prefixo hudu_ e padrão manage/search:
  • Core: articles, companies, assets, passwords (manage + search = 8 tools)
  • Procedures: procedures, procedure tasks (manage + search = 4 tools)
  • Folders: kb article folders (manage + search = 2 tools)
  • Networks: networks, VLANs, VLAN zones, IP addresses (manage + search = 8 tools)
  • Storage: uploads, rack storages, rack items, public photos (manage + search = 8 tools)
  • Labels: definições de etiqueta, etiquetas aplicadas (manage + search = 4 tools)
  • Flags: tipos de sinalização, registros sinalizados (manage + search = 4 tools)
  • Utility: admin, search global, navigation (3 tools)
  • Outros: folders, websites, asset layouts, activity logs, expirations, relations, magic dash, bridges de resources/prompts
• src/types.ts — TypeScript types from OpenAPI
• hudu.json — OpenAPI/Swagger spec (reference only)
• Dockerfile — Multi-stage build, non-root runtime
• .env.example — Environment template
• docker-compose.existing-traefik.yml — Compose for an existing Traefik
• package.json — scripts: dev, build, start, lint, type-check