Notemd MCP

Um servidor backend para o plugin Notemd do Obsidian, oferecendo processamento de texto com IA e gerenciamento de conhecimento.

GitHub

Experimente este MCPPatrocinado

Documentação

Notemd MCP (Mission Control Platform) Server

==================================================
  _   _       _   _ ___    __  __ ___
 | \ | | ___ | |_| |___|  |  \/  |___ \
 |  \| |/ _ \| __| |___|  | |\/| |   | |
 | |\  | (_) | |_| |___   | |  | |___| |
 |_| \_|\___/ \__|_|___|  | |  | |____/
==================================================
   AI-Powered Backend for Your Knowledge Base
==================================================

Bem-vindo ao Notemd MCP Server! Este projeto fornece um poderoso servidor backend autônomo que expõe as funcionalidades principais de processamento de texto com IA e gerenciamento de conhecimento do Notemd Obsidian Plugin.

English | 简体中文

Construído com Python e FastAPI, este servidor permite que você descarregue tarefas computacionais pesadas do cliente e fornece uma API robusta para interagir com sua base de conhecimento programaticamente.

Recursos

Enriquecimento de Conteúdo com IA: Processa automaticamente conteúdo Markdown para identificar conceitos-chave e criar [[wiki-links]], construindo um grafo de conhecimento profundamente interconectado.
Geração Automatizada de Documentação: Gera documentação abrangente e estruturada a partir de um único título ou palavra-chave, opcionalmente usando pesquisa web para contexto.
Pesquisa Web Integrada e Resumo: Realiza pesquisas web usando Tavily ou DuckDuckGo e usa um LLM para fornecer resumos concisos sobre qualquer tópico.
Fluxos de Trabalho de Diagramas (Canônico + Alias de Compatibilidade): Suporta generate_diagram como fluxo canônico, além de generate_experimental_diagram como alias de compatibilidade legado alinhado às superfícies de comando modernas do NotEMD.
Utilitários de Tradução e Extração: Adiciona operações de primeira classe de tradução, extração de conceitos e extração verbatim de texto original para pipelines de automação.
Integridade do Grafo de Conhecimento: Inclui endpoints para atualizar ou remover automaticamente backlinks quando arquivos são renomeados ou excluídos, prevenindo links quebrados.
Correção de Sintaxe: Fornece um utilitário para corrigir em lote erros comuns de sintaxe Mermaid.js e LaTeX frequentemente encontrados em conteúdo gerado por LLM.
Altamente Configurável: Todos os principais recursos, chaves de API, caminhos de arquivo e parâmetros de modelo são facilmente gerenciados em um arquivo central config.py.
Suporte Multi-LLM: Compatível com qualquer API compatível com OpenAI, incluindo modelos locais via LMStudio e Ollama, e provedores de nuvem como DeepSeek, Anthropic, Google e outros.
Documentação Interativa da API: Inclui documentação interativa da API gerada automaticamente via Swagger UI.

Como Funciona

O servidor é construído sobre uma arquitetura simples e lógica:

main.py (Camada de API): Define todos os endpoints da API usando o framework FastAPI. Ele lida com requisições recebidas, valida dados usando Pydantic e chama as funções apropriadas da camada de lógica central.
notemd_core.py (Camada de Lógica): O motor da aplicação. Contém toda a lógica de negócio para interagir com LLMs, processar texto, realizar pesquisas web e gerenciar arquivos dentro da sua base de conhecimento.
config.py (Espaço Definido pelo Usuário): O hub central de configuração. É aqui que você define seus caminhos de arquivo, chaves de API e ajusta o comportamento do servidor para atender às suas necessidades.
cli.js (Ponte MCP): Uma interface de linha de comando baseada em Node.js que atua como ponte para o servidor Python. Ela usa o @modelcontextprotocol/sdk para criar um servidor que pode ser chamado por outras ferramentas. Ela inicia o servidor FastAPI e então se comunica com ele via requisições HTTP.

Primeiros Passos

Siga estes passos para colocar o servidor Notemd MCP em funcionamento na sua máquina local.

Pré-requisitos

Para execução em Python: Python 3.8+ e pip ou uv.
Para execução via NPX: Node.js e npx.

Instalação e Execução

