@certynix/mcp 1.0.0

package/eslint.config.mjs

@@ -0,0 +1,27 @@
+// @ts-check
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import globals from 'globals';
+
+export default tseslint.config(
+  { ignores: ['dist/**', 'node_modules/**', 'eslint.config.mjs'] },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommendedTypeChecked,
+  {
+    languageOptions: {
+      globals: { ...globals.node },
+      parserOptions: {
+        project: './tsconfig.json',
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      '@typescript-eslint/no-floating-promises': 'error',
+      '@typescript-eslint/no-unsafe-assignment': 'error',
+      '@typescript-eslint/no-unsafe-member-access': 'error',
+      '@typescript-eslint/no-unsafe-return': 'error',
+    },
+  },
+);

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@certynix/mcp",
+  "version": "1.0.0",
+  "description": "Official Certynix MCP Server — Expose Trust Infrastructure to AI agents",
+  "bin": {
+    "certynix-mcp": "./dist/index.js"
+  },
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "type-check": "tsc --noEmit",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@certynix/sdk": "file:../sdk-node",
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0",
+    "@types/node": "^20.0.0",
+    "zod": "^3.23.0",
+    "eslint": "^9.0.0",
+    "typescript-eslint": "^8.0.0",
+    "@eslint/js": "^9.0.0",
+    "globals": "^15.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "vitest": {
+    "environment": "node",
+    "globals": false
+  }
+}

