Obsidian Local REST API

Interaja com seu cofre local do Obsidian usando uma API REST.

Documentação

Servidor MCP Obsidian Local REST API

Um servidor MCP (Model Context Protocol) nativo de IA que fornece ferramentas inteligentes e orientadas a tarefas para interagir com cofres do Obsidian por meio de uma API REST local.

🧠 Filosofia de Design Nativo de IA

Este servidor MCP foi redesenhado seguindo princípios nativos de IA, em vez de um simples mapeamento de API para ferramentas. Em vez de expor operações CRUD de baixo nível, ele fornece ferramentas de alto nível e orientadas a tarefas que os LLMs podem raciocinar de forma mais eficaz.

Antes vs Depois: A Transformação

Abordagem Antiga (Baseada em CRUD)	Nova Abordagem (Nativa de IA)	Por que é Melhor
`list_files` (retorna tudo)	`list_directory(path, limit, offset)`	Evita sobrecarga de contexto com paginação
`create_file` + `update_file`	`write_file(path, content, mode)`	Ferramenta única lida com criar/atualizar/anexar
`create_note` + `update_note`	`create_or_update_note(path, content, frontmatter)`	Upsert inteligente remove a complexidade de decisão
`search_notes(query)`	`search_vault(query, scope, path_filter)`	Busca precisa e escalável com filtragem avançada
(sem equivalente)	`get_daily_note(date)`	Abstração de alto nível para fluxo de trabalho comum
(sem equivalente)	`get_recent_notes(limit)`	Acesso recente a arquivos orientado a tarefas
(sem equivalente)	`find_related_notes(path, on)`	Descoberta de relacionamentos conceituais

🛠 Ferramentas Disponíveis

Operações de Diretório e Arquivo

`list_directory`

Propósito: Listar o conteúdo do diretório com paginação para evitar sobrecarga de contexto

{
  "path": "Projects/",
  "recursive": false,
  "limit": 20,
  "offset": 0
}

Benefício de IA: O LLM pode explorar a estrutura do cofre incrementalmente sem sobrecarregar o contexto

`read_file`

Propósito: Ler o conteúdo de qualquer arquivo no cofre

{"path": "notes/meeting-notes.md"}

`write_file`

Propósito: Escrever arquivo com múltiplos modos - substitui operações separadas de criar/atualizar

{
  "path": "notes/summary.md",
  "content": "# Meeting Summary\n...",
  "mode": "append"  // "overwrite", "append", "prepend"
}

Benefício de IA: Ferramenta única lida com todos os cenários de escrita, eliminando ambiguidade

`delete_item`

Propósito: Excluir qualquer arquivo ou diretório

{"path": "old-notes/"}

Operações de Notas Nativas de IA

`create_or_update_note`

Propósito: Upsert inteligente - cria se não existir, atualiza se existir

{
  "path": "daily/2024-12-26",
  "content": "## Tasks\n- Review AI-native MCP design",
  "frontmatter": {"tags": ["daily", "tasks"]}
}

Benefício de IA: Elimina a árvore de decisão "esta nota existe?"

`get_daily_note`

Propósito: Recuperação inteligente de notas diárias com padrões comuns de nomenclatura

{"date": "today"}  // or "yesterday", "2024-12-26"

Benefício de IA: Abstrai detalhes do sistema de arquivos e convenções de nomenclatura

`get_recent_notes`

Propósito: Obter notas modificadas recentemente

{"limit": 5}

Benefício de IA: Corresponde a consultas naturais como "no que trabalhei recentemente?"

Busca Avançada e Descoberta

`search_vault`

Propósito: Busca em múltiplos escopos com filtragem avançada

{
  "query": "machine learning",
  "scope": ["content", "filename", "tags"],
  "path_filter": "research/"
}

Benefício de IA: Busca precisa e direcionada reduz ruído

`find_related_notes`

Propósito: Descobrir relacionamentos conceituais entre notas

{
  "path": "ai-research.md",
  "on": ["tags", "links"]
}

Benefício de IA: Habilita fluxos de trabalho baseados em relacionamentos e descoberta serendipitosa

Ferramentas Legadas (Compatibilidade Retroativa)

O servidor mantém compatibilidade retroativa com ferramentas existentes como get_note, list_notes, get_metadata_keys, etc.

Pré-requisitos

