> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anysite.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLAUDE

# CLAUDE.md

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

## Project Overview

This is a comprehensive documentation project for **anysite.io**, built using the **Mintlify** documentation platform. The project covers three main components:

1. **API Documentation** - Complete REST API reference with OpenAPI synchronization
2. **MCP Server Documentation** - Model Context Protocol server for AI integration
3. **n8n Nodes Documentation** - Community nodes for workflow automation

## Project Goals

* Create comprehensive, user-friendly documentation for the entire anysite.io ecosystem
* Maintain automatic synchronization with OpenAPI specifications
* Provide interactive examples and code playgrounds
* Support developers integrating with Anysite services across different platforms

## Development Environment

### Prerequisites

* **uv** — Python package manager
* **just** — command runner
* **mintlify** — docs CLI (`npm install -g mintlify`)

### just recipes

```bash theme={null}
just update-api   # Update OpenAPI spec from live API
just dev           # Start Mintlify dev server (checks mintlify is installed)
```

### Manual commands

```bash theme={null}
uv sync            # Install/update Python dependencies
mintlify dev       # Local dev server at http://localhost:3000
mintlify build     # Build documentation
mintlify deploy    # Deploy to production
```

## Project Structure

```
/
├── justfile              # just command recipes
├── pyproject.toml        # Python dependencies (uv)
├── docs.json             # Mintlify configuration (migrated from mint.json)
├── openapi-filtered.json # Filtered OpenAPI specification
├── filter_openapi.py     # OpenAPI filtering script
├── llms.txt             # AI documentation indexing
├── .ai/                 # AI assistant instructions
├── public/               # Public assets
│   └── images/
│       ├── make_mcp/     # Make AI Agent integration screenshots
│       └── clay_mcp/     # Clay AI Agent integration screenshots
├── api/                  # API Documentation
│   ├── authentication.mdx
│   ├── endpoints/
│   └── examples/
├── mcp-server/           # MCP Server Documentation
│   ├── tools.mdx
│   ├── unlimited-plan.mdx
│   ├── unlimited-plan-make.mdx  # Make AI Agent integration guide
│   ├── unlimited-plan-clay.mdx  # Clay AI Agent integration guide
│   ├── local-server/
│   ├── claude-desktop-tool/
│   ├── claude-code-tool/
│   └── n8n-tool/
├── n8n-nodes/            # n8n Nodes Documentation
│   ├── installation.mdx
│   ├── nodes/
│   └── workflows/
├── cli/                  # Anysite CLI Documentation
│   ├── overview.mdx
│   ├── installation.mdx
│   ├── agent-protocol.mdx  # Agent Protocol (JSON envelope, exit codes, discovery)
│   ├── endpoints.mdx
│   ├── api-calls.mdx
│   ├── batch-processing.mdx
│   ├── datasets/         # Dataset Pipelines
│   ├── database/         # Database Operations
│   │   ├── connections.mdx
│   │   ├── discovery.mdx   # Database Discovery & Catalog
│   │   └── operations.mdx
│   ├── llm-analysis.mdx
│   ├── querying.mdx
│   └── examples.mdx
├── claude-skills/        # Claude Skills Documentation
└── introduction.mdx      # Getting started guide
```

## Key Resources

