fast-note-sync-mcp

Servidor MCP em Python para expor a REST API do Fast Note Sync como ferramentas MCP via FastMCP.

O projeto funciona como um wrapper entre clientes MCP e o backend fast-note-sync-service, permitindo consultar e editar o vault _Obsidian por stdio ou via transporte HTTP do fastmcp.

Visao Geral

Fluxo principal:

Cliente MCP
  -> server.py (FastMCP + httpx)
  -> REST API Fast Note Sync
  -> vault _Obsidian

O arquivo principal do projeto e server.py, que:

• carrega configuracao de .env
• monta headers obrigatorios da API
• encapsula chamadas HTTP com httpx
• publica as tools MCP com @mcp.tool

Requisitos

• Python 3.11 ou superior
• acesso ao backend Fast Note Sync
• token valido em API_TOKEN

Dependencias Python usadas pelo projeto:

• fastmcp
• httpx

Instalacao

Exemplo com venv:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configuracao

O projeto le automaticamente o arquivo .env no mesmo diretorio do server.py.

Comece copiando o arquivo de exemplo:

cp .env.example .env

Exemplo:

API_BASE_URL=http://seu-servidor:9009/api
API_TOKEN=seu_token_aqui
API_TIMEOUT_SECONDS=20

Variaveis suportadas:

• API_BASE_URL: URL base da REST API
• API_TOKEN: token Bearer obrigatorio
• API_TIMEOUT_SECONDS: timeout das requisicoes HTTP

Observacoes:

• se API_TOKEN nao estiver definido, o server.py falha no startup
• o arquivo .env esta ignorado no .gitignore

Execucao

Rodar diretamente com Python:

.venv/bin/python server.py

Esse modo e o mais comum para clientes MCP locais via stdio.

Transporte HTTP

Para expor o MCP via HTTP:

fastmcp run server.py:mcp --transport http --host 0.0.0.0 --port 8001

Exemplo De Configuracao MCP

Exemplo generico para clientes que aceitam processo Python:

{
  "mcpServers": {
    "fast-note-sync": {
      "type": "python",
      "command": "/caminho/para/.venv/bin/python",
      "args": [
        "/caminho/para/fast-note-sync-mcp/server.py"
      ]
    }
  }
}

Exemplo de configuracao no Hermes:

mcp_servers:
  fast-note-sync:
    command: /caminho/para/.venv/bin/python
    args:
      - /caminho/para/fast-note-sync-mcp/server.py
    enabled: true

Tools Expostas

O server.py atualmente expoe 36 tools MCP, agrupadas nestas categorias:

• Sistema: health_check, get_version, get_webgui_config, get_user_info
• Vaults: list_vaults, get_vault_detail
• Pastas: get_folder_info, create_folder, delete_folder, get_folder_tree, list_folders, list_folder_notes
• Notas leitura: get_note, search_notes, get_note_outlinks, get_note_backlinks
• Notas escrita: create_or_update_note, append_to_note, prepend_to_note, replace_in_note, delete_note, restore_note
• Frontmatter: set_note_frontmatter, delete_note_frontmatter
• Organizacao: move_note, rename_note
• Historico: get_note_history, get_note_history_detail
• Arquivos: get_file_list, get_file_info
• Outras: list_shares, get_storage_configs, get_enabled_storage_types, get_git_sync_configs, get_system_info, get_backup_configs

Comportamento Importante

• set_note_frontmatter esta funcional e envia o valor como lista de um item no payload de update
• replace_in_note suporta busca literal e regex
• move_note e rename_note usam o mesmo endpoint backend
• algumas tools podem depender das permissoes do token usado no backend

Teste Rapido

Validar import e carregamento do .env:

.venv/bin/python -c "import server; print(server.API_BASE_URL); print(bool(server.API_TOKEN))"

Testar health check:

.venv/bin/python - <<'PY'
import json
import server
print(json.dumps(server.health_check(), ensure_ascii=False, indent=2))
PY

Estrutura Atual

fast-note-sync-mcp/
  .env
  .env.example
  .gitignore
  requirements.txt
  server.py
  README.md

Seguranca

• nao comite o .env
• trate API_TOKEN como credencial sensivel
• se o token ja tiver sido exposto anteriormente, faca rotacao

Desenvolvimento

Como o projeto esta concentrado em um unico arquivo, a manutencao tipica envolve:

• adicionar ou ajustar uma tool em server.py
• validar a chamada contra a API real
• atualizar este README.md se o contrato mudar