osint-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

OSINT MCP — the fifth project in the MCP security suite. Provides AI agents with access to OSINT data sources: Shodan, Censys, VirusTotal, SecurityTrails + public DNS/WHOIS/crt.sh/Wayback/BGP/IP geolocation.

Published as npx osint-mcp-server on npm. Public tools work without API keys; paid providers (Shodan, VT, SecurityTrails, Censys) require env vars and return descriptive messages when keys are missing.

Build & Development Commands

bun install                    # Install dependencies
bun run dev                    # Watch mode (bun --watch run src/index.ts)
bun run build                  # Compile for npm (tsc -p tsconfig.build.json → dist/)
npm publish                    # Publishes to npm (prepublishOnly runs build automatically)
npx . --help                   # Test local package as if installed via npx

No test framework is set up yet. When adding tests, use bun test (Bun's built-in test runner).

Architecture

Follows the same architecture as cve-mcp, github-security-mcp, cloud-audit-mcp, and hackbrowser-mcp.

Core Pattern

src/
├── index.ts                  # Entry point: shebang, buildToolContext(), main()
├── types/
│   └── index.ts              # ToolDef, ToolContext, ToolResult interfaces + text()/json() helpers
├── protocol/
│   ├── mcp-server.ts         # Creates McpServer, loops allTools to register, stdio transport
│   └── tools.ts              # All ToolDef objects + allTools[] export
├── <provider>/               # One directory per data source
│   └── index.ts              # API functions (fetch calls, response normalization)
└── utils/
    ├── rate-limiter.ts       # Shared RateLimiter (prevents 429s)
    └── cache.ts              # TTLCache with expiry

Key Interfaces

interface ToolDef {
  name: string;                                          // e.g. "shodan_search"
  description: string;
  schema: Record<string, z.ZodType>;                     // Zod validators per param
  execute: (args: Record<string, unknown>, ctx: ToolContext) => Promise<ToolResult>;
}

interface ToolContext {
  config: { shodan_api_key?: string; vt_api_key?: string; /* ... */ };
  // shared caches, rate limiters
}

interface ToolResult {
  content: { type: "text"; text: string }[];
}