# Castov — Complete LLM & AI Agent Technical Reference (llms-full.txt)

> Castov (`castov` v1.4.0) is a zero-telemetry, deterministic DevSecOps & Developer Toolbox Ecosystem featuring a **Glama Grade A** Model Context Protocol (MCP) Server, a cross-platform CLI (`npx castov`), a pure TypeScript SDK (`@castov/sdk`), a VS Code Extension, 29+ client-side browser utilities, and a 1,000+ page Programmatic SEO technical registry (`https://www.castov.com`).

- **Canonical Website**: https://www.castov.com
- **MCP Server Hub & Interactive JSON-RPC 2.0 Playground**: https://www.castov.com/mcp
- **Developer Ecosystem (`/developer`)**: https://www.castov.com/developer
- **CLI Documentation (`/cli`)**: https://www.castov.com/cli
- **All Browser Utilities (`/tools`)**: https://www.castov.com/tools
- **Sponsorship & Partnerships (`/sponsor`)**: https://www.castov.com/sponsor
- **Compact LLM Index**: https://www.castov.com/llms.txt
- **NPM Package (`castov` v1.4.0)**: https://www.npmjs.com/package/castov
- **NPM SDK (`@castov/sdk` v1.4.0)**: https://www.npmjs.com/package/@castov/sdk
- **GitHub Repository**: https://github.com/castov/time
- **Glama MCP Security Audit**: Grade A (100% deterministic local execution, zero telemetry, zero remote API calls, MIT License)

---

## 1. Quick-Start Commands & IDE Configuration

### 1.1 Start the Castov MCP Server (stdio)
```bash
npx -y castov@latest mcp
```

### 1.2 Run Castov CLI Directly in Terminal
```bash
# Interactive TUI mode
npx castov

# Deterministic subcommands (supports --json for CI/CD pipelines)
npx castov time now --json
npx castov cidr 10.24.0.0/16 --json
npx castov port 5432 --json
npx castov id 018f3a9c-8b5a-7000-8000-010203040506 --json
npx castov cron "*/15 * * * *" --json
npx castov tz "2026-04-20T14:30:00Z" UTC America/New_York --json
npx castov secret 32 --json
npx castov jwt <JWT_TOKEN> --json
npx castov hash "hello world" --algo sha256 --json
npx castov scan ./src --json
```

### 1.3 Claude Desktop / Cursor / Windsurf / VS Code (`mcp.json`)
```json
{
  "mcpServers": {
    "castov": {
      "command": "npx",
      "args": ["-y", "castov@latest", "mcp"]
    }
  }
}
```

### 1.4 Claude Code CLI One-Liner
```bash
claude mcp add castov -- npx -y castov@latest mcp
```

---

## 2. MCP Server Protocol & Architecture

- **Protocol Version**: `2024-11-05` (JSON-RPC 2.0 over `stdio`)
- **Framing Support**: Auto-detects both `Content-Length` HTTP-header framing and newline-delimited JSON (`ndjson`), replying in the exact framing mode initiated by the client.
- **Capabilities**: `tools` (10 deterministic tools), `ping`, `initialize`, `notifications/initialized`, `tools/list`, `tools/call`.
- **Security Guarantees**:
  - **Zero Network Calls**: Every calculation runs locally using Node.js native `crypto` and deterministic math engines.
  - **No Environment Harvesting**: Never reads `process.env` or transmits file contents over the network.
  - **Deterministic Output**: Identical inputs strictly produce identical structured JSON outputs (except cryptographic random generation in `castov_secret`).

---

## 3. Complete Specification of All 10 MCP Tools

Below is the exhaustive specification for each of the 10 tools exposed by `npx -y castov@latest mcp`, including input schemas, parameter definitions, and exact **JSON-RPC 2.0 Request & Response** payloads.

---

### Tool 1: `castov_timestamp`
Convert a Unix timestamp (seconds, milliseconds, microseconds, or nanoseconds) or ISO-8601 date string into structured UTC, local, epoch seconds, epoch milliseconds, and day-of-week metadata.

#### Input Schema (`inputSchema`)
```json
{
  "type": "object",
  "properties": {
    "value": {
      "type": "string",
      "description": "Unix epoch (e.g. '1776297600') or ISO-8601 string or 'now'"
    }
  },
  "required": ["value"]
}
```