Node.js 18+ ou runtime Bun
Obsidian Local REST API rodando localmente (padrão: http://obsidian-local-rest-api.test)

Instalação

Usando npx (Recomendado)

npx obsidian-local-rest-api-mcp

A partir do Código Fonte

# Clone the repository
git clone https://github.com/j-shelfwood/obsidian-local-rest-api-mcp.git
cd obsidian-local-rest-api-mcp

# Install dependencies with bun
bun install

# Build the project
bun run build

Configuração

Defina variáveis de ambiente para a conexão com a API:

export OBSIDIAN_API_URL="http://obsidian-local-rest-api.test"  # Default URL (or http://localhost:8000 for non-Valet setups)
export OBSIDIAN_API_KEY="your-api-key"          # Optional bearer token

Uso

Executando o Servidor

# Development mode with auto-reload
bun run dev

# Production mode
bun run start

# Or run directly
node build/index.js

Configuração do Cliente MCP

Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "npx",
      "args": ["obsidian-local-rest-api-mcp"],
      "env": {
        "OBSIDIAN_API_URL": "http://obsidian-local-rest-api.test",
        "OBSIDIAN_API_KEY": "your-api-key-if-needed"
      }
    }
  }
}

VS Code com Extensão MCP

Use o arquivo de configuração .vscode/mcp.json incluído.

Desenvolvimento

# Watch mode for development
bun run dev

# Build TypeScript
bun run build

# Type checking
bun run tsc --noEmit

Arquitetura

ObsidianApiClient - Wrapper de cliente HTTP para endpoints da API REST
ObsidianMcpServer - Implementação do servidor MCP com manipuladores de ferramentas
Configuração - Configuração baseada em ambiente com validação

Tratamento de Erros

O servidor inclui tratamento abrangente de erros:

Falhas de conexão com a API
Parâmetros de ferramenta inválidos
Timeouts de rede
Erros de autenticação

Erros são retornados como respostas de chamadas de ferramentas MCP com mensagens descritivas.

Depuração

Ative o registro de depuração definindo variáveis de ambiente:

export DEBUG=1
export NODE_ENV=development

Os logs do servidor são gravados em stderr para evitar interferência na comunicação do protocolo MCP em stdout.

Solução de Problemas

Falha ao Iniciar o Servidor MCP

Se o seu cliente MCP mostrar "Falha ao Iniciar" ou erros semelhantes:

Teste o servidor diretamente:
```
npx obsidian-local-rest-api-mcp --version
```
Deve exibir o número da versão.

Teste o protocolo MCP:

# Run our test script
node -e "
const { spawn } = require('child_process');
const child = spawn('npx', ['obsidian-local-rest-api-mcp'], { stdio: ['pipe', 'pipe', 'pipe'] });
child.stdout.on('data', d => console.log('OUT:', d.toString()));
child.stderr.on('data', d => console.log('ERR:', d.toString()));
setTimeout(() => {
  child.stdin.write(JSON.stringify({jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2024-11-05',capabilities:{},clientInfo:{name:'test',version:'1.0.0'}}})+'\n');
  setTimeout(() => child.kill(), 2000);
}, 500);
"

Deve mostrar a resposta de inicialização.

Verifique as Variáveis de Ambiente:
- Certifique-se de que OBSIDIAN_API_URL aponte para um Obsidian Local REST API em execução
- Teste a API diretamente: curl http://obsidian-local-rest-api.test/api/files (ou sua URL de API configurada)
Verifique o Obsidian Local REST API:
- Instale e execute Obsidian Local REST API
- Confirme que está acessível na porta configurada
- Verifique se a autenticação é necessária

Problemas Comuns

"Comando não encontrado": Certifique-se de que Node.js/npm está instalado e npx está disponível

"Conexão recusada": O Obsidian Local REST API não está em execução ou a URL está errada

Domínios .test do Laravel Valet: Se estiver usando Laravel Valet, certifique-se de que o nome do diretório do seu projeto corresponda ao domínio .test (por exemplo, obsidian-local-rest-api.test para um projeto em /obsidian-local-rest-api/)

"Não autorizado": Verifique se a chave da API é necessária e está configurada corretamente

"Timeout": Aumente o timeout na configuração do cliente ou verifique a conectividade de rede

Configuração do Cherry Studio

Para o Cherry Studio, use estas configurações exatas:

Nome: obsidian-vault (ou qualquer nome que preferir)
Tipo: Standard Input/Output (stdio)
Comando: npx
Argumentos: obsidian-local-rest-api-mcp
Variáveis de Ambiente:
- OBSIDIAN_API_URL: Sua URL da API (por exemplo, http://obsidian-local-rest-api.test para Laravel Valet)
- OBSIDIAN_API_KEY: Chave da API opcional se a autenticação for necessária
Variáveis de Ambiente:
- OBSIDIAN_API_URL: http://obsidian-local-rest-api.test (ou sua URL da API)
- OBSIDIAN_API_KEY: your-api-key (se necessário)

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Faça alterações com tipos TypeScript adequados
Teste com seu cofre do Obsidian
Envie um pull request

Licença

MIT