Servidor MCP HackMD

Um servidor Model Context Protocol (MCP) que faz interface com a API do HackMD, permitindo que clientes LLM acessem e interajam com notas, equipes, perfis de usuário e dados de histórico do HackMD.

Recursos

Obter informações do perfil do usuário
Criar, ler, atualizar e excluir notas
Gerenciar notas de equipe e colaborar com membros da equipe
Acessar histórico de leitura
Listar e gerenciar equipes
Suporte a transporte duplo: Transportes HTTP e STDIO
Pronto para implantação em nuvem: Suporte a Smithery e outras plataformas

Requisitos

Node.js 18+

Instalação Local (Transporte STDIO)

Adicione este servidor ao seu mcp.json / claude_desktop_config.json:

{
  "mcpServers": {
    "hackmd": {
      "command": "npx",
      "args": ["-y", "hackmd-mcp"],
      "env": {
        "HACKMD_API_TOKEN": "your_api_token"
      }
    }
  }
}

Você também pode opcionalmente definir a variável de ambiente HACKMD_API_URL se precisar usar um endpoint diferente da API do HackMD.

Reinicie seu cliente MCP (ex.: Claude Desktop)
Use as ferramentas para interagir com o HackMD

Implantação do Servidor (Transporte HTTP)

Auto-hospedagem

Siga as instruções de Desenvolvimento Local para configurar o projeto localmente e, em seguida, execute:

pnpm run start:http

Isso iniciará o servidor na porta 8081 por padrão. Você pode alterar a porta definindo a variável de ambiente PORT.

Implantação em Nuvem

Você pode implantar este servidor MCP em qualquer plataforma de nuvem que suporte aplicativos de servidor Node.js.

Você também pode implantar por meio de plataformas MCP como Smithery.

Configuração

Variáveis de Ambiente (Transporte STDIO e servidor de Transporte HTTP onde o host fornece a configuração)

Ao usar o transporte STDIO ou hospedar o servidor de transporte HTTP, você pode passar a configuração por meio de variáveis de ambiente:

HACKMD_API_TOKEN: Token da API do HackMD (Obrigatório para todas as operações)
HACKMD_API_URL: (Opcional) URL da API do HackMD (Padrão: https://api.hackmd.io/v1)

Variáveis de ambiente aplicadas apenas ao servidor de transporte HTTP:

ALLOWED_HACKMD_API_URLS: (Opcional) Uma lista separada por vírgulas de URLs permitidas da API do HackMD. O servidor rejeitará solicitações se a URL da API do HackMD fornecida não estiver nesta lista. Se não for definida, apenas a URL padrão (https://api.hackmd.io/v1) será permitida.

[!CAUTION] Se você estiver hospedando o servidor de transporte HTTP com token pré-configurado, deve proteger seu endpoint e implementar autenticação antes de permitir que usuários acessem. Caso contrário, qualquer pessoa pode acessar seu servidor MCP usando seu token do HackMD.

Cabeçalhos HTTP (Transporte HTTP onde o usuário fornece a configuração)

Ao usar o transporte HTTP, o usuário pode passar a configuração por meio de cabeçalhos HTTP:

Hackmd-Api-Token: Token da API do HackMD (Obrigatório para todas as operações)
Hackmd-Api-Url: (Opcional) URL da API do HackMD (Padrão: https://api.hackmd.io/v1)

Se o usuário fornecer o token no cabeçalho, enquanto o servidor também tiver HACKMD_API_TOKEN definido, o valor do cabeçalho terá precedência.

Obter um Token da API do HackMD

Para obter um token de API, siga estas etapas:

Acesse Configurações do HackMD.
Clique em "Criar Token de API".
Copie o token gerado e use-o no seu arquivo .env ou nas variáveis de ambiente.

Ferramentas Disponíveis

Ferramentas de Perfil

get_user_info: Obter informações sobre o usuário autenticado

Ferramentas de Equipes

list_teams: Listar todas as equipes acessíveis ao usuário

Ferramentas de Histórico

get_history: Obter o histórico de leitura do usuário

Ferramentas de Notas de Equipe

list_team_notes: Listar todas as notas em uma equipe
create_team_note: Criar uma nova nota em uma equipe
update_team_note: Atualizar uma nota existente em uma equipe
delete_team_note: Excluir uma nota em uma equipe

Ferramentas de Notas do Usuário

list_user_notes: Listar todas as notas de propriedade do usuário
get_note: Obter uma nota pelo seu ID
create_note: Criar uma nova nota
update_note: Atualizar uma nota existente
delete_note: Excluir uma nota

Exemplo de Uso

Gerenciamento Básico de Notas

Can you help me manage my HackMD notes?

Listar Notas

Please list all my notes.

Criar uma Nova Nota

Create a new note with the title "Meeting Notes" and content:
```
# Meeting Notes

Discussion points:
- Item 1
- Item 2
```

Colaboração em Equipe

Show me all the teams I'm part of and list the notes in the first team.

Desenvolvimento Local

Este projeto usa pnpm como gerenciador de pacotes.

Clone o repositório e instale as dependências:

git clone https://github.com/yuna0x0/hackmd-mcp.git
cd hackmd-mcp
pnpm install

Configuração

Crie um arquivo .env copiando o exemplo:

cp env.example .env

Edite o arquivo .env e adicione seu token da API do HackMD:

HACKMD_API_TOKEN=your_api_token

Depuração com o MCP Inspector

Você pode usar o MCP Inspector para testar e depurar o servidor MCP do HackMD:

npx @modelcontextprotocol/inspector -e HACKMD_API_TOKEN=your_api_token npx hackmd-mcp

# Use this instead when Local Development
pnpm run inspector

Em seguida, abra seu navegador na URL fornecida (geralmente http://localhost:6274) para acessar a interface do MCP Inspector. A partir daí, você pode:

Conectar-se ao seu servidor MCP do HackMD em execução
Navegar pelas ferramentas disponíveis
Executar ferramentas com parâmetros personalizados
Visualizar as respostas

Isso é particularmente útil para testar sua configuração antes de conectá-la a clientes MCP como o Claude Desktop.

Docker

Baixe do GitHub Container Registry:

docker pull ghcr.io/yuna0x0/hackmd-mcp

Build Docker (Desenvolvimento Local):

docker build -t ghcr.io/yuna0x0/hackmd-mcp .

Build Docker multi-plataforma (Desenvolvimento Local):

docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/yuna0x0/hackmd-mcp .

Pacotes MCP (MCPB)

Para criar um Pacote MCP para este servidor, execute:

pnpm run pack:mcpb

Aviso de Segurança

Este servidor MCP aceita seu token da API do HackMD no arquivo .env, variável de ambiente ou cabeçalho HTTP. Mantenha essas informações seguras e nunca as envie para o controle de versão.

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

HackMD

Documentação