Forgejo MCP Server

Gerencie repositórios Forgejo e execute comandos através de uma interface de chat compatível com MCP.

Documentação

Servidor MCP Forgejo

📦 Este projeto mudou de endereço. Desenvolvimento, issues, lançamentos e imagens de contêiner agora estão em https://git.b4mad.industries/agentic-forges/forgejo-mcp. O repositório Codeberg em codeberg.org/goern/forgejo-mcp permanece apenas como um espelho somente leitura, e seu registro de contêineres não publica mais imagens — faça pull de git.b4mad.industries/agentic-forges/forgejo-mcp em vez disso. Os números de issues são preservados na mudança. Contribuições de humanos e agentes de IA são bem-vindas no novo endereço.
git clone https://git.b4mad.industries/agentic-forges/forgejo-mcp.git
Se você tem um remote ou um marcador apontando para forgejo.b4mad.net, esse é o mesmo forge sob seu nome anterior — renomeado em 2026-07-29, não movido novamente. O nome antigo ainda resolve e atende na porta 2222 com a mesma chave de host, então clones existentes continuam funcionando; aponte-os novamente quando quiser:
git remote set-url origin \
  ssh://git@git.b4mad.industries:2222/agentic-forges/forgejo-mcp.git
ssh-keyscan -p 2222 git.b4mad.industries >> ~/.ssh/known_hosts

Conecte seu assistente de IA a repositórios Forgejo. Gerencie issues, pull requests, arquivos e muito mais por meio de linguagem natural.

O Que Ele Faz

O Forgejo MCP Server é um plugin de integração que conecta o Forgejo a sistemas Model Context Protocol (MCP). Uma vez configurado, você pode interagir com seus repositórios Forgejo por meio de qualquer assistente de IA compatível com MCP, como Claude, Cursor ou extensões do VS Code.

Exemplos de comandos que você pode usar:

"Liste todos os meus repositórios"
"Crie uma issue intitulada 'Bug na página de login'"
"Mostre pull requests abertos em my-org/my-repo"
"Obtenha o conteúdo de README.md do branch main"
"Mostre as execuções mais recentes do workflow Actions em agentic-forges/forgejo-mcp"

Início Rápido

1. Instalação

Opção A: Usando Go (Recomendado)

git clone https://git.b4mad.industries/agentic-forges/forgejo-mcp.git
cd forgejo-mcp
go install .

Garanta que $GOPATH/bin (normalmente ~/go/bin) esteja no seu PATH.

Nota: você também pode instalar diretamente do caminho do módulo, sem clonar:
go install git.b4mad.industries/agentic-forges/forgejo-mcp/v3@latest

Opção B: Baixar Binário

Baixe o lançamento mais recente na página de lançamentos.

Para Arch Linux, use seu auxiliar AUR favorito:

yay -S forgejo-mcp      # builds from source
yay -S forgejo-mcp-bin  # uses pre-built binary

Opção C: Nix / NixOS

Você pode executar o servidor diretamente usando o gerenciador de pacotes Nix:

nix-shell -p forgejo-mcp

Ou usando Flakes:

nix run nixpkgs#forgejo-mcp

Nota: forgejo-mcp está atualmente disponível apenas no canal unstable e ainda não faz parte do lançamento estável 25.11.

Opção D: Imagem de contêiner

Uma imagem OCI multi-estágio assinada é publicada em cada lançamento em git.b4mad.industries/agentic-forges/forgejo-mcp. Execute o servidor sem compilar a partir do código-fonte:

# Latest release
podman run --rm -i \
  -e FORGEJO_ACCESS_TOKEN="<your personal access token>" \
  git.b4mad.industries/agentic-forges/forgejo-mcp:latest \
  --transport stdio --url https://your-forgejo-instance.org

# Or pin a specific version
podman run --rm -i git.b4mad.industries/agentic-forges/forgejo-mcp:v3.1.0 --help

Tag	Significado
`vMAJOR.MINOR.PATCH`	Imutável — o lançamento exato (ex.: `v3.1.0`). Use em produção.
`latest`	Móvel — acompanha o lançamento mais recente. Apenas conveniência.

A imagem é de arquitetura única (linux/amd64), assinada com cosign e carrega um SBOM CycloneDX anexado. Veja Verificar a imagem do contêiner para verificar a assinatura e a proveniência antes de executar.

2. Obtenha Seu Token de Acesso

Entre na sua instância Forgejo
Vá para Configurações → Aplicações → Tokens de Acesso
Crie um novo token com as permissões que você precisa (repo, issue, etc.)

3. Configure Seu Assistente de IA

Adicione isto ao seu arquivo de configuração MCP:

Para modo stdio (mais comum):

{
  "mcpServers": {
    "forgejo": {
      "command": "forgejo-mcp",
      "args": [
        "--transport", "stdio",
        "--url", "https://your-forgejo-instance.org"
      ],
      "env": {
        "FORGEJO_ACCESS_TOKEN": "<your personal access token>",
        "FORGEJO_USER_AGENT": "forgejo-mcp/1.0.0"
      }
    }
  }
}

Para modo HTTP streamable (recomendado para remoto/Claude.ai):