Escolha o método que melhor se adequa ao seu fluxo de trabalho.

Método 1: Usando `npx` (Recomendado para Início Rápido)

Esta é a forma mais simples de iniciar o servidor. npx baixará e executará temporariamente o pacote. Este método agora suporta modo stdio, o que significa que você verá os logs do servidor FastAPI diretamente no seu terminal.

# This single command will download the package and start the server.
npx notemd-mcp-server

Método 2: Instalação Local com `uv` ou `pip`

Este método é para usuários que desejam clonar o repositório e gerenciar os arquivos localmente.

Clone o repositório:

git clone https://github.com/your-repo/notemd-mcp.git
cd notemd-mcp

Instale as dependências:

Usando uv (Recomendado):

uv venv
uv pip install -r requirements.txt

Usando pip:

python -m venv .venv
# Activate the environment (e.g., source .venv/bin/activate)
pip install -r requirements.txt

Execute o servidor:
```
uvicorn main:app --reload
```

Método 3: Configuração MCP

Para integrar o Notemd MCP à sua configuração da Mission Control Platform (MCP), adicione o seguinte ao objeto mcpServers no seu arquivo settings.json:

 {
   "mcpServers": {
     "notemd-mcp": {
       "description": "Notemd MCP Server - AI-powered text processing and knowledge management
 for your Markdown files.",
       "command": "npx",
       "args": [
         "-y",
         "notemd-mcp-server"
       ],
       "env": {
         "OPENAI_API_KEY": "your_openai_api_key_here",
         "DEEPSEEK_API_KEY": "your_deepseek_api_key_here"
       }
     }
   }
 }

Uso

A melhor forma de explorar e interagir com a API é através da documentação gerada automaticamente.

Navegue até http://127.0.0.1:8000/docs no seu navegador web.

Você verá uma Swagger UI completa e interativa onde poderá visualizar detalhes de cada endpoint, ver modelos de requisição e até enviar requisições de teste diretamente do seu navegador.

Endpoints da API

Endpoint	Método	Descrição	Corpo da Requisição	Resposta
`/process_content`	`POST`	Recebe um bloco de texto e o enriquece com `[[wiki-links]]`.	`{"content": "string", "cancelled": "boolean"}`	`{"processed_content": "string"}`
`/generate_title`	`POST`	Gera documentação completa a partir de um único título.	`{"title": "string", "cancelled": "boolean"}`	`{"generated_content": "string"}`
`/research_summarize`	`POST`	Realiza uma pesquisa web sobre um tópico e retorna um resumo gerado por IA.	`{"topic": "string", "cancelled": "boolean"}`	`{"summary": "string"}`
`/execute_custom_prompt`	`POST`	Executa um prompt definido pelo usuário com o conteúdo fornecido.	`{"prompt": "string", "content": "string", "cancelled": "boolean"}`	`{"response": "string"}`
`/translate_content`	`POST`	Traduz texto/markdown para um idioma de destino.	`{"content": "string", "target_language": "string", "cancelled": "boolean"}`	`{"translated_content": "string"}`
`/summarize_as_mermaid`	`POST`	Resume o conteúdo como um mindmap Mermaid.	`{"content": "string", "target_language": "string", "cancelled": "boolean"}`	`{"mermaid_summary": "string"}`
`/generate_diagram`	`POST`	Endpoint canônico de geração de diagramas.	`{"content": "string", "diagram_intent": "string", "target_language": "string", "compatibility_mode": "string", "cancelled": "boolean"}`	`{"diagram": "string"}`
`/generate_experimental_diagram`	`POST`	Alias de compatibilidade legado para geração de diagramas.	`{"content": "string", "diagram_intent": "string", "target_language": "string", "cancelled": "boolean"}`	`{"diagram": "string"}`
`/preview_diagram`	`POST`	Endpoint canônico de pré-visualização de diagramas (sem efeitos colaterais em arquivos).	`{"content": "string", "diagram_intent": "string", "target_language": "string", "compatibility_mode": "string", "cancelled": "boolean"}`	`{"diagram": "string"}`
`/preview_experimental_diagram`	`POST`	Alias de pré-visualização legado para compatibilidade.	`{"content": "string", "diagram_intent": "string", "target_language": "string", "cancelled": "boolean"}`	`{"diagram": "string"}`
`/extract_concepts`	`POST`	Extrai lista de conceitos centrais sem duplicatas.	`{"content": "string", "cancelled": "boolean"}`	`{"concepts": ["..."]}`
`/extract_original_text`	`POST`	Extrai correspondências verbatim para entrada do usuário a partir do conteúdo de referência.	`{"reference_content": "string", "user_input": "string", "cancelled": "boolean"}`	`{"extracted_text": "string"}`
`/check_duplicates`	`POST`	Retorna termos duplicados normalizados detectados no conteúdo.	`{"content": "string"}`	`{"duplicates": ["..."], "count": 0}`
`/handle_file_rename`	`POST`	Atualiza todos os backlinks no vault quando um arquivo é renomeado.	`{"old_path": "string", "new_path": "string"}`	`{"status": "success"}`
`/handle_file_delete`	`POST`	Remove todos os backlinks para um arquivo que foi excluído.	`{"path": "string"}`	`{"status": "success"}`
`/batch_fix_mermaid`	`POST`	Escaneia uma pasta e corrige erros comuns de sintaxe Mermaid.js e LaTeX em arquivos `.md`.	`{"folder_path": "string"}`	`{"errors": [], "modified_count": "integer"}`
`/health`	`GET`	Uma verificação de saúde simples para confirmar que o servidor está em execução.	(None)	`{"status": "ok"}`