package/src/index.ts

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+
+/**
+ * Certynix MCP Server — Entrypoint
+ *
+ * Expõe a Certynix Trust Infrastructure para agentes de IA via Model Context Protocol.
+ * Suporta transporte stdio (Claude Desktop) e SSE (integrações remotas).
+ *
+ * Variáveis de ambiente:
+ *   CERTYNIX_API_KEY  — obrigatório (cnx_live_sk_* ou cnx_test_sk_*)
+ *   CERTYNIX_BASE_URL — opcional (auto-detectado via prefixo da key)
+ *   CERTYNIX_TIMEOUT  — opcional (ms, padrão: 30000)
+ *   MCP_TRANSPORT     — opcional (stdio | sse, padrão: stdio)
+ *   MCP_PORT          — opcional (apenas para sse, padrão: 3100)
+ *   MCP_LOG_LEVEL     — opcional (debug | info | warn | error, padrão: info)
+ */
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+import { maskApiKey } from './utils/mask.js';
+
+async function main(): Promise<void> {
+  const apiKey = process.env['CERTYNIX_API_KEY'];
+
+  if (!apiKey) {
+    console.error(
+      'Error: CERTYNIX_API_KEY environment variable is required.\n' +
+        'Set it to your Certynix API Key (cnx_live_sk_... for production, cnx_test_sk_... for sandbox).',
+    );
+    process.exit(1);
+  }
+
+  // Validar formato básico sem expor a key
+  if (!apiKey.startsWith('cnx_live_sk_') && !apiKey.startsWith('cnx_test_sk_')) {
+    console.error(
+      'Error: Invalid CERTYNIX_API_KEY format.\n' +
+        'Expected: cnx_live_sk_... (production) or cnx_test_sk_... (sandbox).',
+    );
+    process.exit(1);
+  }
+
+  const transport = process.env['MCP_TRANSPORT'] ?? 'stdio';
+  const baseUrl = process.env['CERTYNIX_BASE_URL'];
+  const timeoutRaw = process.env['CERTYNIX_TIMEOUT'];
+  const timeout =
+    timeoutRaw !== undefined ? parseInt(timeoutRaw, 10) : undefined;
+  const isSandbox = apiKey.startsWith('cnx_test_sk_');
+
+  let server;
+  try {
+    server = createServer(apiKey, {
+      ...(baseUrl !== undefined ? { baseUrl } : {}),
+      ...(timeout !== undefined ? { timeout } : {}),
+    });
+  } catch (err) {
+    // Nunca logar a API key, mesmo em erro de inicialização
+    console.error(
+      'Failed to initialize Certynix MCP Server. Check your API key format and network connectivity.',
+    );
+    if (err instanceof Error) {
+      // Sanitizar mensagem de erro para garantir que a key não vaze
+      const sanitized = err.message.replace(apiKey, maskApiKey(apiKey));
+      console.error(`Details: ${sanitized}`);
+    }
+    process.exit(1);
+  }
+
+  if (transport === 'stdio') {
+    const stdioTransport = new StdioServerTransport();
+    await server.connect(stdioTransport);
+
+    // Log para stderr (não interfere com stdio MCP) — API key mascarada
+    console.error(
+      `Certynix MCP Server running (stdio) — ` +
+        `API key: ${maskApiKey(apiKey)} — ` +
+        `Environment: ${isSandbox ? 'sandbox' : 'production'}`,
+    );
+  } else if (transport === 'sse') {
+    const port = parseInt(process.env['MCP_PORT'] ?? '3100', 10);
+
+    // SSE transport via HTTP server
+    // Importação dinâmica para evitar dependência quando não for necessário
+    const { createServer: createHttpServer } = await import('node:http');
+    const { SSEServerTransport } = await import(
+      '@modelcontextprotocol/sdk/server/sse.js'
+    );
+
+    const httpServer = createHttpServer();
+    let sseTransport: InstanceType<typeof SSEServerTransport> | null = null;
+
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises
+    httpServer.on('request', async (req, res) => {
+      if (req.method === 'GET' && req.url === '/sse') {
+        sseTransport = new SSEServerTransport('/message', res);
+        await server.connect(sseTransport);
+        console.error(
+          `Certynix MCP SSE client connected from ${req.socket.remoteAddress ?? 'unknown'}`,
+        );
+      } else if (req.method === 'POST' && req.url === '/message') {
+        if (!sseTransport) {
+          res.writeHead(503, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'SSE connection not established yet' }));
+          return;
+        }
+        await sseTransport.handlePostMessage(req, res);
+      } else if (req.method === 'GET' && req.url === '/health') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(
+          JSON.stringify({
+            status: 'ok',
+            server: 'certynix-mcp',
+            version: '1.0.0',
+            environment: isSandbox ? 'sandbox' : 'production',
+          }),
+        );
+      } else {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not found' }));
+      }
+    });
+
+    await new Promise<void>((resolve, reject) => {
+      httpServer.listen(port, () => {
+        console.error(
+          `Certynix MCP Server running on port ${port} (SSE) — ` +
+            `API key: ${maskApiKey(apiKey)} — ` +
+            `Environment: ${isSandbox ? 'sandbox' : 'production'}\n` +
+            `  SSE endpoint: http://localhost:${port}/sse\n` +
+            `  Health check: http://localhost:${port}/health`,
+        );
+        resolve();
+      });
+      httpServer.on('error', reject);
+    });
+  } else {
+    console.error(
+      `Error: Invalid MCP_TRANSPORT value: "${transport}". Expected "stdio" or "sse".`,
+    );
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(
+    'Fatal error:',
+    err instanceof Error ? err.message : String(err),
+  );
+  process.exit(1);
+});

package/src/prompts/audit-report.ts