#### JSON-RPC 2.0 Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "castov_timestamp",
    "arguments": {
      "value": "1776297600"
    }
  }
}
```

#### JSON-RPC 2.0 Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"input\": \"1776297600\",\n  \"detectedUnit\": \"seconds\",\n  \"iso8601\": \"2026-04-16T00:00:00.000Z\",\n  \"utcString\": \"Thu, 16 Apr 2026 00:00:00 GMT\",\n  \"unixSeconds\": 1776297600,\n  \"unixMilliseconds\": 1776297600000,\n  \"dayOfWeek\": \"Thursday\",\n  \"isLeapYear\": false\n}"
      }
    ]
  }
}
```

---

### Tool 2: `castov_detect_id`
Inspect an identifier string (UUID v1/v4/v7, ULID, MongoDB ObjectId, Snowflake ID, or KSUID) and extract embedded timestamps, version metadata, and bit layout.

#### Input Schema (`inputSchema`)
```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID string to inspect (UUID, ULID, ObjectId, etc.)"
    }
  },
  "required": ["id"]
}
```

#### JSON-RPC 2.0 Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "castov_detect_id",
    "arguments": {
      "id": "018f3a9c-8b5a-7000-8000-010203040506"
    }
  }
}
```

#### JSON-RPC 2.0 Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"input\": \"018f3a9c-8b5a-7000-8000-010203040506\",\n  \"type\": \"UUID v7 (Time-Ordered)\",\n  \"valid\": true,\n  \"version\": 7,\n  \"variant\": \"RFC 4122 / RFC 9562\",\n  \"timestampIso\": \"2024-05-02T17:26:52.506Z\",\n  \"unixMs\": 1714670812506\n}"
      }
    ]
  }
}
```

---

### Tool 3: `castov_cidr`
Calculate IPv4 CIDR subnet boundaries, netmask, wildcard mask, broadcast address, usable host range, total host count, and AWS/Cloud VPC reserved IP breakdown.

#### Input Schema (`inputSchema`)
```json
{
  "type": "object",
  "properties": {
    "cidr": {
      "type": "string",
      "description": "IPv4 CIDR block, e.g. '10.0.0.0/16' or '192.168.1.0/24'"
    }
  },
  "required": ["cidr"]
}
```

#### JSON-RPC 2.0 Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "castov_cidr",
    "arguments": {
      "cidr": "10.24.0.0/22"
    }
  }
}
```

#### JSON-RPC 2.0 Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"cidr\": \"10.24.0.0/22\",\n  \"networkAddress\": \"10.24.0.0\",\n  \"broadcastAddress\": \"10.24.3.255\",\n  \"subnetMask\": \"255.255.252.0\",\n  \"wildcardMask\": \"0.0.3.255\",\n  \"firstUsableHost\": \"10.24.0.1\",\n  \"lastUsableHost\": \"10.24.3.254\",\n  \"totalAddresses\": 1024,\n  \"usableHosts\": 1022,\n  \"awsUsableHosts\": 1019,\n  \"cidrPrefix\": 22\n}"
      }
    ]
  }
}
```

---

### Tool 4: `castov_port`
Look up a network port number (1-65535) for protocol details, service identification, Docker/Firewall snippets, and command-line process kill instructions across Linux, macOS, and Windows.

#### Input Schema (`inputSchema`)
```json
{
  "type": "object",
  "properties": {
    "port": {
      "type": "number",
      "description": "TCP/UDP port number (e.g. 5432, 6379, 8080, 11434)"
    }
  },
  "required": ["port"]
}
```

#### JSON-RPC 2.0 Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "castov_port",
    "arguments": {
      "port": 5432
    }
  }
}
```

#### JSON-RPC 2.0 Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"port\": 5432,\n  \"service\": \"PostgreSQL Database Server\",\n  \"protocol\": \"TCP\",\n  \"category\": \"Database\",\n  \"killCommands\": {\n    \"unix\": \"lsof -ti :5432 | xargs kill -9\",\n    \"windows\": \"Stop-Process -Id (Get-NetTCPConnection -LocalPort 5432).OwningProcess -Force\"\n  }\n}"
      }
    ]
  }
}
```

---

### Tool 5: `castov_cron`
Validate a 5-field cron expression and compute the next 5 upcoming execution timestamps in ISO-8601 format for a given IANA timezone.