Configuração

Toda a configuração é gerenciada no arquivo config.py. Aqui você pode definir chaves de API, caminhos de arquivo e outras configurações.

Configurações Principais

A função notemd_core.set_settings em main.py inicializa as funcionalidades principais do servidor usando os seguintes parâmetros, principalmente provenientes de config.py:

DEFAULT_PROVIDERS: Uma lista de dicionários, cada um definindo um provedor de LLM com seu name, apiKey, baseUrl, model, temperature e apiVersion opcional (para Azure OpenAI).
ACTIVE_PROVIDER: O nome do provedor de LLM a ser usado por padrão para todas as operações.
CHUNK_WORD_COUNT: O número máximo de palavras por chunk ao processar conteúdo para wiki-linking.
MAX_TOKENS: O número máximo de tokens permitido para interações com LLM.
ENABLE_DUPLICATE_DETECTION: Booleano para habilitar/desabilitar a detecção de conceitos duplicados durante o wiki-linking.

Configuração de Caminhos de Arquivo

Estas configurações definem a estrutura de diretórios para sua base de conhecimento e logs:

VAULT_ROOT: O caminho absoluto para seu vault Obsidian ou o diretório raiz dos seus arquivos Markdown.
CONCEPT_NOTE_FOLDER: A subpasta dentro de VAULT_ROOT onde as notas de conceito geradas serão armazenadas.
PROCESSED_FILE_FOLDER: A subpasta onde os arquivos Markdown processados serão movidos.
CONCEPT_LOG_FOLDER: A subpasta para armazenar logs de geração de conceitos.
CONCEPT_LOG_FILE_NAME: O nome do arquivo de log para geração de conceitos.

Configuração de Pesquisa

Configurações relacionadas à pesquisa web e resumo:

TAVILY_API_KEY: Sua chave de API para Tavily, se SEARCH_PROVIDER estiver definido como "tavily".
SEARCH_PROVIDER: Especifica o mecanismo de pesquisa web a ser usado ("tavily" ou "duckduckgo").
DDG_MAX_RESULTS: Número máximo de resultados a buscar do DuckDuckGo.
DDG_FETCH_TIMEOUT: Tempo limite em segundos para pesquisas no DuckDuckGo.
MAX_RESEARCH_CONTENT_TOKENS: Tokens máximos para conteúdo usado em pesquisa.
ENABLE_RESEARCH_IN_GENERATE_CONTENT: Booleano para habilitar/desabilitar pesquisa web ao gerar conteúdo a partir de um título.
TAVILY_MAX_RESULTS: Número máximo de resultados a buscar do Tavily.
TAVILY_SEARCH_DEPTH: Profundidade de pesquisa para Tavily ("basic" ou "advanced").

Configurações de Chamadas de API Estáveis

