Skip to main content
Glama

💬 Circle Community MCP (circle-community-mcp)

Servidor MCP (Model Context Protocol) para comunidades no Circle.so — API interna autenticada (/internal_api/), TipTap JSON nativo, upload direto de capas via Rails ActiveStorage e Modo Fantasma 100% invisível no Windows.

MCP Standard Python 3.10+ Chrome CDP SQLite Queue License: MIT

Arquitetura • As 18 Ferramentas (7 Famílias) • Instalação em 2 Minutos • Exemplos de Prompts • Auto-Healing


⚡ O Problema que o circle-community-mcp Resolve

Automatizar comunidades hospedadas no Circle.so (como a Engenheiros de Vídeo ou qualquer comunidade de alunos/criadores) costuma esbarrar em três barreiras:

  1. A API pública do Circle exige plano Enterprise/Admin: membros comuns não têm chave de API para ler o feed, buscar vagas, responder comentários ou publicar seus projetos diretamente do terminal.

  2. Automação via cliques no navegador é lenta e quebra: abrir uma janela do Playwright que rouba o foco da sua tela, esperar o editor ProseMirror carregar e simular digitação tecla por tecla leva vários segundos e falha quando o layout muda.

  3. Conflito entre múltiplos agentes: se você estiver rodando Claude Code, Google Antigravity e Cursor ao mesmo tempo, dois processos tentando controlar o mesmo navegador corrompem o perfil do Chrome.

Como nossa engenharia resolve isso:

O circle-community-mcp separa o navegador da fila de execução em duas portas dedicadas (9363 e 9364) e opera dentro da sessão autenticada do seu navegador, disparando chamadas HTTP diretas nos endpoints /internal_api/ do Circle com o seu cookie e token X-CSRF-Token:

  • Velocidade de API com login normal de membro: listar Spaces, ler o chat ao vivo (Papo), buscar vagas, dar like ou publicar um post com formatação TipTap JSON (incluindo links clicáveis, menções @[Nome](url) e upload nativo de imagem de capa via /rails/active_storage/direct_uploads) leva milissegundos em vez de dezenas de segundos clicando na tela.

  • Fallback Híbrido ProseMirror (dom_bypass.js): se algum endpoint interno do Circle exigir interação visual, o motor aciona automaticamente o fallback em DOM/Shadow-DOM e React Fiber.

  • Modo Fantasma de 4 Camadas no Windows (Zero-Tray + Zero-Taskbar): depois que você faz login uma única vez, o navegador roda 100% invisível em segundo plano. Ele não aparece na Barra de Tarefas, não aparece no Alt+Tab, não abre ícone no System Tray e nunca rouba o foco do seu teclado.


Related MCP server: WinMind

🏗️ Arquitetura Dual-Port & Modo Fantasma (4 Camadas)

O servidor foi desenhado para rodar 100% em paralelo com outros MCPs baseados em Chrome CDP (como Flow Studio :9333/:9334, Adobe Podcast :9343/:9344 e AI Studio Voice :9353/:9354), sem colisão de portas nem vazamento de áudio.

flowchart LR
    subgraph Clientes["🤖 Clientes MCP (Simultâneos)"]
        A1["Claude Code CLI"]
        A2["Google Antigravity"]
        A3["Cursor IDE"]
    end

    subgraph FastMCP["⚡ circle_mcp_server.py"]
        M["FastMCP Server (18 Tools / 7 Famílias)"]
    end

    subgraph Daemon["🗄️ Fila Central (:9364)"]
        D["circle_queue_daemon.py (aiohttp HTTP)"]
        DB[("circle_queue.db (SQLite Audit & Lock)")]
        D --> DB
    end

    subgraph GhostChrome["👻 Chrome Ghost CDP (:9363)"]
        C["Perfil Isolado (C:\\circle-mcp-profile)"]
        W["Win32 Ghost Layer: SW_HIDE + WS_EX_TOOLWINDOW + DeleteTab + (-32000,-32000)"]
        S["Triple Audio Silence Shield (--mute-audio + CDP Mute + WebAudio ZeroGain)"]
        C --- W
        C --- S
    end

    subgraph Circle["🌐 Circle.so (Sessão Autenticada)"]
        API["/internal_api/* + X-CSRF-Token + TipTap JSON"]
        UP["/rails/active_storage/direct_uploads (Capas & Anexos)"]
        DOM["Fallback ProseMirror / React Fiber (dom_bypass.js)"]
    end

    A1 & A2 & A3 -->|stdio MCP| M
    M -->|HTTP JSON 127.0.0.1:9364| D
    D -->|Playwright CDP 127.0.0.1:9363| C
    C -->|In-Page Fetch (ms)| API
    C -->|Direct Upload MD5| UP
    C -.->|Auto-Fallback| DOM

