convez.ai
MCP ServerDados & AnalyticsAvançado
DforDennies

KolRadar MCP Server

DforDennies/kolradar-mcp-server

Dashboard de saúde empresarial com análise de KPIs, benchmarks e detecção de anomalias

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP para análise de dashboards de saúde empresarial (KolRadar), expondo 23 ferramentas para consultar KPIs, scores de saúde da empresa, benchmarks e anomalias. Integra-se com PostgreSQL e funciona tanto em ambiente local quanto em Vercel, com suporte a autenticação por API key e controle de escopo granular.

Instalação

$npx convez-ai DforDennies/kolradar-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
14%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Monitoramento de KPIs e métricas de empresas em tempo real
  • Detecção de anomalias e spikes em dados de negócio
  • Análise de funnel e tendências trimestral de saúde empresarial
  • Ranking de empresas por métrica e benchmarking de mercado
  • Rastreamento de contratos e análise de engajamento de usuários

Veredito

Ferramenta sólida e production-ready para análise de saúde empresarial com 23 endpoints especializados e suporte a múltiplos bancos PostgreSQL. Requer conhecimento de infraestrutura (Vercel, PostgreSQL, Prisma), mas oferece granularidade robusta via scopes e é bem documentada para equipes de análise/BI.

README

A tradução para o português deste README ainda está na fila.

KolRadar MCP Server

MCP (Model Context Protocol) server for KolRadar health dashboard analytics. Exposes 23 tools for querying business KPIs, company health scores, benchmarks, anomalies, and more.

Quick Start

1. Fork & Clone

git clone https://github.com/YOUR_USER/kolradar-mcp-server.git
cd kolradar-mcp-server
npm install

2. Configure Database

Copy .env.example to .env and fill in your PostgreSQL connection strings:

cp .env.example .env

You need up to 3 PostgreSQL databases:

VariablePurposeRequired
DATABASE_URLMain DB — workspaces, monthly_kpi, company_groups, etc.Yes
DATABASE_URL_SUB_EVENTSSub-events DB — monthly_sub_eventsFor sub-event tools
DATABASE_URL_DAILYDaily KPI DB — daily_kpiFor daily KPI tools

3. Push Schema

npx prisma db push

This creates all tables in your main database.

4. Generate API Key

DATABASE_URL="your-connection-string" npm run seed-key

Save the printed key — you'll need it for your MCP client config.

5. Deploy to Vercel

npx vercel --prod

Set the same environment variables in Vercel dashboard or via CLI:

vercel env add DATABASE_URL
vercel env add DATABASE_URL_SUB_EVENTS
vercel env add DATABASE_URL_DAILY

6. Connect MCP Client

Add to your Claude Code config (~/.claude.json):

{
  "mcpServers": {
    "kolr-health": {
      "type": "url",
      "url": "https://YOUR-DEPLOYMENT.vercel.app/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Available Tools (23)

Global (5)

  • getDataStatus — Data freshness check
  • getSnapshot — Dashboard overview with company counts and contract expiry
  • getTopCompanies — Top N companies by events
  • detectAnomalies — Spike/crash/risk/health-drop detection
  • getFlashReport — Global KPI summary with period comparison

Company (8)

  • listCompanies — Search and filter companies
  • lookupCompany — Fuzzy company lookup with recent KPIs
  • getCompanyKpi — Monthly KPI for a company group
  • getCompanyDailyKpi — Daily-level KPI with custom billing cycles
  • getCompanyDetails — CRM records and payment history
  • getCompanySubEvents — Feature adoption breakdown
  • getCompanyIntent — Create vs visit intent analysis
  • getCompanyReport — Pre-generated AI reports

Analysis (6)

  • getBenchmark — Market benchmark metrics
  • getContractExpiry — Contract expiration tracking
  • getFunnel — Registration-to-payment funnel
  • getQoQ — Quarter-over-quarter health trends
  • getMetricTrend — Single metric trend over time
  • getMetricRanking — Company rankings by metric

Users (4)

  • getLowEngagement — Low-engagement workspaces by funnel stage
  • getOrphanUsers — Users who never entered a workspace
  • getAttributedCompanies — Companies by activity/payment matrix
  • listCountries — Available countries

Auth & Scopes

API keys support scope-based access control:

ScopeEffect
allFull access (default)
crm_onlyOnly CRM-enabled workspaces
country:tw,jpOnly specified countries
owner:NameOnly workspaces owned by specified sales rep
companies:1,2,3Only specified company IDs

Create a scoped key:

DATABASE_URL="..." node scripts/seed-key.mjs "japan-team" '["country:jp"]'

Architecture

src/
├── app/api/mcp/[transport]/route.ts   # MCP endpoint (Streamable HTTP)
├── lib/
│   ├── prisma.ts                       # Main DB (Prisma + PrismaPg adapter)
│   ├── prisma-sub.ts                   # Sub-events DB (pg Pool)
│   ├── prisma-daily.ts                 # Daily KPI DB (pg Pool)
│   ├── scope-filter.ts                 # Scope-based SQL filtering
│   ├── kpi-aggregate.ts                # Benchmark computation
│   ├── period-utils.ts                 # Period/time helpers
│   ├── constants.ts                    # MIN_MONTH constant
│   └── mcp/
│       ├── auth.ts                     # API key auth (SHA-256)
│       └── tools/
│           ├── global.ts               # 5 global tools
│           ├── companies.ts            # 8 company tools
│           ├── analysis.ts             # 6 analysis tools
│           └── users.ts                # 4 user tools

License

MIT

Ver o original no GitHub

Bom para

Relacionados