Estas configurações controlam o mecanismo de nova tentativa para chamadas de API de LLM:

ENABLE_STABLE_API_CALL: Booleano para habilitar/desabilitar chamadas de API estáveis com novas tentativas.
API_CALL_INTERVAL: Intervalo em segundos entre novas tentativas de chamadas de API.
API_CALL_MAX_RETRIES: Número máximo de novas tentativas para uma chamada de API com falha.

Configurações Multi-Modelo e Específicas de Tarefa

Estas configurações permitem controle granular sobre qual provedor de LLM e modelo são usados para tarefas específicas:

ADD_LINKS_PROVIDER: O provedor de LLM a ser usado para a operação process_content (adicionar links).
RESEARCH_PROVIDER: O provedor de LLM a ser usado para a operação research_summarize.
GENERATE_TITLE_PROVIDER: O provedor de LLM a ser usado para a operação generate_title.
TRANSLATE_PROVIDER: Provedor para translate_content.
SUMMARIZE_TO_MERMAID_PROVIDER: Provedor para summarize_as_mermaid.
EXTRACT_CONCEPTS_PROVIDER: Provedor para extract_concepts.
EXTRACT_ORIGINAL_TEXT_PROVIDER: Provedor para extract_original_text.
DIAGRAM_PROVIDER: Provedor para generate_diagram.
ADD_LINKS_MODEL: Modelo específico a ser usado para adicionar links (substitui o padrão do provedor se definido).
RESEARCH_MODEL: Modelo específico a ser usado para pesquisa (substitui o padrão do provedor se definido).
GENERATE_TITLE_MODEL: Modelo específico a ser usado para geração de títulos (substitui o padrão do provedor se definido).
TRANSLATE_MODEL, SUMMARIZE_TO_MERMAID_MODEL, EXTRACT_CONCEPTS_MODEL, EXTRACT_ORIGINAL_TEXT_MODEL, DIAGRAM_MODEL: Substituições de modelo específicas de tarefa.

Configurações de Pós-processamento

REMOVE_CODE_FENCES_ON_ADD_LINKS: Booleano para remover cercas de código do conteúdo após adicionar links.

Configurações de Idioma

LANGUAGE: O idioma padrão para processamento de conteúdo.
AVAILABLE_LANGUAGES: Uma lista de idiomas suportados.

Configurações de Prompts Personalizados

Estas configurações permitem habilitar e definir prompts personalizados para várias operações:

ENABLE_GLOBAL_CUSTOM_PROMPTS: Booleano para habilitar/desabilitar o uso de prompts personalizados globalmente.
CUSTOM_PROMPT_ADD_LINKS: String de prompt personalizado para a operação process_content (adicionar links).
CUSTOM_PROMPT_GENERATE_TITLE: String de prompt personalizado para a operação generate_title.
CUSTOM_PROMPT_RESEARCH_SUMMARIZE: String de prompt personalizado para a operação research_summarize.
CUSTOM_PROMPT_TRANSLATE: String de prompt personalizado para translate_content.
CUSTOM_PROMPT_SUMMARIZE_TO_MERMAID: String de prompt personalizado para summarize_as_mermaid.
CUSTOM_PROMPT_GENERATE_DIAGRAM: String de prompt personalizado para generate_diagram.
CUSTOM_PROMPT_EXTRACT_CONCEPTS: String de prompt personalizado para extract_concepts.
CUSTOM_PROMPT_EXTRACT_ORIGINAL_TEXT: String de prompt personalizado para extract_original_text.

Release (npm + PyPI)

Use este comando de uma linha para incrementar uma versão compartilhada e publicar npm e PyPI em sincronia:

npm run release:sync-publish -- 0.6.1

Execução de teste (sem publicação):

npm run release:sync-publish -- 0.6.1 --dry-run

Notas:

O comando atualiza a versão npm (package.json + package-lock.json) e sincroniza as versões do Python/servidor em setup.py, main.py e cli.js.
Certifique-se de que a autenticação npm esteja pronta (npm login ou NPM_TOKEN) e que a autenticação PyPI esteja pronta (~/.pypirc ou TWINE_USERNAME + TWINE_PASSWORD).
Ele compila os artefatos Python e executa twine check antes do upload.

Licença

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