Configuração do Discourse MCP no CLI do OpenCode

Wiki da comunidade Usuários
, ,
1

Este guia fornece instruções testadas para instalar o Discourse MCP no OpenCode CLI. Se você estiver usando um cliente MCP diferente, também escrevi guias para o Codex CLI.

USE SEU LLM! LLMs são muito bons em seguir instruções e podem fazer a configuração para você. Aponte o LLM para este guia por URL e peça-lhe para fazer a configuração. Você também pode pedir-lhe para explicar quaisquer etapas que não entenda.

Pré-requisitos

  • Node.js instalado (24 LTS recomendado)
  • OpenCode CLI instalado
  • Acesso ao fórum Discourse pretendido como um usuário comum (não é necessário ser um administrador!)

É importante perceber que existem três componentes separados aqui:

  1. O fórum Discourse remoto, que é a fonte de dados e o destino para as ações.

  1. O servidor Discourse MCP, que é uma ferramenta de código aberto executada localmente que se conecta ao Discourse e fornece uma API para o OpenCode interagir com o Discourse. Isto é instalado como um pacote NPX e lançado sob demanda pelo OpenCode CLI.

  1. O OpenCode CLI, que é o cliente MCP que se conecta ao servidor MCP e fornece a interface para interagir com o Discourse através da API do MCP.

1. Gerar a chave de API de Usuário

Isso o autenticará no Discourse e é assim que você obterá sua chave de API. O npx baixará e executará o código, nada precisa ser instalado no sentido tradicional.

Em um terminal, execute:

npx @discourse/mcp@latest generate-user-api-key \
  --site =DISCOURSE-FORUM= \
  --save-to =PROFILE-PATH=/=NAME=.json

Exemplo:

npx @discourse/mcp@latest generate-user-api-key \
  --site https://meta.discourse.org \
  --save-to ~/.config/opencode/discourse-profiles/meta.json

Aprove o consentimento do navegador e copie de volta os dados criptografados, o que comprova sua capacidade de fazer login e gera uma chave de API que é salva em =PROFILE-PATH= para uso pelo servidor MCP.

A chave de API terá o mesmo nível de acesso ao fórum que você tem como usuário.

2. Adicionar o servidor MCP ao OpenCode CLI

Edite seu arquivo de configuração do OpenCode em ~/.config/opencode/opencode.jsonc e adicione a seguinte entrada à seção mcp:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    // ... outros servidores MCP ...
    "discourse-=NAME=-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@discourse/mcp@latest",
        "--profile",
        "=PROFILE-PATH=/=NAME=.json",
      ],
      "enabled": true,
      "environment": {},
    },
  },
}

Exemplo:

"discourse-meta-mcp": {
  "type": "local",
  "command": [
    "npx",
    "-y",
    "@discourse/mcp@latest",
    "--profile",
    "/home/marcus/.config/opencode/discourse-profiles/meta.json"
  ],
  "enabled": true,
  "environment": {},
},

O servidor MCP será iniciado sob demanda com npx pelo OpenCode CLI quando você iniciar o OpenCode. Ele está configurado para usar o perfil em =PROFILE-PATH= e, por padrão, é somente leitura.

3. Reiniciar o OpenCode CLI

Reinicie completamente o OpenCode para que ele recarregue a configuração e se conecte ao servidor MCP.

Se ele iniciar sem erros, o servidor Discourse MCP está funcionando. Você pode pedir ao OpenCode para consultar seu fórum Discourse em busca de informações — especialmente informações às quais você tem acesso, mas que não são públicas — isso verificará se ele está se conectando como você.

4. Habilitar Recursos de Escrita (Opcional)

Por padrão, o servidor Discourse MCP é executado no modo somente leitura. Para habilitar operações de escrita (criação de posts, tópicos, usuários, etc.), você precisa adicionar duas flags ao seu arquivo de perfil JSON.

Edite =PROFILE-PATH=/=NAME=.json e adicione "read_only": false e "allow_writes": true como irmãos do array auth_pairs:

{
  "read_only": false,
  "allow_writes": true,
  "auth_pairs": [
    {
      "site": "=DISCOURSE-FORUM=",
      "user_api_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "user_api_client_id": "discourse-mcp"
    }
  ]
}

Exemplo:

{
  "read_only": false,
  "allow_writes": true,
  "auth_pairs": [
    {
      "site": "https://meta.discourse.org",
      "user_api_key": "abc123def456ghi789jkl012mno345pqr",
      "user_api_client_id": "discourse-mcp"
    }
  ]
}

Após adicionar essas flags, reinicie o OpenCode CLI para que as alterações entrem em vigor. O servidor MCP agora permitirá operações de escrita como:

  • Criação e atualização de tópicos
  • Criação de posts e respostas
  • Gerenciamento de rascunhos
  • Upload de arquivos
  • Criação de categorias (se você tiver permissão)
  • Gerenciamento de usuários (se você tiver permissão de administrador)

Aviso: As operações de escrita usarão as permissões da sua conta de usuário. Qualquer conteúdo criado aparecerá como se você o tivesse criado manualmente. Use os recursos de escrita com responsabilidade.

Gerenciando Múltiplas Instâncias do Discourse

Você pode adicionar vários fóruns Discourse repetindo o processo com diferentes arquivos de perfil e nomes de servidor MCP:

"discourse-meta-mcp": {
  "type": "local",
  "command": [
    "npx", "-y", "@discourse/mcp@latest",
    "--profile", "/home/username/.config/opencode/discourse-profiles/meta.json"
  ],
  "enabled": true,
  "environment": {},
},
"discourse-mycommunity-mcp": {
  "type": "local",
  "command": [
    "npx", "-y", "@discourse/mcp@latest",
    "--profile", "/home/username/.config/opencode/discourse-profiles/mycommunity.json"
  ],
  "enabled": true,
  "environment": {},
},

Arquivos de Configuração

Existem dois arquivos principais:

  1. =OPENCODE-CONFIG= - Arquivo de configuração do OpenCode CLI em ~/.config/opencode/opencode.jsonc, que inclui as configurações do servidor MCP.

  2. =PROFILE-PATH= - O perfil para o servidor Discourse MCP, que inclui a chave de API e outras configurações para conectar-se ao Discourse.

Configurações do OpenCode

As configurações para conectar-se ao servidor MCP estão em =OPENCODE-CONFIG= (tipicamente ~/.config/opencode/opencode.jsonc):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "discourse-=NAME=-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@discourse/mcp@latest",
        "--profile",
        "=PROFILE-PATH=/=NAME=.json",
      ],
      "enabled": true,
      "environment": {},
    },
  },
}

Documentação das Configurações do OpenCode MCP: Documentação do OpenCode

Configurações do Discourse MCP

As configurações para o próprio servidor Discourse MCP estão em =PROFILE-PATH=/=NAME=.json=:

{
  "auth_pairs": [
    {
      "site": "=DISCOURSE-FORUM=",
      "user_api_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "user_api_client_id": "discourse-mcp"
    }
  ]
}

Documentação das configurações do Discourse MCP: GitHub - discourse/discourse-mcp

Melhores Práticas de Segurança

É recomendado:

  1. Armazenar arquivos de perfil em um diretório dedicado (ex: ~/.config/opencode/discourse-profiles/)
  2. Adicionar este diretório ao .gitignore se você estiver rastreando seus dotfiles em controle de versão
  3. Usar nomes descritivos para seus arquivos de perfil (ex: meta.json, mycommunity.json)
  4. Manter as chaves de API privadas - elas têm o mesmo nível de acesso que sua conta de usuário

Solução de Problemas

  • Problemas de conexão: Verifique se o caminho do perfil em opencode.jsonc está correto e se o arquivo existe
  • Erros de autorização: Verifique se a chave de API não foi revogada em suas preferências de usuário do Discourse
  • Erros de permissão: Certifique-se de ter as permissões necessárias na instância do Discourse
  • Reinicialização necessária: Alterações em opencode.jsonc exigem a reinicialização do OpenCode CLI
3 curtidas