#### Input Schema (`inputSchema`)
```json
{
  "type": "object",
  "properties": {
    "expression": {
      "type": "string",
      "description": "5-field cron expression, e.g. '*/15 * * * *'"
    },
    "timezone": {
      "type": "string",
      "description": "Optional IANA timezone (default: 'UTC')"
    }
  },
  "required": ["expression"]
}
```

#### JSON-RPC 2.0 Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "castov_cron",
    "arguments": {
      "expression": "*/15 * * * *",
      "timezone": "UTC"
    }
  }
}
```

#### JSON-RPC 2.0 Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"expression\": \"*/15 * * * *\",\n  \"timezone\": \"UTC\",\n  \"valid\": true,\n  \"summary\": \"Every 15 minutes\",\n  \"nextRuns\": [\n    \"2026-04-16T12:00:00.000Z\",\n    \"2026-04-16T12:15:00.000Z\",\n    \"2026-04-16T12:30:00.000Z\",\n    \"2026-04-16T12:45:00.000Z\",\n    \"2026-04-16T13:00:00.000Z\"\n  ]\n}"
      }
    ]
  }
}
```

---

### Tool 6: `castov_timezone`
Convert a date/time string between two IANA timezones with exact DST offset calculation.

#### Input Schema (`inputSchema`)
```json
{
  "type": "object",
  "properties": {
    "dateTime": {
      "type": "string",
      "description": "ISO date-time string (e.g. '2026-04-20T14:30:00Z')"
    },
    "fromZone": {
      "type": "string",
      "description": "Source IANA timezone (e.g. 'UTC')"
    },
    "toZone": {
      "type": "string",
      "description": "Target IANA timezone (e.g. 'America/New_York' or 'Asia/Tokyo')"
    }
  },
  "required": ["dateTime", "fromZone", "toZone"]
}
```

#### JSON-RPC 2.0 Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "castov_timezone",
    "arguments": {
      "dateTime": "2026-04-20T14:30:00Z",
      "fromZone": "UTC",
      "toZone": "America/New_York"
    }
  }
}
```

#### JSON-RPC 2.0 Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"input\": \"2026-04-20T14:30:00Z\",\n  \"fromZone\": \"UTC\",\n  \"toZone\": \"America/New_York\",\n  \"convertedFormatted\": \"2026-04-20 10:30:00 EDT\",\n  \"utcIso\": \"2026-04-20T14:30:00.000Z\",\n  \"unixSeconds\": 1776695400\n}"
      }
    ]
  }
}
```

---

### Tool 7: `castov_secret`
Generate cryptographically secure random secrets (Hex, Base64, Base64URL) and a RFC-9562 UUID v4 using Node's CSPRNG (`crypto.randomBytes`).

#### Input Schema (`inputSchema`)
```json
{
  "type": "object",
  "properties": {
    "bytes": {
      "type": "number",
      "description": "Entropy length in bytes (8 to 128, default 32)"
    }
  }
}
```

#### JSON-RPC 2.0 Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "castov_secret",
    "arguments": {
      "bytes": 32
    }
  }
}
```

#### JSON-RPC 2.0 Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"bytes\": 32,\n  \"entropyBits\": 256,\n  \"hex\": \"<64-char-hex-csprng-output>\",\n  \"base64\": \"<44-char-base64-csprng-output>\",\n  \"base64url\": \"<43-char-base64url-csprng-output>\",\n  \"uuidv4\": \"f47ac10b-58cc-4372-a567-0e02b2c3d479\"\n}"
      }
    ]
  }
}
```

---

### Tool 8: `castov_jwt_decode`
Decode and inspect a JSON Web Token (JWT) header, payload claims, issued-at (`iat`), not-before (`nbf`), and expiration (`exp`) status locally without transmitting the token over the network.

#### Input Schema (`inputSchema`)
```json
{
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "Raw JWT string (header.payload.signature)"
    }
  },
  "required": ["token"]
}
```

#### JSON-RPC 2.0 Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "castov_jwt_decode",
    "arguments": {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfOTkxM2EiLCJyb2xlIjoiYWRtaW4iLCJpYXQiOjE3NzYyOTc2MDAsImV4cCI6MTg5MzQ1NjAwMH0.sig"
    }
  }
}
```

#### JSON-RPC 2.0 Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"header\": {\n    \"alg\": \"HS256\",\n    \"typ\": \"JWT\"\n  },\n  \"payload\": {\n    \"sub\": \"usr_9913a\",\n    \"role\": \"admin\",\n    \"iat\": 1776297600,\n    \"exp\": 1893456000\n  },\n  \"isExpired\": false,\n  \"expiresAtIso\": \"2030-01-01T00:00:00.000Z\",\n  \"issuedAtIso\": \"2026-04-16T00:00:00.000Z\"\n}"
      }
    ]
  }
}
```