@@ -0,0 +1,126 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+/**
+ * Prompt: certynix_audit_report
+ * Gera um relatório de auditoria estruturado a partir dos audit logs da organização.
+ */
+export function registerAuditReportPrompt(server: McpServer): void {
+  server.prompt(
+    'certynix_audit_report',
+    'Gera um relatório de auditoria estruturado para um período específico, analisando ações críticas, padrões de acesso e eventos de segurança.',
+    {
+      period: z
+        .enum(['last_7_days', 'last_30_days', 'custom'])
+        .describe(
+          "Período do relatório: 'last_7_days' (últimos 7 dias), 'last_30_days' (últimos 30 dias), 'custom' (usar start_date e end_date).",
+        ),
+      start_date: z
+        .string()
+        .optional()
+        .describe("Data de início no formato ISO 8601 (ex: 2026-01-01T00:00:00Z). Necessário apenas quando period='custom'."),
+      end_date: z
+        .string()
+        .optional()
+        .describe("Data de fim no formato ISO 8601 (ex: 2026-01-31T23:59:59Z). Necessário apenas quando period='custom'."),
+    },
+    (args) => {
+      const period = args['period'] ?? 'last_30_days';
+      const startDate = args['start_date'];
+      const endDate = args['end_date'];
+
+      let periodDescription: string;
+      let dateInstructions: string;
+
+      if (period === 'last_7_days') {
+        const now = new Date();
+        const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
+        periodDescription = 'últimos 7 dias';
+        dateInstructions = `Use created_after="${weekAgo.toISOString()}" e created_before="${now.toISOString()}" ao chamar list_audit_logs.`;
+      } else if (period === 'last_30_days') {
+        const now = new Date();
+        const monthAgo = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000);
+        periodDescription = 'últimos 30 dias';
+        dateInstructions = `Use created_after="${monthAgo.toISOString()}" e created_before="${now.toISOString()}" ao chamar list_audit_logs.`;
+      } else if (period === 'custom' && startDate && endDate) {
+        periodDescription = `${startDate} até ${endDate}`;
+        dateInstructions = `Use created_after="${startDate}" e created_before="${endDate}" ao chamar list_audit_logs.`;
+      } else {
+        periodDescription = 'período especificado';
+        dateInstructions =
+          "Peça ao usuário para especificar start_date e end_date quando period='custom'.";
+      }
+
+      return {
+        messages: [
+          {
+            role: 'user' as const,
+            content: {
+              type: 'text' as const,
+              text: `Gere um Relatório de Auditoria Certynix completo para o período: ${periodDescription}.
+
+## Instruções de execução
+
+1. **Chame a tool list_audit_logs** com os seguintes parâmetros:
+   - ${dateInstructions}
+   - limit: 100
+   - Se houver has_more=true na resposta, continue paginando com o next_cursor até obter todos os registros do período.
+
+2. **Chame a tool get_trust_score** para incluir o Trust Score atual no relatório.
+
+3. **Chame a tool list_alerts** com resolved=false para incluir alertas ativos.
+
+## Estrutura do relatório a gerar
+
+Após coletar os dados, gere um relatório em Markdown com esta estrutura:
+
+---
+
+# Relatório de Auditoria Certynix
+**Período:** ${periodDescription}
+**Gerado em:** [data atual]
+
+## Resumo Executivo
+- Total de ações no período: [N]
+- Trust Score atual: [score]/100
+- Alertas ativos: [N]
+- Eventos críticos: [N]
+
+## Trust Score
+- Score: [N]/100 ([label])
+- Identidade: [N]/35
+- Segurança: [N]/25
+- Comportamento: [N]/20
+- Assets: [N]/20
+- Penalidades ativas: [lista ou "Nenhuma"]
+
+## Atividade por Tipo de Ação
+| Ação | Quantidade |
+|------|-----------|
+| asset.created | N |
+| api_key.created | N |
+| ... | ... |
+
+## Eventos Críticos de Segurança
+[Lista de eventos relacionados a api_key.created, api_key.revoked, member.invited, plan.changed, etc.]
+
+## Assets Registrados no Período
+[Sumário de assets registrados: total, status breakdown, first_registrant count]
+
+## Alertas de Exposição Ativos
+[Lista de alertas não resolvidos com severidade]
+
+## Recomendações
+[Com base nos dados coletados, liste 3-5 recomendações priorizadas]
+
+---
+
+**IMPORTANTE:** Nunca inclua valores de API Keys, tokens, ou outros dados sensíveis no relatório.
+`,
+            },
+          },
+        ],
+      };
+    },
+  );
+}

package/src/prompts/security-review.ts

