# 🔗 OBSIDIAN MCP SERVER

Bridge MCP usando **stdio transport** para conectar Claude Desktop ao seu vault Obsidian via Local REST API.

**Versão 2.0** - Refatorado para usar arquitetura stdio (sem necessidade de ngrok!)

---

## 📋 PRÉ-REQUISITOS

✅ Node.js instalado (v18+)
✅ Plugin "Local REST API" ativo no Obsidian
✅ Claude Desktop instalado (para uso local)

**NÃO é necessário:**
❌ ngrok ou ferramentas de tunneling
❌ Servidor HTTP externo
❌ Configurações de porta ou firewall complexas

---

## ⚡ INSTALAÇÃO RÁPIDA

### 1. CLONE OU BAIXE OS ARQUIVOS

```bash
git clone <repo-url> obsidian-mcp
cd obsidian-mcp
```

Ou baixe os arquivos:
- `obsidian-mcp-server.js`
- `package.json`
- `.env.example`

### 2. INSTALE DEPENDÊNCIAS

```bash
npm install
```

### 3. CONFIGURE A API KEY

Copie o arquivo de exemplo:
```bash
cp .env.example .env
```

Edite `.env` e preencha:
```bash
OBSIDIAN_API_KEY=sua_api_key_aqui
OBSIDIAN_URL=http://127.0.0.1:27123
```

**Como obter a API Key:**
1. Abra Obsidian
2. Settings → Community Plugins → Local REST API
3. Ative "Enable Non-encrypted (HTTP) Server"
4. Copie a API Key exibida

### 4. TESTE O SERVIDOR (Opcional)

```bash
./start-server.sh
```

Você deve ver:
```
╔════════════════════════════════════════════╗
║   OBSIDIAN MCP SERVER - RODANDO ✓         ║
╚════════════════════════════════════════════╝

📁 Obsidian API: http://127.0.0.1:27123
🔑 API Key: 2c134def4a...

🚀 Aguardando comandos do Claude Desktop via stdio...
```

Pressione `Ctrl+C` para parar.

### 5. CONFIGURE NO CLAUDE DESKTOP

Veja o guia completo: **[CLAUDE_DESKTOP_CONFIG.md](CLAUDE_DESKTOP_CONFIG.md)**

**Resumo:**
1. Edite `claude_desktop_config.json` (veja seção abaixo)
2. Reinicie Claude Desktop
3. Teste usando ferramentas MCP

---

## 🖥️ CONFIGURAÇÃO CLAUDE DESKTOP

### Localização do Arquivo de Configuração

**Windows:**
```
%APPDATA%\Claude\claude_desktop_config.json
```

**macOS:**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Ou acesse via Claude Desktop:**
Settings → Developer → "Edit Config"

### Exemplo de Configuração

#### Linux/macOS:
```json
{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/home/usuario/obsidian-mcp/obsidian-mcp-server.js"],
      "env": {
        "OBSIDIAN_API_KEY": "sua_api_key_aqui",
        "OBSIDIAN_URL": "http://127.0.0.1:27123"
      }
    }
  }
}
```

#### Windows (WSL):
```json
{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": [
        "\\\\wsl$\\Ubuntu\\home\\usuario\\obsidian-mcp\\obsidian-mcp-server.js"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "sua_api_key_aqui",
        "OBSIDIAN_URL": "http://172.x.x.x:27123"
      }
    }
  }
}
```

**⚠️ Windows WSL:** Ajuste o IP `172.x.x.x` para o IP do seu Windows host.
Veja instruções completas em [CLAUDE_DESKTOP_CONFIG.md](CLAUDE_DESKTOP_CONFIG.md).

### Reiniciar Claude Desktop

Após editar a configuração:
1. **Feche completamente** Claude Desktop
2. **Reabra** Claude Desktop
3. Aguarde alguns segundos para o servidor MCP iniciar

---

## 🛠️ FERRAMENTAS DISPONÍVEIS

Quando conectado, Claude Desktop terá acesso a:

### `list_vault_files()`
Lista todos os arquivos .md do vault
```
Claude: "Liste todos os meus arquivos do Obsidian"
```

### `read_note(path)`
Lê conteúdo de nota específica
```
Claude: "Leia a nota 'Projetos/Ideia X.md'"
```

### `search_notes(query)`
Busca por texto em todas as notas
```
Claude: "Busque notas sobre 'machine learning'"
```

### `create_note(path, content)`
Cria nova nota
```
Claude: "Crie uma nota em 'Daily/2025-10-05.md' com resumo da conversa"
```

