CompanyIQ MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Overview CompanyIQ MCP is a Model Context Protocol server for Norwegian company intelligence and market analysis. It integrates with Brønnøysund Register Centre (company registry) and Statistics Norway (SSB) APIs to provide business intelligence tools for Claude Desktop. ## Commands ```bash # Build the TypeScript project (compiles to build/, copies schema.sql) npm run build # Watch mode for development npm run watch # Run data sync (if sync-data.js exists) npm run sync ``` ## Architecture ### MCP Server Structure - **Entry point**: `src/index.ts` - Registers all MCP tools and routes requests to handlers - **Tools**: `src/tools/*.ts` - Each file implements one MCP tool (e.g., `search_companies.ts`, `analyze_financials.ts`) - **API clients**: `src/apis/brreg.ts` (Brønnøysund Registry), `src/apis/ssb.ts` (Statistics Norway) - **Database**: `src/database/db.ts` + `schema.sql` - SQLite with better-sqlite3 for caching - **Analytics**: `src/analytics/*.ts` - Growth scoring, risk analysis logic - **Scraper**: `src/scraper/*.ts` - Puppeteer browser automation + OpenAI Vision for PDF parsing ### Data Flow 1. MCP tools receive requests via `CallToolRequestSchema` handler in index.ts 2. Tools query local SQLite cache first, then fetch from APIs if needed 3. Results cached with TTL (default 24h via `CACHE_TTL_HOURS`) 4. Financial data can be auto-scraped from PDFs using headless Chrome ### Key Patterns - All tools follow signature: `(args, db, apiClient) => Promise<ToolResult>` - Database uses WAL mode with foreign keys enabled - API clients implement rate limiting (100ms between requests for Brønnøysund) - SSB data uses filter-aware caching with hash-based lookup ## Environment Variables Create `.env` in project root: ``` BRREG_API_BASE_URL=https://data.brreg.no/enhetsregisteret/api SSB_API_BASE_URL=https://data.ssb.no/api/pxwebapi/v2 OPENAI_API_KEY=sk-... # Required for PDF parsing with Vision CACHE_TTL_HOURS=24 ``` ## Database Schema SQLite database at `data/companies.db` with tables: - `companies` - Main company records (org_nr as PK) - `financial_snapshots` - Year-by-year financials (org_nr + year unique) - `board_members` - Leadership/board with role types (DAGL=CEO, LEDE=Chair, MEDL=Member) - `ownership`, `subunits`, `company_history` - Related company data - `ssb_cache`, `market_analysis` - API response caching ## Adding New Tools 1. Create `src/tools/new_tool.ts` with handler function 2. Register in `src/index.ts`: - Import the handler - Add tool schema to `ListToolsRequestSchema` handler - Add case to `CallToolRequestSchema` switch statement 3. Rebuild with `npm run build` ## Common NACE Codes (Norwegian Industry Classification) - 62: IT/Software - 64: Financial services - 70: Management consulting - 71: Architecture/Engineering - 45-47: Construction/Trade