* **OpenAPI Specification**: [https://api.anysite.io/openapi.json](https://api.anysite.io/openapi.json)
* **MCP Server Repository**: [https://github.com/horizondatawave/hdw-mcp-server](https://github.com/horizondatawave/hdw-mcp-server)
* **n8n Nodes Repository**: [https://github.com/horizondatawave/n8n-nodes-anysite](https://github.com/horizondatawave/n8n-nodes-anysite)
* **Mintlify Documentation**: [https://mintlify.com/docs](https://mintlify.com/docs)

## API Structure & Authentication

**IMPORTANT API Details**:

* **Base URL**: [https://api.anysite.io](https://api.anysite.io)
* **Authentication**: `access-token` header (NOT Bearer tokens)
* **HTTP Methods**: All main endpoints use POST method (except token management endpoints which use GET)
* **Request Format**: JSON request body for all POST endpoints
* **Endpoint Prefix**: All main API endpoints have `/api/` prefix

```bash theme={null}
# Correct authentication and request format
curl -X POST "https://api.anysite.io/api/linkedin/user" \
  -H "access-token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "linkedin.com/in/username"}'

# Token management endpoints (GET method)
curl -H "access-token: YOUR_API_KEY" https://api.anysite.io/token/statistic

# WRONG - DO NOT USE
curl -H "Authorization: Bearer YOUR_API_KEY" ...
```

All documentation examples use the correct `access-token` header format and POST methods.

## Content Synchronization

* OpenAPI specification is automatically synchronized from the live API using filtered version
* Unwanted endpoints (Payments, Subscriptions, Chat, Webhooks) are automatically excluded
* x-request-id parameters are automatically removed from all endpoints
* Repository documentation is manually updated when source repositories change
* Version control ensures consistency across all documentation sections

## MCP Unlimited Plan Integrations

The documentation includes comprehensive integration guides for AI agent platforms:

### Make AI Agent Integration

* **File**: `mcp-server/unlimited-plan-make.mdx`
* **Images**: `public/images/make_mcp/` (6 screenshots)
* **Focus**: Autonomous research agents, workflow automation, scheduled intelligence
* **Use Cases**: Lead enrichment, competitor monitoring, multi-platform research, recruitment

### Clay AI Agent Integration

* **File**: `mcp-server/unlimited-plan-clay.mdx`
* **Images**: `public/images/clay_mcp/` (3 screenshots)
* **Focus**: Data enrichment workflows, table-based automation, waterfall sequences
* **Use Cases**: Lead enrichment, company intelligence, multi-platform waterfall, talent sourcing

**Integration Pattern:**
Both guides follow consistent structure:

1. Overview & Prerequisites
2. Get MCP Connection URL (from app.anysite.io)
3. Configure MCP in platform (with screenshots)
4. System prompts & tool inventory
5. Use cases with examples
6. Workflow integration diagrams
7. Troubleshooting & security
8. Benefits & next steps

## OpenAPI Filtering & Navigation Generation

The project uses `filter_openapi.py` to process the OpenAPI specification and auto-generate Mintlify navigation:

```bash theme={null}
# Run the filtering script (or: just update-api)
python3 filter_openapi.py
```

**What the script does:**

* Downloads the live OpenAPI spec from [https://api.anysite.io/openapi.json](https://api.anysite.io/openapi.json)
* Removes x-request-id parameters and fixes OAuth security references
* Maps technical tag names to human-readable names (e.g. `/linkedin/company` → `LinkedIn Companies`)
* Embeds `x-llm-*` hints into endpoint descriptions for AI agents
* Removes endpoints with path parameters `{...}` (breaks Mintlify parser)
* Removes invalid schema names
* **Auto-generates nested sidebar navigation** in `docs.json` from `x-tagGroups` (Mintlify does not support `x-tagGroups` natively, so the script builds the `groups` structure manually)
* Generates llms.txt, llms-full.txt, and split JSON files for AI consumption

**Navigation auto-generation:**

* Groups are built from the OpenAPI `x-tagGroups` extension
* Each tag becomes a nested sub-group with its endpoints
* Single-tag groups are flattened to avoid duplication (e.g. SEC → endpoints directly, not SEC → SEC → endpoints)
* Both EN and ZH API Reference tabs are updated automatically

The filtered spec is saved as `openapi-filtered.json` and used by Mintlify for page generation.

## AI Features

The documentation includes AI-enhanced features:

* **AI Development Assistant**: Smart prompt generation system for API integration
  * **"AI Prompt" buttons** appear next to each API endpoint title
  * Automatically generates comprehensive integration prompts for AI development tools
  * Extracts endpoint details, authentication, request/response examples from Mintlify's rendered content
  * Provides production-ready implementation requirements and best practices
  * Works with Claude, ChatGPT, Perplexity, and other AI development tools
* **LLMs.txt**: Comprehensive API overview for AI tools consumption with all 51+ endpoints
  * Complete LinkedIn API coverage (39 endpoints organized by categories)
  * Correct HTTP methods (POST for main endpoints, GET for tokens)
  * Proper endpoint paths with `/api/` prefix
  * Authentication examples and request formats
* **Contextual Menu**: Copy, view, and share functionality with AI tools (ChatGPT, Claude, Perplexity)
* **AI Instructions**: Detailed guidance for AI assistants in `.ai/instructions.md`

## Development Workflow

1. Run `just update-api` when API changes to update filtered OpenAPI spec
2. Run `just dev` for local preview during editing
3. Test all interactive examples and code snippets
4. Ensure cross-references between sections work correctly
5. Build and verify before deployment

## Правила обновления документации

### Автоматическое обновление OpenAPI спецификации

Для обновления документации API используйте скрипт `filter_openapi.py`:

```bash theme={null}
# Запуск фильтрации OpenAPI спецификации
python3 filter_openapi.py
```

**Что делает скрипт:**

* Загружает актуальную OpenAPI спецификацию с [https://api.anysite.io/openapi.json](https://api.anysite.io/openapi.json)
* Убирает технические параметры (x-request-id) из всех эндпоинтов
* Встраивает x-llm хинты в описания эндпоинтов
* Улучшает названия тегов для лучшей читаемости
* Удаляет эндпоинты с path-параметрами `{...}` (ломают Mintlify)
* **Автоматически генерирует вложенную навигацию** в `docs.json` из `x-tagGroups`
* Сохраняет отфильтрованную версию в `openapi-filtered.json`
* Генерирует llms.txt, llms-full.txt и JSON файлы для AI

### Порядок обновления документации

1. **При изменениях в API:**
   ```bash theme={null}
   just update-api
   ```

2. **При изменениях в MCP сервере:**
   * Проверить репозиторий: [https://github.com/horizondatawave/hdw-mcp-server](https://github.com/horizondatawave/hdw-mcp-server)
   * Обновить файлы в папке `mcp-server/`

3. **При изменениях в n8n нодах:**
   * Проверить репозиторий: [https://github.com/horizondatawave/n8n-nodes-anysite](https://github.com/horizondatawave/n8n-nodes-anysite)
   * Обновить файлы в папке `n8n-nodes/`

4. **При добавлении новых AI интеграций:**
   * Создать файл в формате `mcp-server/unlimited-plan-{platform}.mdx`
   * Добавить скриншоты в `public/images/{platform}_mcp/`
   * Обновить `docs.json` в секции "MCP Unlimited Plan"
   * Следовать структуре существующих интеграций (Make, Clay)
   * Обновить `CLAUDE.md` в секции "MCP Unlimited Plan Integrations"

5. **Проверка изменений:**
   ```bash theme={null}
   just dev  # Локальный предварительный просмотр
   ```

6. **Тестирование:**
   * Проверить все интерактивные примеры
   * Убедиться в корректности кросс-ссылок
   * Проверить отображение всех изображений
   * Протестировать AI функции (кнопки "AI Prompt")

### Мониторинг изменений

**Автоматически отслеживаемые изменения:**

* OpenAPI спецификация синхронизируется с живым API
* Фильтрация применяется автоматически при запуске скрипта

**Ручной контроль версий:**

* Документация MCP сервера обновляется при изменениях в исходном репозитории
* Документация n8n нодов обновляется при релизах новых версий
* Документация AI интеграций (Make, Clay) обновляется при изменениях в UI платформ
* Общие разделы (введение, аутентификация) обновляются по мере необходимости

### Команды для обновления

```bash theme={null}
just update-api   # Обновить OpenAPI спецификацию
just dev           # Запустить dev сервер (проверяет установку mintlify)
```

## Important Notes

* Configuration migrated from `mint.json` to `docs.json` for modern Mintlify features
* **All API examples use correct patterns**:
  * `access-token` header authentication (NOT Bearer tokens)
  * POST method for main endpoints (LinkedIn, Twitter, Instagram, Reddit, Google)
  * GET method only for token management endpoints (`/token/statistic`, `/token/requests`, `/token/requests/count`)
  * JSON request body for all POST endpoints
  * Proper `/api/` prefix for all main endpoints
* **AI Development Assistant feature**:
  * JavaScript implementation in `public/ai-prompt.js` loaded via `docs.json` head scripts
  * Works with Mintlify's dynamic API page generation from OpenAPI specifications
  * Automatically adds "🤖 AI Prompt" buttons to endpoint titles
  * Extracts data from DOM (not OpenAPI files) for real-time content accuracy
  * Generates comprehensive prompts with endpoint details, authentication, examples, and implementation requirements
* Python dependencies managed via `uv` (`pyproject.toml`), virtual environment in `.venv/`
* `.venv/` and `.claude/` are in gitignore
* Contextual menu requires `docs.json` configuration format
* Filter script improves tag names and auto-generates nested sidebar navigation from `x-tagGroups`
* **LLMs.txt updated with complete API coverage**: 51+ endpoints including all 39 LinkedIn endpoints organized by functionality