​

CLAUDE.md

​

Project Overview

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

just update-api   # Update OpenAPI spec from live API
just dev           # Start Mintlify dev server (checks mintlify is installed)

​

Manual commands

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
• MCP Server Repository: https://github.com/horizondatawave/hdw-mcp-server
• n8n Nodes Repository: https://github.com/horizondatawave/n8n-nodes-anysite
• Mintlify Documentation: https://mintlify.com/docs

​

API Structure & Authentication

• Base URL: 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

# 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" ...

​

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

​

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

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

# Run the filtering script (or: just update-api)
python3 filter_openapi.py

• Downloads the live OpenAPI spec from 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

• 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

​

AI 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 спецификации

# Запуск фильтрации OpenAPI спецификации
python3 filter_openapi.py

• Загружает актуальную OpenAPI спецификацию с 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:
   just update-api
   
2. При изменениях в MCP сервере:
   • Проверить репозиторий: https://github.com/horizondatawave/hdw-mcp-server
   • Обновить файлы в папке mcp-server/
3. При изменениях в n8n нодах:
   • Проверить репозиторий: 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. Проверка изменений:
   just dev  # Локальный предварительный просмотр
   
6. Тестирование:
   • Проверить все интерактивные примеры
   • Убедиться в корректности кросс-ссылок
   • Проверить отображение всех изображений
   • Протестировать AI функции (кнопки “AI Prompt”)

​

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

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

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

​

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

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