Por que 4 camadas no Modo Fantasma do Windows?

O Chrome precisa de uma janela de renderização real para manter sessões complexas, WebSockets de chat e tokens CSRF vivos sem throttling. Para que essa janela nunca incomode você enquanto edita vídeo ou programa, o circleapi.py aplica quatro travas combinadas via user32.dll e COM (ITaskbarList):

Camada

Tecnologia Aplicada

O que faz na prática

1. Off-Screen Coordinates

--window-position=-32000,-32000

Posiciona a janela fora do espaço visível de todos os monitores desde o boot do processo.

2. Remoção da Barra de Tarefas

ITaskbarList::DeleteTab(hwnd)

Remove o ícone do Chrome da Barra de Tarefas do Windows (a barra fica limpa).

3. Remoção do Alt+Tab

WS_EX_TOOLWINDOW (SetWindowLongPtrW)

Marca a janela como ToolWindow oculta para que ela nunca apareça quando você alterna janelas com Alt+Tab.

4. Ocultação Win32 sem Minimizar

ShowWindow(hwnd, SW_HIDE) + --disable-renderer-backgrounding

Esconde a superfície da janela no nível do sistema operacional mantendo o motor V8 e a rede ativos a 100% da velocidade.

Precisa ver o navegador para logar ou conferir algo? Basta chamar circle_show_browser() (traz a janela para a coordenada 120, 80 da sua tela) e depois circle_hide_browser() para devolvê-la ao Modo Fantasma.


🗺️ Mapa Completo das 18 Ferramentas (7 Famílias)

O circle-community-mcp expõe 18 ferramentas organizadas em 7 famílias para que o seu agente possa navegar, pesquisar, conversar, publicar e editar posts na comunidade:

1️⃣ Comunidades & Spaces

Ferramenta

Parâmetros Principais

O que faz

circle_list_spaces

community_url=""

Lista os dados da comunidade logada (/internal_api/communities), todos os Spaces de postagem, cursos, eventos, salas de chat (/internal_api/spaces) e conversas de DM (/internal_api/chat_rooms).

2️⃣ Chat Ao Vivo & Mensagens Diretas (DMs)

Ferramenta

Parâmetros Principais

O que faz

circle_get_chat_messages

chat_url_or_slug="papo", limit=40

Puxa as mensagens em tempo real do chat geral da comunidade (ex.: Papo) ou de qualquer sala/DM informando o nome do contato ou UUID da conversa.

circle_send_chat_message

message, chat_url_or_slug="papo", attachment_path=""

Envia mensagem no chat ao vivo ou em uma DM via POST /internal_api/chat_rooms/<uuid>/messages com suporte a anexos e fallback ProseMirror.

3️⃣ Feed, Postagens, Edição In-Place, Comentários & Likes

Ferramenta

Parâmetros Principais

O que faz

circle_get_posts

space_url_or_slug="", limit=15

Puxa os posts recentes do Feed Geral ("") ou de qualquer Space específico ("projetos", "ia", "edicao", "motion", "negocios", "clones", "hyperframes", "get-brolls").

circle_get_post_comments

post_id_or_url, page_num=1

Puxa a árvore completa de comentários e respostas de um post (/internal_api/posts/<id>/comments).

circle_create_post

space_url_or_slug, title, body, attachment_path=""

Cria e publica um novo post em qualquer Space. Converte quebras de linha, links https://... e menções @[Nome](url) para TipTap JSON nativo e faz upload da imagem de capa via Rails ActiveStorage DirectUpload.

circle_edit_post

space_url_or_slug, post_id_or_slug, title="", body="", attachment_path=""

Edição In-Place (PUT /internal_api/spaces/<space_id>/posts/<post_id>): atualiza título, texto ou capa de um post já publicado sem criar post duplicado e preservando os likes e comentários existentes.

circle_comment_post

post_url, comment_text

Publica um comentário ou resposta em qualquer post (aceita ID numérico ou URL completa).

circle_like_post

post_id_or_url

Dá like em um post (POST /internal_api/posts/<id>/user_likes).

4️⃣ Busca Global & Radar de Oportunidades / Vagas

Ferramenta

Parâmetros Principais

O que faz