{
  "mcpServers": {
    "forgejo": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Ao usar o modo HTTP streamable, inicie o servidor primeiro:

forgejo-mcp --transport http --url https://your-forgejo-instance.org --token <your-token>

Modo HTTP multi-tenant (opcional):

Você pode executar uma única instância centralizada de forgejo-mcp e deixar cada cliente fornecer seu próprio token por meio do cabeçalho HTTP padrão Authorization. Isso permite atender vários usuários ou agentes a partir de um único servidor.

Inicie o servidor (opcionalmente sem qualquer token global):

forgejo-mcp --transport http --url https://your-forgejo-instance.org

Os clientes incluem seu token específico em cada requisição:
- Authorization: token <token> (estilo Forgejo)
- Authorization: Bearer <token> (estilo OAuth2/MCP)
- Nota: O esquema (token ou Bearer) não diferencia maiúsculas de minúsculas.

Veja demos/multi-tenant-http.md para um passo a passo copiável.

Expondo o servidor a uma rede

Por padrão, os transportes sse e http escutam apenas em loopback, então nada fora desta máquina pode alcançá-los. Isso segue a orientação do Model Context Protocol para servidores executados localmente, e é uma mudança de comportamento: versões anteriores escutavam em todas as interfaces de rede. O padrão, localhost, vincula ambas as famílias de loopback, então um cliente que resolve localhost para 127.0.0.1 ou ::1 conecta. Se a porta já estiver ocupada em qualquer uma das famílias, o servidor se recusa a iniciar, em vez de atender na outra família enquanto alguns clientes alcançam o que quer que esteja na porta. Uma família que a máquina não pode usar — IPv6 desabilitado, por exemplo — é ignorada, e o log de inicialização informa isso.

Passe um endereço em vez de um nome — --host 127.0.0.1 ou --host ::1 — para vincular apenas essa família. Use-o quando a outra família for inutilizável nesta máquina de uma forma que o servidor não consiga reconhecer como "ausente", para que ele não se recuse a iniciar.

Se você executa o servidor em um contêiner, ou atende clientes remotos, agora você deve declarar isso explicitamente. O padrão não aceitará conexões de fora da máquina — ou, em um contêiner, de fora do contêiner:

defina --host para um endereço que a rede possa alcançar (0.0.0.0 para todas as interfaces, que é a escolha usual dentro de um contêiner);
e defina --allowed-hosts para os nomes de host que seus clientes usam. Isso é obrigatório, não opcional: o servidor se recusa a iniciar em um endereço alcançável pela rede sem isso, em vez de iniciar e rejeitar todas as requisições.

Requisições são recusadas com 403 Forbidden quando seu cabeçalho Host não é um que você declarou. Nomes de loopback são sempre aceitos em um listener de loopback, então declarar o hostname de um proxy não impede você de conectar diretamente da mesma máquina.

Clientes de navegador. Uma requisição que carrega um cabeçalho Origin é recusada a menos que essa origem esteja listada em --allowed-origins, que é vazio por padrão. Origens são comparadas integralmente — esquema, host e porta — porque a porta de um Origin pertence à página que faz a requisição, não a este servidor. Requisições sem cabeçalho Origin algum não são afetadas, que é o caso normal: um cliente MCP não é um navegador.

Autenticação em `sse` e `http`

Nesses transportes, cada requisição deve carregar seu próprio cabeçalho Authorization. Uma requisição sem um é recusada com 401 Unauthorized, em vez de ser atendida usando o token configurado do próprio servidor. Isso é o que a configuração multi-tenant acima espera de qualquer forma, e é por isso que essa configuração é segura para expor.

Em stdio, o token configurado ainda substitui um cabeçalho ausente exatamente como antes. Nada sobre stdio muda.

Se você executa uma implantação de usuário único sobre sse ou http e quer o comportamento antigo, --allow-operator-token-fallback o restaura. Entenda o que isso significa antes de usá-lo: qualquer cliente que possa alcançar a porta age como a identidade por trás do seu token, sem apresentar uma credencial. O log de inicialização informa isso, em voz alta, sempre que está ativo.

Para modo SSE (HTTP legado):

{
  "mcpServers": {
    "forgejo": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Ao usar o modo SSE, inicie o servidor primeiro:

forgejo-mcp --transport sse --url https://your-forgejo-instance.org --token <your-token>

Operação remota como servidor de recursos OAuth

Com --auth-mode resource-server, o transporte http se torna um servidor de recursos OAuth 2.0 conforme define a especificação de autorização MCP. Os clientes não enviam mais um token Forgejo. Eles fazem login em um provedor OpenID Connect que você escolhe e enviam seu token de acesso JWT. O servidor valida esse token, assina um JWT que dura cinco minutos para o chamador, e o apresenta ao Forgejo por meio de uma Integração Autorizada Forgejo 16. Nenhum token do forge é configurado em qualquer lugar, e o token de acesso do chamador nunca chega ao Forgejo.

O modo precisa de:

Forgejo 16.0 ou mais recente;
um provedor OpenID Connect que emita tokens de acesso JWT e possa adicionar uma claim por usuário (padrão forgejo_aud) contendo o público da Integração Autorizada desse usuário;
uma origem HTTPS pública para o servidor, porque o Forgejo busca os documentos de emissor do servidor a partir dela;
um arquivo de chave de assinatura: EC P-256 ou P-384, Ed25519, ou RSA de pelo menos 2048 bits.

forgejo-mcp --transport http --url https://forgejo.example.org \
  --host 0.0.0.0 --allowed-hosts mcp.example.org \
  --auth-mode resource-server \
  --authorization-server https://id.example.org \
  --resource https://mcp.example.org/mcp \
  --forgejo-jwt-issuer https://mcp.example.org/issuer \
  --forgejo-jwt-signing-key-file /run/credentials/forgejo-mcp.service/signing-key

O modo é opt-in: sem --auth-mode, tudo acima se comporta como antes. Nesse modo, o servidor responde apenas a /mcp, os metadados do recurso protegido, e ao documento de descoberta e conjunto de chaves sob o caminho do emissor. Ele se recusa a iniciar em uma configuração que não possa atender com segurança, e a recusa nomeia a configuração a corrigir. A chave de assinatura age para cada usuário cuja integração confia no emissor, então proteja-a como o token do forge que ela substitui.

Guia do operador: requisitos do provedor de identidade, ordem de implantação, regras de proxy, rotação de chaves e um exemplo prático com Zitadel.
Guia do usuário: criação da Integração Autorizada, a regra de claim sub obrigatória e configuração de um cliente MCP.

4. Comece a Usar

Abra seu assistente de IA compatível com MCP e tente:

List all my repositories

Ferramentas Disponíveis

Ferramenta	Descrição
Usuário
`get_my_user_info`	Obter informações sobre o usuário autenticado
`check_notifications`	Verificar e listar notificações do usuário
`get_notification_thread`	Obter informações detalhadas sobre um único tópico de notificação
`mark_notification_read`	Marcar um único tópico de notificação como lido
`mark_all_notifications_read`	Reconhecer todas as notificações
`list_repo_notifications`	Filtrar notificações limitadas a um único repositório
`mark_repo_notifications_read`	Marcar todas as notificações em um repositório específico como lidas
`search_users`	Pesquisar usuários
Repositórios
`list_my_repos`	Listar todos os repositórios que você possui
`get_repo`	Obter um único repositório por proprietário e nome
`create_repo`	Criar um novo repositório
`fork_repo`	Bifurcar um repositório
`edit_repo`	Editar configurações do repositório. Apenas os campos que você enviar são alterados; campos omitidos permanecem inalterados. Não fornecer nenhum campo é um erro.
`search_repos`	Pesquisar repositórios
Tópicos
`list_repo_topics`	Listar os tópicos de um repositório. Limitado por `page` (padrão 1) + `limit` (padrão 100); retorna `{topics, page, limit, count}`.
`set_repo_topics`	Substituir todos os tópicos. `topics` é uma string obrigatória separada por vírgulas; uma string vazia limpa. Nomes inválidos são rejeitados antes da solicitação.
`add_repo_topic`	Adicionar um tópico
`delete_repo_topic`	Excluir um tópico
Ramos
`list_branches`	Listar todos os ramos em um repositório
`create_branch`	Criar um novo ramo
`delete_branch`	Excluir um ramo
Proteção de Ramos
`list_branch_protections`	Listar as regras de proteção de ramos de um repositório. Limitado por `page` (baseado em 1) + `limit` (tamanho da página); a resposta ecoa `page`/`limit` para que os chamadores possam buscar a próxima página.
`get_branch_protection`	Obter uma única regra pelo nome `rule`
`create_branch_protection`	Criar uma regra. Requer `branch_name`; `status_check_contexts` é uma lista separada por vírgulas de verificações obrigatórias (por exemplo, `"ci/build,ci/test"`).
`edit_branch_protection`	Editar uma regra pelo nome `rule`. Apenas os campos que você enviar são alterados; campos omitidos permanecem inalterados.
`delete_branch_protection`	Excluir uma regra pelo nome `rule`
Webhooks
`list_repo_hooks`	Listar webhooks do repositório. Limitado por `page` (padrão 1) + `limit` (padrão 30, sem teto imposto pelo servidor); retorna `total_count` quando o Forgejo relata `X-Total-Count`.
`get_repo_hook`	Obter um único webhook do repositório por ID
`create_repo_hook`	Criar um webhook do repositório. O segredo é aceito, mas nunca ecoado na resposta.
`edit_repo_hook`	Editar um webhook do repositório. Apenas os campos que você enviar são alterados; campos omitidos permanecem inalterados.
`delete_repo_hook`	Excluir um webhook do repositório por ID
`test_repo_hook`	Acionar uma entrega de teste para um webhook do repositório — AVISO: aciona uma entrega HTTP ao vivo
Arquivos
`get_file_content`	Obter o conteúdo de um arquivo. Opcionalmente, `start_line`/`end_line` solicitam um intervalo de linhas inclusivo baseado em 1 (limita-se à extensão do arquivo; ignorado quando `with_metadata=true`).
`list_repo_contents`	Listar arquivos e diretórios em um caminho. `path=""` lista a raiz do repositório. Retorna um nível; para uma árvore completa, use `get_repo_tree` com `recursive=true`.
`get_repo_tree`	Obter a árvore Git. `recursive=true` retorna a árvore de arquivos completa em uma resposta (sujeita ao limite de tamanho do endpoint de árvore do servidor); `recursive=false` (padrão) retorna um nível.
`create_file`	Criar um novo arquivo
`update_file`	Atualizar um arquivo existente
`delete_file`	Excluir um arquivo
Commits
`list_repo_commits`	Listar commits em um repositório
`get_commit_statuses`	Listar status de commit por contexto para um SHA completo de 40 caracteres. Limitado por `page` (padrão 1) + `limit` (padrão 30, máximo 50); retorna `{sha, statuses, page, limit, count, total_count}` — `total_count` está presente apenas quando o Forgejo relata `X-Total-Count`. O agregado combinado permanece no recurso de status de commit. Não são execuções de Actions (`list_workflow_runs`).
Problemas
`list_repo_issues`	Listar problemas em um repositório (página/limite). Opcionalmente, `sort` ordena no lado do servidor: `relevance`, `latest`, `oldest`, `recentupdate`, `leastupdate`, `mostcomment`, `leastcomment`, `nearduedate`, `farduedate` (os dois últimos são as direções de data de vencimento).
`search_issues`	Pesquisar problemas em todos os repositórios de um proprietário (página/limite); retorna `{issues,page,limit,count,has_next,total_count}` — `total_count` está presente apenas quando o Forgejo relata `X-Total-Count`
`get_issue_by_index`	Obter um problema específico
`create_issue`	Criar um novo problema. Opcionalmente, `labels` (nomes ou IDs separados por vírgulas), `assignees` (nomes de usuário separados por vírgulas) e `milestone` (ID numérico) são aplicados pela mesma solicitação que cria o problema.
`add_issue_labels`	Adicionar rótulos a um problema. `labels` aceita nomes de rótulos ou IDs numéricos separados por vírgulas; um nome não reconhecido é um erro e nada é aplicado.
`remove_issue_labels`	Remover rótulos de um problema. `labels` aceita nomes de rótulos ou IDs numéricos separados por vírgulas.
`update_issue`	Atualizar um problema existente (requer ID de marco numérico). `due_date` define o prazo (RFC3339); `clear_due_date=true` o remove. Os dois são mutuamente exclusivos — definir ambos é um erro, e omitir ambos deixa o prazo inalterado. `set_labels` substitui todo o conjunto de rótulos do problema (nomes ou IDs); uma string vazia limpa todos os rótulos.
`issue_state_change`	Abrir ou fechar um problema
`list_issue_dependencies`	Listar problemas dos quais o problema fornecido depende. Limitado por `page` (baseado em 1) + `limit` (tamanho da página); a resposta ecoa `page`/`limit` para que os chamadores possam buscar a próxima página.
`list_issue_dependents`	Listar problemas que dependem do problema fornecido. Limitado por `page` (baseado em 1) + `limit` (tamanho da página); a resposta ecoa `page`/`limit` para que os chamadores possam buscar a próxima página.
`add_issue_dependency`	Fazer um problema depender de outro. A dependência pode estar em um repositório diferente: opcionalmente, `depends_on_owner`/`depends_on_repo` usam como padrão `owner`/`repo`.
`remove_issue_dependency`	Remover uma dependência de um problema. Para uma dependência entre repositórios, opcionalmente, `dependency_owner`/`dependency_repo` usam como padrão `owner`/`repo`.
`list_repo_milestones`	Listar marcos com seus IDs (use com `update_issue`)
`list_repo_labels`	Listar rótulos com seus IDs. Mescla rótulos de nível de organização para repositórios de propriedade de organização (defina `include_org_labels=false` para optar por não participar). Cada entrada carrega um campo `scope` (`"repo"` ou `"org"`).
`list_org_labels`	Listar rótulos de nível de organização com seus IDs. As ferramentas de atribuição aceitam nomes de rótulos diretamente, então isso é para descoberta e para o nome raro que existe tanto no escopo do repositório quanto no da organização.
`create_repo_label`	Criar um rótulo de repositório (`name`, `color` como hex de 6 dígitos, opcional `description`). Retorna o `id` numérico; `add_issue_labels` também aceita o nome.
`edit_repo_label`	Editar um rótulo de repositório (PATCH — apenas os campos fornecidos mudam: `name`, `color`, `description`).
`delete_repo_label`	Excluir um rótulo de repositório. Recusa por padrão quando o rótulo está em uso (relata a contagem); defina `delete_mode=force` para substituir.
`get_repo_label`	Obter um único rótulo de repositório pelo `id` numérico.
`create_org_label`	Criar um rótulo de nível de organização. Mesmos campos que `create_repo_label`.
`edit_org_label`	Editar um rótulo de nível de organização (semântica PATCH).
`delete_org_label`	Excluir um rótulo de nível de organização. A proteção de uso conta nos repositórios de organização visíveis (melhor esforço); `delete_mode=force` substitui.
`get_org_label`	Obter um único rótulo de nível de organização pelo `id` numérico.
Comentários
`list_issue_comments`	Listar comentários em um problema ou PR
`get_issue_comment`	Obter um comentário específico
`create_issue_comment`	Adicionar um comentário a um problema ou PR
`edit_issue_comment`	Editar um comentário
`delete_issue_comment`	Excluir um comentário
Pull Requests
`list_repo_pull_requests`	Listar pull requests em um repositório
`get_pull_request_by_index`	Obter um pull request específico
`create_pull_request`	Criar um novo pull request
`update_pull_request`	Atualizar um pull request existente
`list_pull_reviews`	Listar revisões para um pull request
`get_pull_review`	Obter uma revisão específica de pull request
`list_pull_review_comments`	Listar comentários em uma revisão de pull request
`list_pull_request_files`	Listar arquivos alterados em um pull request (paginado). Use os nomes de arquivo retornados como o argumento `file_path` para `get_pull_request_diff`.
`get_pull_request_diff`	Obter o diff unificado de um pull request. Opcionalmente, `file_path` retorna apenas os hunks desse arquivo (corresponde ao caminho pré ou pós-renomeação).
`merge_pull_request`	Mesclar um pull request (estilo: merge/rebase/rebase-merge/squash; título/mensagem/excluir-ramo/forçar-mesclagem/aguardar-verificações opcionais).
`create_pull_review`	Criar uma revisão em um pull request (estado: APPROVED/REQUEST_CHANGES/COMMENT) com comentários inline opcionais.
`submit_pull_review`	Enviar uma revisão de pull request pendente
`dismiss_pull_review`	Dispensar uma revisão de pull request
`delete_pull_review`	Excluir uma revisão de pull request pendente
`create_review_requests`	Solicitar revisões de usuários ou equipes específicos
`delete_review_requests`	Cancelar solicitações de revisão pendentes
Pacotes
`list_packages`	Listar versões de pacotes de um usuário ou organização (uma linha por versão). Opcionalmente, `type` e `q`. Paginado pelo servidor via `page`/`limit` (padrão 30, máximo 50). Envelope `{packages, page, limit, count, has_next, total_count?}`. Um proprietário ausente é um erro, não uma lista vazia
`get_package`	Obter uma versão de pacote. Não incorpora usuários proprietário/criador
`delete_package`	Excluir uma versão de pacote (não todas as versões do nome). Sem pré-verificação. 4xx/5xx permanecem erros
`list_package_files`	Listar arquivos de uma versão de pacote. Paginado pelo cliente via `page`/`limit` (padrão 30, máximo 50); envelope `{files, page, limit, count, has_next, total_count}` (`total_count` é o comprimento da lista buscada)
Actions
`dispatch_workflow`	Acionar uma execução de workflow via evento `workflow_dispatch`
`list_workflow_runs`	Listar execuções de workflow com filtragem opcional por status, evento ou SHA
`get_workflow_run`	Obter detalhes de uma execução de workflow específica por ID
`list_action_run_jobs`	Listar jobs para uma execução de workflow do Forgejo v16+ com limites de `page` e `limit` no lado do cliente
`get_action_job_logs`	Ler um log de job do Forgejo v16+ com limites retomáveis de `offset` e `max_bytes`; usa como padrão o final
`cancel_workflow_run`	Cancelar uma execução de workflow pendente ou em execução. Execuções já concluídas também retornam sucesso (HTTP 204); a execução permanece inalterada
`delete_workflow_run`	Excluir uma execução de workflow concluída. Uma execução ao vivo é um erro de API. Remove a execução e seus logs de job; o Forgejo marca os artefatos dessa execução como excluídos
`list_action_run_artifacts`	Listar artefatos de uma execução de workflow. Paginado pelo servidor via `page`/`limit` (padrão 30, máximo 50); filtro opcional `name`. Envelope `{artifacts, page, limit, count, total_count?}`
`get_action_artifact`	Obter metadados para um artefato de Actions. Não baixa o zip
Organizações
`list_my_orgs`	Listar minhas organizações
`list_user_orgs`	Listar as organizações de um usuário
`get_org`	Obter detalhes da organização
`create_org`	Criar uma organização
`edit_org`	Editar configurações da organização
`delete_org`	Excluir uma organização — destrutivo e irreversível: todos os repositórios, equipes e dados são removidos permanentemente
`list_org_members`	Listar membros de uma organização
`check_org_membership`	Verificar se um usuário é membro de uma organização
`remove_org_member`	Remover um membro de uma organização
`list_org_teams`	Listar times em uma organização
`search_org_teams`	Buscar times em uma organização
`create_org_team`	Criar um time em uma organização
`add_team_member`	Adicionar um usuário a um time
`remove_team_member`	Remover um usuário de um time
`add_team_repo`	Adicionar um repositório a um time
`remove_team_repo`	Remover um repositório de um time
Controle de Tempo
`list_issue_tracked_times`	Listar entradas de tempo rastreadas em uma issue ou PR
`list_repo_tracked_times`	Listar entradas de tempo rastreadas em um repositório
`list_my_tracked_times`	Listar suas próprias entradas de tempo rastreadas
`add_issue_time`	Registrar tempo em uma issue ou PR (aceita segundos ou duração como `15m`)
`reset_issue_time`	Excluir TODAS as entradas de tempo rastreadas em uma issue ou PR (destrutivo)
`delete_issue_time_entry`	Excluir uma única entrada de tempo rastreada por ID
`start_issue_stopwatch`	Iniciar um cronômetro em uma issue ou PR
`stop_issue_stopwatch`	Parar um cronômetro em execução e registrar o tempo decorrido
`cancel_issue_stopwatch`	Cancelar um cronômetro em execução sem registrar
`list_my_stopwatches`	Listar cronômetros atualmente em execução
Anexos
`list_issue_attachments`	Listar anexos em uma issue ou PR
`get_issue_attachment`	Obter metadados de um único anexo de issue/PR
`download_issue_attachment`	Baixar um anexo de issue/PR (inline se < 1 MiB; metadados + URL caso contrário)
`create_issue_attachment`	Enviar um novo anexo para uma issue ou PR (conteúdo base64 ou um caminho de arquivo no host MCP)
`edit_issue_attachment`	Renomear um anexo de issue/PR
`delete_issue_attachment`	Excluir um anexo de issue/PR
`list_comment_attachments`	Listar anexos em um comentário de issue/PR
`get_comment_attachment`	Obter metadados de um único anexo de comentário
`download_comment_attachment`	Baixar um anexo de comentário (inline se < 1 MiB; metadados + URL caso contrário)
`create_comment_attachment`	Enviar um novo anexo para um comentário de issue/PR (conteúdo base64 ou um caminho de arquivo no host MCP)
`edit_comment_attachment`	Renomear um anexo de comentário
`delete_comment_attachment`	Excluir um anexo de comentário
Releases
`list_releases`	Listar releases de um repositório (página/limite + filtro `state` no lado do cliente: all/draft/prerelease/published)
`get_release_by_id`	Obter uma release por ID numérico
`get_release_by_tag`	Obter uma release pelo nome da tag
`get_latest_release`	Obter a release mais recente que não seja draft nem prerelease
`create_release`	Criar uma nova release (passe `target_commitish` para também criar a tag)
`edit_release`	Atualizar campos de uma release existente (apenas os campos fornecidos são enviados)
`delete_release`	Excluir uma release por ID numérico — destrutivo
`delete_release_by_tag`	Excluir uma release pelo nome da tag — destrutivo, verifique a tag
`list_release_attachments`	Listar anexos em uma release (resposta obtida por completo, fatiada no lado do cliente)
`get_release_attachment`	Obter metadados de um único anexo de release
`download_release_attachment`	Baixar um anexo de release (inline se < 1 MiB; metadados + URL caso contrário)
`create_release_attachment`	Enviar um novo anexo para uma release (conteúdo base64 ou um caminho de arquivo no host MCP)
`edit_release_attachment`	Renomear um anexo de release
`delete_release_attachment`	Excluir um anexo de release — destrutivo
Wiki
`list_wiki_pages`	Listar páginas usando `page`/`limit`; retorna `has_next` e, quando o Forgejo reporta `X-Total-Count`, `total_count`. `total_count` conta as entradas brutas da árvore do wiki upstream, então pode exceder o número de páginas listadas em um wiki com subdiretórios — um limite superior, não um total exato.
`get_wiki_page`	Ler Markdown decodificado; `start_line`/`end_line` opcionais, sempre retorna `total_lines`.
`get_wiki_revisions`	Listar histórico de revisões usando `page`/`limit`; retorna `has_next` e `total_count`, a contagem total de revisões da página conforme reportado no corpo da resposta.
`create_wiki_page`	Criar uma página e retornar seu `page_name` normalizado pelo servidor; títulos separados por barras são uma convenção plana de nomenclatura de subpáginas (sem hierarquia e sem página pai automática), e um título existente é sobrescrito.
`update_wiki_page`	Atualizar conteúdo/título pelo `page_name` normalizado; o último escritor vence.
`delete_wiki_page`	Excluir uma página pelo `page_name` normalizado.
Servidor
`get_forgejo_mcp_server_version`	Obter a versão do servidor MCP

Recursos

Os modelos de recursos MCP expõem entidades do Forgejo como recursos endereçáveis por URI usando o esquema forgejo://. O esquema de URI é portável entre instâncias — a mesma forma de URI funciona em qualquer instância do Forgejo — e não colide com links web do Forgejo. Clientes que suportam resources/templates/list e resources/read (Claude Code, Claude Desktop, Codex, Cursor) podem resolver esses URIs diretamente. Clientes sem suporte a modelos de recursos continuam usando as ferramentas acima — nenhuma funcionalidade é removida.

Os recursos NÃO substituem nenhuma ferramenta MCP — toda ferramenta existente de listar/obter permanece disponível; os recursos são uma superfície de leitura aditiva e endereçável por URI, destinada à resolução automática a partir do contexto LLM e ao cache endereçável por conteúdo de entidades imutáveis, como commits.

Recursos que incorporam uma lista (issue, pr) limitam o array incorporado a 30 itens. Quando truncado, o payload JSON inclui um sentinela nomeando a ferramenta list_* correspondente que o chamador deve invocar para obter a lista completa.

Quando usar recursos vs ferramentas: prefira um recurso quando você tiver um sha ou índice específico em mãos; prefira uma ferramenta ao listar ou pesquisar.

Modelo de URI	Entidade	Notas
`forgejo://owner/{owner}`	application/json	Perfil de usuário ou organização endereçado pelo login; resolve usuário primeiro, com fallback para organização.
`forgejo://repo/{owner}/{repo}`	application/json	Visão geral do repositório: identidade + contagens, sem listas incorporadas.
`forgejo://repo/{owner}/{repo}/commit/{sha}`	Metadados de commit	Imutável por sha. Retorna JSON + sidecar markdown. sha deve ter 40 caracteres hexadecimais.
`forgejo://repo/{owner}/{repo}/commit/{sha}/status`	application/json	Status de CI combinado para um sha: estado agregado + status por contexto limitados (máx. 30, sentinela nomeia a ferramenta de lista `get_commit_statuses`).
`forgejo://repo/{owner}/{repo}/issue/{index}`	application/json (+ sidecar text/markdown)	Metadados de issue + corpo renderizado + comentários recentes limitados (máx. 30, sentinela nomeia `list_issue_comments`).
`forgejo://repo/{owner}/{repo}/issues{?state,labels,page,limit}`	application/json	Lista limitada de issues como linhas — índice, título, estado, autor, labels, assignees, milestone, contagem de comentários, timestamps, data de vencimento — e sem corpos. `state` ∈ {open, closed, all} (padrão `open`); `labels` separados por vírgula; máx. 30, sentinela nomeia `list_repo_issues`. Leia o recurso de issue individual para obter o corpo.
`forgejo://repo/{owner}/{repo}/{kind}/{index}/comment/{id}`	application/json (+ sidecar text/markdown)	Comentário individual por id; kind ∈ {issue, pr}.
`forgejo://repo/{owner}/{repo}/{kind}/{index}/comments{?page,limit}`	application/json	Thread de comentários limitada com corpos completos (o recurso de issue individual os resume em 200 caracteres); kind ∈ {issue, pr}; máx. 30, sentinela nomeia `list_issue_comments`.
`forgejo://repo/{owner}/{repo}/pr/{index}`	application/json (+ sidecar text/markdown)	Metadados de PR, refs head/base, mergeabilidade, comentários recentes limitados (máx. 30, sentinela `list_issue_comments`) e reviews (máx. 30, sentinela `list_pull_reviews`).
`forgejo://repo/{owner}/{repo}/branch_protections`	application/json	Lista limitada de regras de proteção de branch.
`forgejo://repo/{owner}/{repo}/branch_protection/{rule}`	application/json	Regra individual de proteção de branch. Nomes de regras são padrões de branch, então codifique um `/` literal como `%2F` e espaços como `%20` (`release%2Fv1`); um `/` bruto não resolve.
`forgejo://repo/{owner}/{repo}/hooks`	application/json	Lista limitada de webhooks do repositório (máx. 30, sentinela nomeia `list_repo_hooks`). O segredo nunca é retornado.
`forgejo://repo/{owner}/{repo}/hook/{id}`	application/json	Webhook individual do repositório por id. O segredo nunca é retornado.
`forgejo://repo/{owner}/{repo}/label/{id}`	application/json	Label individual do repositório por id numérico.
`forgejo://repo/{owner}/{repo}/labels{?page,limit}`	application/json	Lista limitada de labels do repositório (máx. 30, sentinela nomeia `list_repo_labels`).
`forgejo://org/{org}/labels{?page,limit}`	application/json	Lista limitada de labels em nível de organização (máx. 30, sentinela nomeia `list_org_labels`).
`forgejo://repo/{owner}/{repo}/wiki/{pageName}`	application/json (+ sidecar text/markdown)	Página wiki com revisões limitadas e Markdown limitado a 1 MiB. Use o `page_name` normalizado retornado; codifique um `/` literal como `%2F` e espaços como `%20` no URI (não codifique duas vezes um nome já normalizado).

Títulos separados por barras, como Guides/Setup, são úteis como convenção de nomenclatura de subpáginas, mas o Forgejo armazena as páginas em uma lista plana: ele não cria Guides automaticamente nem registra uma relação pai-filho. Crie a página pai separadamente quando os leitores precisarem dela, e sempre enderece chamadas subsequentes com o page_name normalizado retornado por create ou list. O comportamento REST de wiki documentado aqui foi testado ao vivo contra o Forgejo 15.0.4+gitea-1.22.0; a demonstração MCP completa foi reproduzida com sucesso contra 16.0.0+gitea-1.22.0. Esta é a faixa testada, não uma garantia para cada implantação intermediária ou com proxy diferente.

Compatibilidade com Clientes

Cliente	`resources/templates/list`	`resources/read`
Claude Code	suportado	suportado
Claude Desktop	suportado	suportado
Codex	suportado	suportado
Cursor (atual)	suportado	suportado
Clientes antigos / mínimos	apenas ferramentas	apenas ferramentas

Demonstrações

Walkthroughs completos e copiáveis das ferramentas acima — agrupados por tópico (labels, anexos, controle de tempo, notificações, organizações, I/O limitado em revisão de código, transporte) — estão em demos/. Cada demonstração combina invocações reais de ./forgejo-mcp --cli com a saída que produziram contra codeberg.org.

Modo CLI

Você pode invocar qualquer ferramenta diretamente da linha de comando sem executar um servidor MCP. Isso é útil para scripts de shell, pipelines de CI/CD e skills do Claude Code.

# List all available tools (grouped by domain)
forgejo-mcp --cli list

# Invoke a tool with JSON arguments
forgejo-mcp --cli get_issue_by_index --args '{"owner":"goern","repo":"forgejo-mcp","index":1}'

# Pipe JSON arguments via stdin
echo '{"owner":"goern","repo":"forgejo-mcp"}' | forgejo-mcp --cli list_repo_issues

# List recent workflow runs (text output)
forgejo-mcp --cli list_workflow_runs \
  --args '{"owner":"goern","repo":"forgejo-mcp"}' \
  --output=text

# List only failed runs
forgejo-mcp --cli list_workflow_runs \
  --args '{"owner":"goern","repo":"forgejo-mcp","status":"failure"}' \
  --output=text

# List jobs and inspect the tail of a failed job (Forgejo v16+)
forgejo-mcp --cli list_action_run_jobs \
  --args '{"owner":"goern","repo":"forgejo-mcp","run_id":123}' \
  --output=text
forgejo-mcp --cli get_action_job_logs \
  --args '{"owner":"goern","repo":"forgejo-mcp","job_id":456,"max_bytes":32768}' \
  --output=text

# Forgejo's run-wide ZIP log endpoint has no Range support. Enumerate jobs and
# fetch their bounded plaintext logs instead.

# List artifacts of a run, then read one artifact's metadata (no zip download)
forgejo-mcp --cli list_action_run_artifacts \
  --args '{"owner":"goern","repo":"forgejo-mcp","run_id":123,"limit":30}' \
  --output=text
forgejo-mcp --cli get_action_artifact \
  --args '{"owner":"goern","repo":"forgejo-mcp","artifact_id":789}' \
  --output=text

# List package versions for an owner, then inspect one version's files
forgejo-mcp --cli list_packages \
  --args '{"owner":"OWNER","type":"container","limit":30}' \
  --output=text
forgejo-mcp --cli get_package \
  --args '{"owner":"OWNER","type":"container","name":"app","version":"1.0.0"}' \
  --output=text
forgejo-mcp --cli list_package_files \
  --args '{"owner":"OWNER","type":"container","name":"app","version":"1.0.0"}' \
  --output=text

# delete_package removes one version. Do not invoke it against a registry you do not own.

# cancel_workflow_run is 204 even when the run already finished.
# delete_workflow_run only succeeds for a completed run; a live run is an error.

# Show a tool's parameters
forgejo-mcp --cli create_issue --help

# Control output format (json or text)
forgejo-mcp --cli list --output=json
forgejo-mcp --cli get_my_user_info --args '{}' --output=text

O modo CLI requer a mesma configuração de FORGEJO_URL e FORGEJO_ACCESS_TOKEN que o modo servidor MCP. Os resultados das ferramentas são gravados como JSON no stdout por padrão; erros vão para o stderr com um código de saída diferente de zero.

Opções de Configuração

Você pode configurar o servidor usando argumentos de linha de comando ou variáveis de ambiente:

Argumento CLI	Variável de Ambiente	Descrição
`--url`	`FORGEJO_URL`	URL da sua instância do Forgejo
`--token`	`FORGEJO_ACCESS_TOKEN`	Seu token de acesso pessoal
`--debug`	`FORGEJO_DEBUG`	Ativa o modo de depuração
`--transport`	-	Modo de transporte: `stdio`, `sse` ou `http`
`--sse-port`	-	Porta para o modo SSE (padrão: 8080)
`--http-port`	-	Porta para o modo HTTP streamable (padrão: 8080)
`--host`	`FORGEJO_MCP_HOST`	Endereço ao qual os transportes `sse` e `http` se vinculam (padrão: `localhost`, acessível apenas desta máquina, vinculando tanto `127.0.0.1` quanto `::1`; passe um desses endereços para vincular apenas aquela família)
`--allowed-hosts`	`FORGEJO_MCP_ALLOWED_HOSTS`	Nomes de `Host` separados por vírgula aos quais este servidor responde; obrigatório quando `--host` não é loopback
`--allowed-origins`	`FORGEJO_MCP_ALLOWED_ORIGINS`	Origens web separadas por vírgula autorizadas a enviar um cabeçalho `Origin`, como origens completas (`https://console.example.org`). Vazio por padrão
`--allow-operator-token-fallback`	`FORGEJO_MCP_ALLOW_OPERATOR_TOKEN_FALLBACK`	Em `sse`/`http`, atenda solicitações sem cabeçalho `Authorization` usando o token próprio deste servidor. Desativado por padrão
`--auth-mode`	`FORGEJO_MCP_AUTH_MODE`	`passthrough` (padrão) ou `resource-server`; veja Operação remota como servidor de recursos OAuth
`--authorization-server`	`FORGEJO_MCP_AUTHORIZATION_SERVER`	Modo `resource-server`: URL do emissor do provedor OpenID Connect, comparado byte a byte
`--resource`	`FORGEJO_MCP_RESOURCE`	Modo `resource-server`: URI canônico do endpoint MCP, por exemplo `https://mcp.example.org/mcp`; seu caminho deve ser `/mcp`
`--resource-audience`	`FORGEJO_MCP_RESOURCE_AUDIENCE`	Modo `resource-server`: valor que a claim `aud` de um token de acesso deve conter (padrão: o valor de `--resource`)
`--scopes-supported`	`FORGEJO_MCP_SCOPES_SUPPORTED`	Modo `resource-server`: scopes separados por espaço publicados nos metadados e no desafio `401` (padrão: nenhum publicado)
`--forgejo-audience-claim`	`FORGEJO_MCP_FORGEJO_AUDIENCE_CLAIM`	Modo `resource-server`: claim do token de acesso que contém o público da Integração Autorizada do Forgejo do chamador (padrão: `forgejo_aud`)
`--forgejo-jwt-issuer`	`FORGEJO_MCP_FORGEJO_JWT_ISSUER`	Modo `resource-server`: URL do emissor sob a qual o servidor assina JWTs para o Forgejo, por exemplo `https://mcp.example.org/issuer`; https, sem barra final
`--forgejo-jwt-signing-key-file`	`FORGEJO_MCP_FORGEJO_JWT_SIGNING_KEY_FILE`	Modo `resource-server`: chave privada PEM que assina os JWTs para o Forgejo (EC P-256 ou P-384, Ed25519, ou RSA de pelo menos 2048 bits)
`--forgejo-jwt-published-key-files`	`FORGEJO_MCP_FORGEJO_JWT_PUBLISHED_KEY_FILES`	Modo `resource-server`: chaves PEM separadas por vírgula publicadas ao lado da chave de assinatura, para rotação de chaves
`--cli`	-	Entra no modo CLI para invocação direta de ferramentas
`--user-agent`	`FORGEJO_USER_AGENT`	Cabeçalho HTTP User-Agent (padrão: `forgejo-mcp/<version>`)
-	`FORGEJO_MCP_ALLOW_FILE_PATH_UPLOAD`	Permite uploads de anexos `file_path` para ler o sistema de arquivos do host (`1`/`true`/`yes`/`on`; desativado por padrão)
-	`FORGEJO_MCP_UPLOAD_ROOT`	Restringe uploads de `file_path` a este diretório (padrão: qualquer lugar que o processo possa ler)

Argumentos de linha de comando têm prioridade sobre variáveis de ambiente.

As configurações de resource-server são recusadas no modo passthrough, portanto uma configuração que as define mas esquece --auth-mode resource-server não inicia.

Enviando anexos do sistema de arquivos do host

create_issue_attachment, create_comment_attachment e create_release_attachment aceitam tanto content em base64 quanto um file_path na máquina que executa forgejo-mcp. A forma de caminho evita a expansão em base64 de um artefato de release grande através do transporte MCP.

Está desativado por padrão, porque dá a qualquer coisa que controle o cliente MCP a capacidade de ler qualquer arquivo que o processo do servidor possa ler — um agente com injeção de prompt poderia enviar ~/.ssh/id_ed25519 como um ativo público de release. Ative-o deliberadamente e prefira confiná-lo:

export FORGEJO_MCP_ALLOW_FILE_PATH_UPLOAD=1
export FORGEJO_MCP_UPLOAD_ROOT=/home/you/build/dist   # optional but recommended

Com FORGEJO_MCP_UPLOAD_ROOT definido, um caminho que resolva fora desse diretório — por ser absoluto, por .., ou através de um symlink — é rejeitado antes que qualquer coisa seja lida. Uploads de content em base64 não são afetados por nenhuma das variáveis.

Verificando Releases

Os arquivos de release são acompanhados por um arquivo checksums.txt e um checksums.txt.sig opcional produzido pelo cosign com o par de chaves de release do projeto. Verificar ambos os arquivos permite confirmar que o binário que você baixou foi construído pelo pipeline de release do projeto e não foi adulterado em trânsito.

Atenção: a assinatura com cosign foi introduzida em meados de 2026. Tags lançadas antes da implementação da assinatura são distribuídas sem um arquivo .sig — a verificação se aplica apenas a partir de v2.23.x em diante, e somente quando o segredo COSIGN_PRIVATE_KEY foi configurado no momento do release.

1. Instale o cosign

Siga o guia de instalação do cosign upstream para sua plataforma. Caminhos rápidos:

# Linux/macOS — pinned binary
COSIGN_VERSION=v2.4.1
curl -sSfL -o /usr/local/bin/cosign \
  "https://github.com/sigstore/cosign/releases/download/${COSIGN_VERSION}/cosign-linux-amd64"
chmod +x /usr/local/bin/cosign

# macOS via Homebrew
brew install cosign

# Arch Linux
sudo pacman -S cosign

Confirme:

cosign version

2. Obtenha a chave pública

A fonte normativa para a chave pública do cosign é o repositório GitOps op1st-emea-b4mad — a mesma fonte de verdade que provisiona o Segredo cosign-signing-key-artifacts no namespace op1st-pipelines onde o pipeline de release é executado. Esta é a chave de assinatura de artefatos que assina os blobs de release (checksums.txt.sig); é distinta da chave de assinatura de imagens cosign-signing-key-images.pub usada nas seções §5–§6 abaixo. Duas maneiras de obtê-la:

Ponta do branch (ao vivo, acompanha rotações futuras de chaves):

curl -sSfL -o cosign.pub \
  https://codeberg.org/operate-first/op1st-emea-b4mad/raw/branch/main/manifests/applications/op1st-pipelines-tokens/cosign-signing-key-artifacts.pub

Fixada por commit (à prova de adulteração, recomendada para CI/scripts):

curl -sSfL -o cosign.pub \
  https://codeberg.org/operate-first/op1st-emea-b4mad/raw/commit/cd3715fa8283a2069a2e3e299744a7b55b1b0260/manifests/applications/op1st-pipelines-tokens/cosign-signing-key-artifacts.pub

O permalink fixado por commit incorpora seu conteúdo no hash da URL — se alguém algum dia reescrever o arquivo naquele commit, seu download falhará ou não corresponderá. Fixe no commit mais recente em que você confia antes de adotar a chave em automação.

3. Baixe os artefatos do release

Escolha a tag que você instalou (ex.: v3.1.0) e baixe o arquivo de checksum, sua assinatura e o arquivo binário:

TAG=v3.1.0
VERSION="${TAG#v}"
BASE="https://git.b4mad.industries/agentic-forges/forgejo-mcp/releases/download/${TAG}"

curl -sSfLO "${BASE}/forgejo-mcp_${VERSION}_checksums.txt"
curl -sSfLO "${BASE}/forgejo-mcp_${VERSION}_checksums.txt.sig"
curl -sSfLO "${BASE}/forgejo-mcp_${VERSION}_linux_amd64.tar.gz"   # adjust os/arch

4. Verifique a assinatura e, em seguida, o checksum

O Cosign verifica que checksums.txt foi assinado pelo detentor da chave privada correspondente a cosign.pub. Depois que o arquivo de checksum for confiável, uma verificação simples de sha256sum -c confirma a integridade do arquivo.

# Verify checksums.txt against the signature.
cosign verify-blob \
  --key cosign.pub \
  --signature "forgejo-mcp_${VERSION}_checksums.txt.sig" \
  "forgejo-mcp_${VERSION}_checksums.txt"
# Expected: "Verified OK"

# Verify the downloaded archive against the (now-trusted) checksums.
sha256sum --ignore-missing -c "forgejo-mcp_${VERSION}_checksums.txt"
# Expected: "<archive>: OK"

A cadeia de checksum cobre transitivamente os SBOMs e outros ativos por arquivo — verificar checksums.txt uma vez é suficiente para tudo listado dentro dele.

5. Verifique a proveniência SLSA para a imagem release-tools

A imagem de contêiner release-tools (usada internamente pelo pipeline de release do Tekton) carrega proveniência SLSA v1.0 gerada pelo Tekton Chains. Esta atestação vincula o digest da imagem ao PipelineRun exato, commit git e identidade do builder que a produziu — fornecendo proveniência da cadeia de suprimentos além do que a assinatura cosign sozinha pode atestar.

Busque a chave pública cosign-signing-key-images (uma chave separada da chave de assinatura de artefatos acima):

curl -sSfL -o cosign-images.pub \
  https://codeberg.org/operate-first/op1st-emea-b4mad/raw/branch/main/manifests/applications/op1st-pipelines-tokens/cosign-signing-key-images.pub

Verifique a atestação contra uma tag de imagem específica:

IMAGE_TAG=v1.0.0   # substitute the release-tools tag you want to verify
cosign verify-attestation \
  --type slsaprovenance \
  --key cosign-images.pub \
  "codeberg.org/operate-first/release-tools:${IMAGE_TAG}" \
  | jq .

Uma execução bem-sucedida imprime a declaração in-toto decodificada (JSON). Verifique se predicate.buildDefinition.externalParameters.runSpec.params referencia a revisão git esperada, e predicate.runDetails.builder.id mostra o builder do Tekton Chains.

Nota: Atestações de proveniência SLSA estão disponíveis para releases construídas após o forgejo-mcp-46j (suporte ao Tekton Chains). Tags de imagem anteriores carregam apenas a assinatura cosign; elas não têm payload verify-attestation.

6. Verifique a imagem de contêiner

A imagem de aplicação git.b4mad.industries/agentic-forges/forgejo-mcp (Opção D) é assinada pela mesma chave cosign-signing-key-images que a imagem release-tools, carrega um SBOM CycloneDX anexado e recebe proveniência SLSA v1.0 do Tekton Chains. Reutilize a chave cosign-images.pub buscada acima.

Verifique a assinatura:

IMAGE_TAG=v3.1.0   # substitute the release you are pulling
cosign verify \
  --key cosign-images.pub \
  "git.b4mad.industries/agentic-forges/forgejo-mcp:${IMAGE_TAG}" \
  | jq .

Verifique a atestação de proveniência SLSA:

cosign verify-attestation \
  --type slsaprovenance \
  --key cosign-images.pub \
  "git.b4mad.industries/agentic-forges/forgejo-mcp:${IMAGE_TAG}" \
  | jq .

Verifique e baixe a atestação SBOM CycloneDX assinada:

cosign verify-attestation \
  --type cyclonedx \
  --key cosign-images.pub \
  "git.b4mad.industries/agentic-forges/forgejo-mcp:${IMAGE_TAG}" \
  | jq -r '.payload | @base64d | fromjson | .predicate' > forgejo-mcp.cdx.json

O SBOM agora é uma atestação in-toto assinada (cosign attest), não um artefato attach sbom não assinado. cosign download sbom não se aplica mais.

Como o pipeline de publicação envia por digest e só promove as tags vX.Y.Z / latest após a assinatura e a anexação do SBOM serem bem-sucedidas, qualquer tag que você possa puxar é garantidamente assinada.

Solução de problemas de verificação

Error: no matching signatures — o arquivo .sig é de uma release diferente, ou cosign.pub é a chave errada. Baixe novamente ambos da mesma tag.
Error: cannot read file: checksums.txt.sig — a release é anterior à assinatura cosign, ou a assinatura foi pulada naquela execução porque o segredo não foi definido. Use a verificação somente por checksum (sha256sum -c), que ainda detecta corrupção em trânsito, mas não adulteração.
Incompatibilidade entre cosign.pub e a assinatura — confirme que você buscou a chave pública de um commit que inclui a chave em uso no momento da release. Em caso de dúvida, busque de branch/main.

Solução de problemas

Ative o modo de depuração para ver logs detalhados:

forgejo-mcp --transport sse --url <url> --token <token> --debug

Ou defina a variável de ambiente:

export FORGEJO_DEBUG=true

User-Agent personalizado: Se sua instância do Forgejo ou proxy bloquear o user agent padrão go-http-client, defina um personalizado:

# Via environment variable
export FORGEJO_USER_AGENT="forgejo-mcp/1.0.0"

# Or via CLI flag
forgejo-mcp --user-agent "forgejo-mcp/1.0.0" --transport sse --url <url> --token <token>

Obtendo Ajuda

Relatar problemas — bugs, dúvidas, solicitações de recursos
Encontrou um problema de segurança? Não use o rastreador de issues. Veja SECURITY.md para saber como relatar em privado.
Ver código-fonte
Conversar no Matrix — #forgejo-mcp:b4mad.net

Este repositório também é espelhado no Radicle — uma rede de colaboração de código ponto a ponto. Clone via:

rad clone rad:z4PdPpsH9iJQcWfqTbxpFcWaZ9zPL

Para Desenvolvedores

Veja DEVELOPER.md para instruções de build, visão geral da arquitetura e diretrizes de contribuição.

Problemas Conhecidos

Instalação pelo caminho antigo do módulo Codeberg — go install codeberg.org/goern/forgejo-mcp/v2@latest ainda resolve, contra o espelho somente leitura, mas esse espelho está atrasado em relação à release atual. Use git.b4mad.industries/agentic-forges/forgejo-mcp/v3@latest em vez disso.

Esta entrada costumava dizer que o novo caminho não era instalável até uma release carregar o go.mod renomeado. Essa release aconteceu — v3.0.0 em diante declaram module git.b4mad.industries/agentic-forges/forgejo-mcp/v3 — então o novo caminho instala normalmente. O bloqueador anterior da diretiva replace (#67) também desapareceu; go.mod não contém mais um.

Contribuidores

forgejo-mcp é moldado por todos que abrem issues, escrevem código, revisam PRs e impulsionam o projeto. Obrigado a todos. 🙏

Contribuidores de código

Contribuidor	Destaques
goern (Christoph Görn)	Criador e mantenedor do projeto
Ronmi Ren	Co-criador; transporte SSE/HTTP, bloqueio de issues, melhorias de CI/CD, logo, especificação Glama
twstagg (Tristin Stagg)	Suporte a configuração de user agent (PR #89)
mattdm (Matthew Miller)	Melhorias de logging, migração FORGEJO_*, README, refatoração de URL
byteflavour	`check_notifications` + API completa de gerenciamento de notificações (PR #84, #86); autenticação stateless por requisição para transportes HTTP/SSE (PR #138); documentação de instalação NixOS (PR #146); endurecimento de transporte de rede — bind loopback por padrão, verificações `Host`/`Origin`, credencial por requisição (PR #545, incorporado como #573; #586, #585, #589); modo servidor de recursos OAuth — validação JWT de entrada e assinatura de Integração Autorizada Forgejo 16 de saída, com guias de operador e usuário e 40 cenários de demonstração ancorados (PR #584, pesquisado em #582); `FORGEJO_MCP_EXEC` de ambiente de desenvolvimento (PR #580); solicitações de recursos #80, #85
jesterret	Suporte a revisões e comentários de pull requests (PR #51)
appleboy	Suporte a porta SSE personalizada, correções de bugs
ignasgil	Ferramenta `remove_issue_labels` (PR #96)
dmikushin (Dmitry Mikushin)	Correção de análise de parâmetros numéricos codificados como string de clientes MCP (PR #93)
jiriks74	Atualização de dependência mcp-go v0.44.0 (PR #90)
th (Tomi Haapaniemi)	Ferramenta `update_pull_request`
hiifong	Correções de bugs e atualizações iniciais
Lunny Xiao	Contribuições iniciais
techknowlogick	Contribuições iniciais
yp05327	Contribuições iniciais
mw75	Suporte a proprietário/org para criação de repositórios (PR #18)
Dax Kelson	Gerenciamento de comentários em issues (PR #34)
Guruprasad Kulkarni	Documentação de instalação Arch Linux AUR (PR #69)
Mario Wolff	Contribuições
Massimo Fraschetti	Contribuições
synath (David Paul Turley)	Suporte a token com escopo de repositório via sonda `ServerVersion` (PR #112); verificação de código de status de merge (PR #113); empacotamento Claude Desktop Extension (.mcpb) (PR #118, #123); issue `due_date` + ordenação no servidor (PR #483); recursos limitados de lista de issues e threads de comentários (PR #487); `total_count` em envelopes paginados de `X-Total-Count` (PR #507); endurecimento de timeout `create_*_attachment` (PR #534, #536); dependências de issues entre repositórios (PR #535)
BrilliantKahn	Padrão de texto simples `get_file_content` (PR #116); ferramentas `list_repo_contents` e `get_repo_tree` (PR #117). Primeira contribuição open source de todos os tempos — bem-vindo a bordo! 🎉
nesvet (Eugene Nesvetaev)	`get_repo`/`edit_repo` (PR #527); ferramentas de tópicos de repositório (PR #528); cancelar/excluir execuções de Actions e artefatos de execução (PR #533); `get_commit_statuses` (PR #542); ferramentas de pacote listar/obter/excluir/arquivos (PR #543); nomes de labels aceitos na criação, atribuição e substituição de issues (PR #591)
pisco (Marco Pisco)	Uploads `file_path` para anexos de issues, comentários e releases, com multipart de streaming para que grandes ativos de release não passem mais por base64 (PR #481)

Contribuidores da comunidade

Relatores de issues e participantes de discussões que moldaram a direção do projeto:

Contribuidor	Contribuições
byteflavour	Abriu #80 (descoberta de milestone/label), #85 (proposta de API de notificações); revisor ativo em discussões
choucavalier	Abriu #82 (correção de skill), #70 (releases macOS arm64), #62 (releases binárias e suporte a mise)
MalcolmMielle	Abriu #59 (ferramentas de revisão de PR — implementadas desde então)
redbeard	Abriu #60 (suporte a Actions — implementado desde então)
c6sepl6p	Abriu #72 (codificação base64), #54 (merge de pull request — implementado desde então)
malik	Abriu #73 (flag de versão), #47 (correção de build Nix)
a2800276	Abriu #74 (compatibilidade OpenAI)
simenandre	Abriu #49 (suporte a go install)
BasdP	Abriu #42 (suporte a Projects)
BoBeR182	Abriu #32 (suporte a wiki)
ignasgil	Abriu #95 (solicitação de recurso `remove_issue_labels`)
Vokuar	Abriu #99 (suporte a transporte HTTP streamable)
janbaer	Abriu #98 (responder a comentário de revisão)
fraschm98	Relatos de issues iniciais
heathen711	Abriu #106 (anexos de issue/comentário — implementado desde então); moldou o design do limite inline de 1 MiB + fallback `browser_download_url`
decarvalhoaa (Antonio De Carvalho)	Abriu #593 (limite de tamanho de resposta no servidor) a partir de um estouro real de janela de contexto atrás do Open WebUI, com a medição que motivou o trabalho de payload `list_repo_pull_requests` em #596
chris420 (Chris Oloff)	Abriu #452 (busca de issues em toda a org — implementada desde então como `search_issues`); revisão de design no PR #458 que substituiu a sonda de próxima página pela aplicação de teto de instância, e detectou o envelope de resposta reportando incorretamente seu próprio `limit`

Contribuidores Cyborg

Este projeto também recebeu contribuições de agentes de codificação de IA — enviadas como PRs regulares, revisadas por humanos:

Agente	Papel	Contribuições
brenner-axiom (b4-dev, B4arena)	Agente de desenvolvimento de IA	Ferramentas de gerenciamento de organização (PR #94); demonstrações showboat (PR #97); ferramentas `list_repo_milestones`, `list_repo_labels` (PR #83); correção de condição de corrida (PR #78); documentação de contribuidores (PR #87, #88); abriu #76; revisões de código
opencode	Agente de desenvolvimento de IA	Suporte a revisões e comentários de pull requests (PR #51)
claude-code	Agente de desenvolvimento de IA	Padrão de texto simples `get_file_content` e ferramentas `list_repo_contents`/`get_repo_tree`, em parceria com BrilliantKahn (PR #116, #117)
b4mad-release-agent	Automação de release	Changelog automatizado e marcação de releases
bot Renovate do #B4mad	Atualizações de dependências	Atualizações automatizadas de dependências

Quer contribuir? Abra uma issue ou pull request — todos são bem-vindos.

Licença

Este projeto é open source. Veja o repositório para detalhes da licença.