@@ -0,0 +1,102 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * Prompt: certynix_security_review
+ * Analisa o estado de segurança da Organization e gera recomendações.
+ */
+export function registerSecurityReviewPrompt(server: McpServer): void {
+  server.prompt(
+    'certynix_security_review',
+    'Gera uma análise de segurança completa da Organization: Trust Score, penalidades ativas, status de API Keys, alertas abertos e recomendações priorizadas.',
+    {},
+    (_args) => {
+      return {
+        messages: [
+          {
+            role: 'user' as const,
+            content: {
+              type: 'text' as const,
+              text: `Realize uma Revisão de Segurança completa da organização Certynix.
+
+## Instruções de execução
+
+Execute as seguintes tools em ordem para coletar dados:
+
+1. **get_trust_score** — Trust Score atual com componentes e penalidades
+2. **list_alerts** com resolved=false, limit=50 — Alertas de exposição ativos
+3. **list_api_keys** com limit=100 — Inventário de API Keys ativas
+4. **list_audit_logs** com limit=50, action="api_key.created" — Criações recentes de API Keys
+5. **list_audit_logs** com limit=20, action="member.invited" — Membros adicionados recentemente
+6. **list_assets** com limit=20, status="failed" — Assets com falha de verificação
+
+## Estrutura da análise a gerar
+
+Após coletar todos os dados, gere uma Revisão de Segurança em Markdown:
+
+---
+
+# Revisão de Segurança Certynix
+**Data:** [data atual]
+**Status Geral:** [Critico / Atenção / Bom / Excelente com base no score]
+
+## Trust Score: [N]/100
+
+### Componentes
+| Pilar | Pontuação | Máximo | Status |
+|-------|-----------|--------|--------|
+| Identidade | N | 35 | [OK/Atenção/Crítico] |
+| Segurança | N | 25 | [OK/Atenção/Crítico] |
+| Comportamento | N | 20 | [OK/Atenção/Crítico] |
+| Assets | N | 20 | [OK/Atenção/Crítico] |
+
+### Penalidades Ativas
+[Lista de penalidades ou "Nenhuma penalidade ativa"]
+
+## Alertas de Exposição ([N] ativos)
+
+### Alta Severidade ([N])
+[Lista de alertas high com descrição]
+
+### Média Severidade ([N])
+[Lista de alertas medium]
+
+### Baixa Severidade ([N])
+[Lista de alertas low]
+
+## API Keys ([N] ativas)
+[Listar todas as API Keys com nome e data de criação]
+[Identificar keys não utilizadas recentemente]
+[Identificar keys criadas há mais de 90 dias sem rotação]
+
+## Observações de Acesso
+[Membros adicionados recentemente]
+[API Keys criadas recentemente]
+
+## Assets com Falha ([N])
+[Lista de assets com status=failed]
+
+## Recomendações Priorizadas
+
+### Críticas (ação imediata)
+1. [recomendação baseada nos dados]
+
+### Altas (próxima semana)
+1. [recomendação baseada nos dados]
+
+### Médias (próximo mês)
+1. [recomendação baseada nos dados]
+
+## Score de Maturidade de Segurança
+[Avaliação qualitativa de 1-5 com justificativa baseada nos dados coletados]
+
+---
+
+**IMPORTANTE:** Nunca inclua valores de API Keys, tokens, signing secrets ou outros dados sensíveis na análise.
+`,
+            },
+          },
+        ],
+      };
+    },
+  );
+}

package/src/resources/alerts-active.ts