circle_search

query, include_chat=True, limit=25

Vasculha simultaneamente os posts do Feed, o Space de Oportunidades (/c/motion) e o histórico do Chat Ao Vivo (Papo) atrás de vagas, freelas, ferramentas ou dúvidas técnicas.

5️⃣ Membros, Networking & Perfis

Ferramenta

Parâmetros Principais

O que faz

circle_list_members

limit=30

Lista membros ativos da comunidade, contatos de DM e ranking do leaderboard (/internal_api/gamification/members).

circle_get_member_profile

public_uid

Puxa a ficha completa de um membro (/internal_api/profiles/<public_uid>?page_name=profile_view): bio, headline, redes sociais, Instagram, links, localização e pontuação.

6️⃣ Notificações & Menções

Ferramenta

Parâmetros Principais

O que faz

circle_get_notifications

unread_only=False, limit=25

Lista as notificações da sua conta (/internal_api/notifications): quem comentou no seu post, quem mencionou você com @ e novos posts nos Spaces que você segue.

7️⃣ Controle Fantasma Invisível & Auto-Healing

Ferramenta

Parâmetros Principais

O que faz

circle_login_browser

url="https://login.circle.so/"

Abre e traz para a frente a janela do Chrome isolado (porta 9363) para você fazer o login inicial na sua conta do Circle.so.

circle_hide_browser

(nenhum)

Ativa imediatamente o Modo Fantasma de 4 camadas (SW_HIDE + WS_EX_TOOLWINDOW + sem Taskbar) e salva o selo .login_completed.

circle_show_browser

(nenhum)

Traz a janela do Chrome (porta 9363) de volta para a tela principal (120, 80) caso você queira inspecionar algo visualmente.

circle_status

(nenhum)

Retorna o status de saúde do Daemon (:9364), da conexão CDP (:9363), URL ativa, estado do login e contador de chamadas de rede.

circle_diagnose

reason="manual_check", take_screenshot=True

Executa o Raio-X completo de Auto-Healing: varre DOM + Shadow-DOM, lista seletores interativos, captura as últimas 60 chamadas /internal_api/ e tira screenshot de diagnóstico.

circle_update_selectors / circle_reload_daemon

selectors={...}

Atualiza selectors.json em tempo real e recarrega o módulo circleapi.py a quente (importlib.reload) sem derrubar o servidor MCP.


🚀 Como Instalar e Usar em 2 Minutos

Pré-requisitos

  • Python 3.10+ instalado na máquina

  • Google Chrome instalado

  • Um cliente compatível com MCP (Claude Code, Google Antigravity, Cursor ou Windsurf)

Passo 1 — Clonar o repositório e instalar as dependências

git clone https://github.com/NicolasCoder/circle-community-mcp.git
cd circle-community-mcp
pip install -r requirements.txt
playwright install chromium

Passo 2 — Rodar o Instalador Universal de 1 Clique (setup_mcp.py)

O script setup_mcp.py detecta o caminho do seu Python e registra automaticamente o servidor circle-community e a SKILL.md no Claude Code, Google Antigravity e Cursor:

python setup_mcp.py

Adicione o bloco abaixo no seu arquivo de configuração MCP (~/.claude.json, ~/.cursor/mcp.json ou ~/.gemini/config/mcp_config.json):

{
  "mcpServers": {
    "circle-community": {
      "command": "python",
      "args": [
        "C:/caminho/para/circle-community-mcp/circle_mcp_server.py"
      ]
    }
  }
}

Passo 3 — Fazer o primeiro login (1 única vez)

Abra o seu agente (Claude Code, Antigravity ou Cursor) e peça:

"Abra o navegador de login do Circle com circle_login_browser para eu entrar na minha conta."

  1. Uma janela limpa do Chrome (no perfil isolado C:\circle-mcp-profile) vai se abrir na tela de login do Circle.so.

  2. Faça login normalmente na sua conta e entre na sua comunidade (ex.: https://engenheiros-de-video.circle.so).

  3. Peça ao agente: "Pode esconder o navegador do Circle com circle_hide_browser."

  4. Pronto! A sessão fica salva no perfil isolado e todas as próximas execuções já iniciam direto no Modo Fantasma 100% invisível.


💬 Exemplos Reais de Uso (Prompts Prontos)

Depois de logado, você conversa com a sua comunidade diretamente pelo chat do seu agente:

📦 1. Publicar um projeto novo no espaço Projetos (com capa e links)

"Publique um post no espaço projetos do Circle apresentando o nosso novo repositório do GitHub. Coloque um título chamativo, explique em 3 passos como a galera pode testar e anexe a imagem ./capa_projeto.png."

🔎 2. Radar de Vagas e Freelas de Edição / Motion

"Use o circle_search para buscar vagas de editor, freela, premiere ou after effects publicadas nos últimos dias no Space de Oportunidades e no chat Papo, e me traga um resumo com o link e o autor de cada uma."

💬 3. Responder comentários e interagir com a galera

"Verifique minhas notificações recentes no Circle (circle_get_notifications), veja quem comentou no meu último post no espaço projetos e responda agradecendo e tirando as dúvidas técnicas."

✏️ 4. Atualizar um post já publicado sem criar duplicata (In-Place Edit)

"Use circle_edit_post no meu post do espaço projetos para adicionar o link atualizado da documentação no final do texto, mantendo a imagem de capa original."

🤝 5. Mapear membros e fazer networking

"Liste os membros mais ativos da comunidade com circle_list_members, puxe o perfil dos 5 primeiros com circle_get_member_profile e me mostre quem trabalha com Motion Design e automação com IA."


🛡️ Auto-Healing e Diagnóstico (DOM + Rede)

Se o Circle.so atualizar algum componente visual ou rota interna no futuro, você não precisa adivinhar o que mudou:

  1. Chame circle_diagnose(reason="check_ui", take_screenshot=True).

  2. O motor dom_bypass.js varre todos os elementos interativos (incluindo Shadow-DOM e editores ProseMirror/TipTap) e o sniffer de rede do daemon entrega o histórico das últimas 60 chamadas JSON em /internal_api/.

  3. Atualize qualquer seletor em tempo real com circle_update_selectors(...) e aplique sem reiniciar o cliente MCP usando circle_reload_daemon().


📁 Estrutura do Repositório

circle-community-mcp/
├── circle_mcp_server.py     # Servidor FastMCP (expõe as 18 tools para Claude/AGY/Cursor)
├── circle_queue_daemon.py   # Daemon HTTP (:9364) + Fila Central SQLite + Sniffer de Rede
├── circleapi.py             # Motor Híbrido (/internal_api/ + TipTap JSON + ActiveStorage + Win32 Ghost Mode)
├── dom_bypass.js            # Runtime JS injetado via CDP (Shadow-DOM Piercing + React Fiber + Audio Silence Shield)
├── setup_mcp.py             # Instalador Universal 1-Clique (Antigravity, Claude Code e Cursor)
├── config.json              # Configurações de portas (9363/9364), visibilidade e timeouts
├── accounts.json            # Gerenciador de perfis isolados do Chrome (sanitizado)
├── selectors.json           # Mapa vivo de seletores DOM e endpoints monitorados pelo Auto-Healing
├── cover_style_preset.json  # Preset visual 3D Origami Cats para capas de posts na comunidade
├── SKILL.md                 # Skill oficial com instruções de uso para agentes autônomos
├── .env.example             # Variáveis de ambiente opcionais para customização de portas e perfil
├── requirements.txt         # Dependências Python (mcp, playwright, aiohttp, psutil, Pillow)
└── assets/                  # Logos e referências visuais da comunidade

📄 Licença

Distribuído sob a licença MIT. Veja LICENSE para mais detalhes.

Construído por Nicolas Rezende (@NicolasCoder) para a comunidade Engenheiros de Vídeo.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to operate and monitor Windows workspaces through native tools for filesystem operations, PowerShell execution, background tasks, Windows services, GPU telemetry, PDF generation, and a built-in web gateway/dashboard.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables an AI to see and drive any Windows application through the accessibility tree - reading real element names, states and actions and invoking the app's own controls without screenshots or moving the mouse, even for windows behind others. Also exposes 200+ native Windows tools for system health, hardware, network, privacy, files, processes, registry, media and more.
      3
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to drive your own signed-in ChatGPT web account — asking questions, continuing chats, attaching files, toggling thinking or web search, creating images, transcribing recordings of any length, reading replies aloud, and managing conversations, memories and projects. It runs against a local Chrome tab on chatgpt.com and reports live progress and step-named errors back to the client.
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Gives AI agents a single shared, logged-in Chrome they can drive over MCP or plain HTTP: open and read tabs, click, type, upload files, run short Playwright scripts, hand off whole web tasks to a cheaper model, and keep per-site memory. Agents work in background windows they own without stealing the user's mouse or closing their tabs.
      MIT