---

### Tool 9: `castov_hash`
Compute deterministic cryptographic digests (`sha256`, `sha384`, `sha512`, `sha1`, `md5`) in both hexadecimal and Base64 formats.

#### Input Schema (`inputSchema`)
```json
{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "Input string to hash"
    },
    "algorithm": {
      "type": "string",
      "enum": ["sha256", "sha384", "sha512", "sha1", "md5"],
      "description": "Hash algorithm (default: 'sha256')"
    }
  },
  "required": ["text"]
}
```

#### JSON-RPC 2.0 Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "castov_hash",
    "arguments": {
      "text": "castov-mcp-v1.4.0",
      "algorithm": "sha256"
    }
  }
}
```

#### JSON-RPC 2.0 Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"algorithm\": \"sha256\",\n  \"inputLength\": 17,\n  \"hex\": \"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08\",\n  \"base64\": \"n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=\"\n}"
      }
    ]
  }
}
```

---

### Tool 10: `castov_scan_secrets`
Scan code snippets, `.env` files, or configuration text for leaked credentials (AWS Access Keys, Stripe Live Keys, GitHub PATs, OpenAI/Anthropic Keys, Slack Webhooks, Private Keys, and Database URLs) locally before committing or sending to an LLM.

#### Input Schema (`inputSchema`)
```json
{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "Text or source code snippet to scan for exposed credentials"
    }
  },
  "required": ["content"]
}
```

#### JSON-RPC 2.0 Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "castov_scan_secrets",
    "arguments": {
      "content": "AWS_KEY=AKIA_EXAMPLE_REDACTED_KEY\nSTRIPE_SECRET=sk_live_EXAMPLE_REDACTED_TOKEN"
    }
  }
}
```

#### JSON-RPC 2.0 Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"clean\": false,\n  \"findingsCount\": 2,\n  \"findings\": [\n    {\n      \"ruleId\": \"aws-access-key-id\",\n      \"severity\": \"CRITICAL\",\n      \"description\": \"AWS Access Key ID\",\n      \"line\": 1,\n      \"redactedMatch\": \"AKIA...REDACTED\"\n    },\n    {\n      \"ruleId\": \"stripe-live-secret\",\n      \"severity\": \"CRITICAL\",\n      \"description\": \"Stripe Live Secret Key\",\n      \"line\": 2,\n      \"redactedMatch\": \"sk_live_...REDACTED\"\n    }\n  ]\n}"
      }
    ]
  }
}
```

---

## 4. Programmatic SEO & Technical Reference Registries

Castov hosts deterministic, statically generated reference pages for common engineering lookups:
- **Network Ports Registry (`/ports/[port]`)**: 74+ ports including PostgreSQL (`5432`), Redis (`6379`), Ollama (`11434`), Qdrant (`6333`), Milvus (`19530`), ChromaDB (`8000`), Weaviate (`8080`), OpenTelemetry (`4317`/`4318`), Supabase (`54321`/`54322`), Kubernetes (`6443`), and Kafka (`9092`).
- **Developer Error Fixes (`/error-fixes/[slug]`)**: 38+ step-by-step root-cause and copy-paste remediation guides for Node.js, Docker, Git, PostgreSQL, Kubernetes, Next.js, Supabase RLS, and MCP stdio `spawn npx ENOENT` errors.
- **IPv4 CIDR Calculators (`/cidr/[prefix]`)**: Pre-computed tables for `/8` through `/32` subnets including AWS VPC, GCP, and Azure reserved address breakdowns.
- **Linux Chmod Matrix (`/chmod/[code]`)**: Octal and symbolic permission references (`000`–`777`) with security audits.
- **Cron Schedule Reference (`/cron/[expression]`)**: Human-readable breakdowns and next-execution schedules for standard cron expressions.
- **HTTP Status Codes (`/http-status/[code]`)**: RFC-compliant semantics and debugging tips for `1xx`–`5xx` status codes.