### `update_note(path, content)`
Atualiza nota existente
```
Claude: "Atualize 'TODO.md' adicionando tarefa X"
```

---

## 🔧 CONFIGURAÇÃO AVANÇADA

### Mudar URL do Obsidian

Se o Obsidian estiver em outra máquina ou porta:

```bash
export OBSIDIAN_URL="http://192.168.1.100:27123"
```

Ou edite diretamente no `.env`.

### Testar Conexão com Obsidian

```bash
curl -s http://127.0.0.1:27123 \
  -H "Authorization: Bearer SUA_API_KEY" | jq
```

Deve retornar JSON com `"status": "OK"`.

### Logs e Debugging

Logs do servidor vão para **stderr** (não interfere com stdio):
- Quando executado pelo Claude Desktop, logs ficam em:
  - Windows: `%APPDATA%\Claude\logs\mcp*.log`
  - macOS: `~/Library/Logs/Claude/mcp*.log`

---

## 🌐 CONFIGURAÇÃO WINDOWS WSL

Se você usa WSL (Windows Subsystem for Linux), use **Mirrored Networking Mode** para acesso direto ao localhost do Windows.

### 1. Ativar Mirrored Networking (Windows 11 22H2+)

Crie o arquivo `.wslconfig` no Windows:

**Caminho:** `C:\Users\SeuUsuario\.wslconfig`

**Conteúdo:**
```ini
[wsl2]
networkingMode=mirrored
```

### 2. Reiniciar WSL

```powershell
wsl --shutdown
```

Depois reabra o WSL.

### 3. Configurar .env

Com mirrored networking, use `localhost` diretamente:

```bash
OBSIDIAN_API_KEY=sua_api_key_aqui
OBSIDIAN_URL=http://127.0.0.1:27123
```

### 4. Testar Conexão

```bash
curl -s http://127.0.0.1:27123 \
  -H "Authorization: Bearer SUA_API_KEY" | jq
```

Deve retornar JSON com `"status": "OK"`.

Veja guia completo em: **[CLAUDE_DESKTOP_CONFIG.md](CLAUDE_DESKTOP_CONFIG.md)**

---

## ❗ TROUBLESHOOTING

### "OBSIDIAN_API_KEY não configurada"
→ Configure a variável de ambiente ou edite `.env`

### "ECONNREFUSED 127.0.0.1:27123"
→ Certifique-se que o Obsidian está aberto e o plugin Local REST API está ativo com HTTP server habilitado

### "401 Unauthorized"
→ Verifique se a API Key está correta. Copie novamente do Obsidian.

### "Server Disconnected" no Claude Desktop
→ Verifique logs em `%APPDATA%\Claude\logs\mcp*.log` (Windows) ou `~/Library/Logs/Claude/` (macOS)

### WSL: Connection refused ao acessar Windows
→ Verifique port proxy e firewall (veja seção Windows WSL acima)

---

## 🎯 EXEMPLO DE USO REAL

**VOCÊ NO CLAUDE DESKTOP:**
> "Liste todos os meus projetos no Obsidian e resuma os principais tópicos"

**CLAUDE FAZ:**
1. Chama `list_vault_files()`
2. Filtra arquivos da pasta "Projetos/"
3. Para cada arquivo, chama `read_note(path)`
4. Analisa conteúdo e gera resumo estruturado

**VOCÊ:**
> "Crie uma nota de reunião com as decisões que discutimos"

**CLAUDE FAZ:**
1. Chama `create_note("Reuniões/2025-10-05.md", conteudo)`
2. Formata a nota em markdown
3. Confirma criação

---

## 📦 RODAR COMO SERVIÇO (Opcional)

### Linux (systemd)

Crie `/etc/systemd/system/obsidian-mcp.service`:
```ini
[Unit]
Description=Obsidian MCP Server
After=network.target

[Service]
Type=simple
User=seu-usuario
WorkingDirectory=/caminho/para/obsidian-mcp
Environment="OBSIDIAN_API_KEY=sua-key-aqui"
Environment="OBSIDIAN_URL=http://127.0.0.1:27123"
ExecStart=/usr/bin/node /caminho/para/obsidian-mcp/obsidian-mcp-server.js
Restart=always

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl enable obsidian-mcp
sudo systemctl start obsidian-mcp
```

### macOS (launchd)