@@ -0,0 +1,56 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CertynixClient } from '@certynix/sdk';
+import { formatError } from '../utils/format.js';
+
+/**
+ * Resource: certynix://alerts/active
+ * Lista todos os Exposure Alerts ativos não resolvidos.
+ */
+export function registerActiveAlertsResource(server: McpServer, client: CertynixClient): void {
+  server.resource(
+    'alerts-active',
+    'certynix://alerts/active',
+    {
+      description:
+        'Lista de Exposure Alerts ativos não resolvidos: anomalias de integridade detectadas automaticamente (surtos de verificação, versões conflitantes, assets não verificados).',
+      mimeType: 'application/json',
+    },
+    async (_uri) => {
+      try {
+        const page = await client.alerts.listPage({ resolved: false, limit: 50 });
+
+        return {
+          contents: [
+            {
+              uri: 'certynix://alerts/active',
+              mimeType: 'application/json',
+              text: JSON.stringify(
+                {
+                  data: page.data,
+                  total_active: page.data.length,
+                  has_more: page.pagination.has_more,
+                  next_cursor: page.pagination.next_cursor,
+                  note: page.pagination.has_more
+                    ? 'Use a tool list_alerts com cursor para ver mais alertas.'
+                    : undefined,
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          contents: [
+            {
+              uri: 'certynix://alerts/active',
+              mimeType: 'application/json',
+              text: JSON.stringify({ error: formatError(err) }, null, 2),
+            },
+          ],
+        };
+      }
+    },
+  );
+}

package/src/resources/asset.ts

@@ -0,0 +1,79 @@
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CertynixClient } from '@certynix/sdk';
+import { formatError } from '../utils/format.js';
+
+/**
+ * Resource template: certynix://assets/{asset_id}
+ * Retorna metadados completos de um asset específico.
+ */
+export function registerAssetResource(server: McpServer, client: CertynixClient): void {
+  server.resource(
+    'asset',
+    new ResourceTemplate('certynix://assets/{asset_id}', { list: undefined }),
+    {
+      description:
+        'Metadados completos de um asset específico: hash, status, Trust Score individual, contagem de verificações públicas e histórico de eventos.',
+      mimeType: 'application/json',
+    },
+    async (uri, variables) => {
+      const assetId = variables['asset_id'];
+
+      if (typeof assetId !== 'string' || !assetId) {
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              mimeType: 'application/json',
+              text: JSON.stringify(
+                { error: 'asset_id is required in the URI: certynix://assets/{asset_id}' },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      }
+
+      try {
+        const asset = await client.assets.get(assetId);
+
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              mimeType: 'application/json',
+              text: JSON.stringify(
+                {
+                  id: asset.id,
+                  hash: asset.hash,
+                  status: asset.status,
+                  trust_score: asset.trustScore,
+                  source_type: asset.sourceType,
+                  source_reference: asset.sourceReference,
+                  public_verification_count: asset.publicVerificationCount,
+                  is_first_registrant: asset.isFirstRegistrant,
+                  is_sample: asset.isSample,
+                  created_at: asset.createdAt,
+                  events: asset.events,
+                  verification_url: `https://certynix.com/verify/${asset.id}`,
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              mimeType: 'application/json',
+              text: JSON.stringify({ error: formatError(err) }, null, 2),
+            },
+          ],
+        };
+      }
+    },
+  );
+}

package/src/resources/organization-info.ts

@@ -0,0 +1,60 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CertynixClient } from '@certynix/sdk';
+import { formatError } from '../utils/format.js';
+
+/**
+ * Resource: certynix://organization/info
+ * Retorna informações da Organization autenticada via API Key.
+ * Usa o Trust Score endpoint para obter dados da organização.
+ */
+export function registerOrganizationInfoResource(
+  server: McpServer,
+  client: CertynixClient,
+): void {
+  server.resource(
+    'organization-info',
+    'certynix://organization/info',
+    {
+      description:
+        'Informações da Organization autenticada: Trust Score atual, componentes e penalidades ativas.',
+      mimeType: 'application/json',
+    },
+    async (_uri) => {
+      try {
+        const trustScore = await client.trustScore.get();
+
+        return {
+          contents: [
+            {
+              uri: 'certynix://organization/info',
+              mimeType: 'application/json',
+              text: JSON.stringify(
+                {
+                  trust_score: {
+                    score: trustScore.score,
+                    algorithm_version: trustScore.algorithmVersion,
+                    components: trustScore.components,
+                    penalties: trustScore.penalties,
+                    updated_at: trustScore.updatedAt,
+                  },
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          contents: [
+            {
+              uri: 'certynix://organization/info',
+              mimeType: 'application/json',
+              text: JSON.stringify({ error: formatError(err) }, null, 2),
+            },
+          ],
+        };
+      }
+    },
+  );
+}