Crie `~/Library/LaunchAgents/com.obsidian-mcp.plist`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.obsidian-mcp</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/node</string>
        <string>/caminho/para/obsidian-mcp-server.js</string>
    </array>
    <key>EnvironmentVariables</key>
    <dict>
        <key>OBSIDIAN_API_KEY</key>
        <string>sua-key-aqui</string>
        <key>OBSIDIAN_URL</key>
        <string>http://127.0.0.1:27123</string>
    </dict>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>
```

```bash
launchctl load ~/Library/LaunchAgents/com.obsidian-mcp.plist
```

**⚠️ NOTA:** Para uso com Claude Desktop, NÃO é necessário rodar como serviço. Claude Desktop gerencia o processo automaticamente.

---

## 🔄 MIGRAÇÃO DA VERSÃO 1.0 (HTTP)

Se você usava a versão antiga com ngrok:

**O que mudou (v1.0 → v2.0):**
- ✅ Removido servidor HTTP (porta 3000)
- ✅ Removido necessidade de ngrok
- ✅ Adicionado stdio transport
- ✅ Integração direta com Claude Desktop
- ✅ Corrigido Content-Type para `text/markdown` (criar/atualizar notas)
- ✅ Suporte a WSL mirrored networking mode

**Como migrar:**
1. Atualize os arquivos do projeto
2. Execute `npm install` para instalar `@modelcontextprotocol/sdk`
3. Configure Claude Desktop seguindo [CLAUDE_DESKTOP_CONFIG.md](CLAUDE_DESKTOP_CONFIG.md)
4. Remova referências a ngrok

**Backup da versão HTTP:**
O arquivo original foi salvo em `obsidian-mcp-server-http.js.bak`

---

## 📚 ARQUITETURA

```
┌─────────────────┐
│ Claude Desktop  │
│   (Windows)     │
└────────┬────────┘
         │ stdio transport
         │ (stdin/stdout)
         ▼
┌─────────────────┐
│  MCP Server     │
│     (WSL)       │
└────────┬────────┘
         │ HTTP REST API
         │ (via port proxy)
         ▼
┌─────────────────┐
│ Obsidian REST   │
│ API (Windows)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Obsidian       │
│  Vault (.md)    │
└─────────────────┘
```

---

## 📝 NOTAS TÉCNICAS

### Content-Type para Criação de Notas

O Obsidian Local REST API **requer** `Content-Type: text/markdown` para operações de criação e atualização de arquivos. O servidor MCP implementa dois métodos de requisição:

- **`request()`** - Para operações de leitura/listagem (usa `application/json`)
- **`requestText()`** - Para criar/atualizar arquivos (usa `text/markdown`)

Se você encontrar erro `40010` ao criar notas, verifique se está usando a versão v2.0+ do servidor que inclui essa correção.

### WSL Mirrored Networking

Para Windows 11 22H2+, o modo mirrored networking permite que WSL acesse `localhost` do Windows diretamente, eliminando necessidade de:
- Port proxy (netsh)
- Descobrir IP do host Windows
- Configurar firewall

Simplesmente crie `.wslconfig` com `networkingMode=mirrored` e reinicie WSL.

---

## 🚀 PRÓXIMOS PASSOS

Depois de configurar:

1. "Liste todos os meus arquivos do Obsidian"
2. "Analise os temas mais frequentes nas minhas notas"
3. "Encontre todas as referências sobre [tópico X]"
4. "Crie uma nota resumindo nossas conversas de hoje"
5. "Organize minhas notas de projeto criando um índice"

---

## 🤝 CONTRIBUINDO

Melhorias são bem-vindas! Sinta-se livre para:
- Reportar bugs
- Sugerir novas funcionalidades
- Enviar pull requests

---

## 📄 LICENÇA

MIT - Use como quiser!

---

## 📖 RECURSOS ADICIONAIS

- **[CLAUDE_DESKTOP_CONFIG.md](CLAUDE_DESKTOP_CONFIG.md)** - Guia completo de configuração
- [Model Context Protocol](https://modelcontextprotocol.io/) - Documentação oficial MCP
- [Obsidian Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) - Plugin Obsidian
- [Claude Desktop](https://claude.ai/download) - Download Claude Desktop

---

## 🎖️ CRÉDITOS

**Desenvolvido por Aurora × Fernando** 🤝

MCP (Model Context Protocol) por [Anthropic](https://www.anthropic.com/)
Obsidian Local REST API por [Adam Coddington](https://github.com/coddingtonbear)

---

**Versão 2.0.0** - Refatorado para stdio transport (2025)