Simplenote MCP Server

Um servidor para conectar e gerenciar suas notas do Simplenote dentro do Claude Desktop.

Documentação

Simplenote MCP Server

Um servidor MCP leve que integra o Simplenote com o Claude Desktop usando o MCP Python SDK.

Isso permite que o Claude Desktop interaja com suas notas do Simplenote como um backend de memória ou fonte de conteúdo.

Novidades

30 Ferramentas — Paridade Total com Bear + Diferenciais do Simplenote + Ferramentas de Companhia para Claude + Criptografia de Cofre

Cofre — criptografia de notas opcional no lado do cliente: O Simplenote não possui criptografia em repouso. create_note/update_note agora aceitam encrypt: true, e encrypt_note/decrypt_note convertem notas existentes — os corpos se tornam texto cifrado AES-256-GCM antes de chegarem à API do Simplenote. Consulte docs/security/encryption-design.md.

Recursos MCP e Prompts reforçados para o caso de uso de memória de trabalho:

Corrigido: list_resources/read_resource estavam descartando silenciosamente metadados de tags/datas/paginação por meio de campos não-schema — agora anexados através do campo de extensão _meta da especificação MCP, o mecanismo correto.
session-handoff MCP Prompt: estrutura o fluxo de trabalho de Continuidade de Sessão (get_or_create_note + add_text com um formato Status:/Next:/Blockers:) para transferência de contexto entre sessões.

Ferramentas de exclusão irreversível com proteções de segurança obrigatórias:

permanent_delete_note: Destruir permanentemente uma única nota; requer confirm=true; pré-visualização de simulação por padrão
empty_trash: Excluir permanentemente todas as notas na lixeira; padrão é dry_run=true (pré-visualização); requer dry_run=false E confirm=true
1334 testes passando, cobertura de 79%+, zero erros de linting/tipos

Consulte o CHANGELOG e ROADMAP.md para detalhes completos.

v1.17.0

Correção assíncrona de search_notes: Consultas booleanas AND não travam mais o servidor; a busca agora roda em um executor de pool de threads com timeout de 30 s
Pré-filtro de substring: buscar "test" agora retorna corretamente notas contendo "testing", "tested", etc.
Suíte de testes de integração com motor real adicionada; erro de importação em auxiliares de teste corrigido

v1.16.0

publish_note: Publicar uma nota em uma URL pública — exclusivo do Simplenote MCP; retorna public_url
unpublish_note: Remover uma nota do acesso público; sem efeito se já estiver não publicada

Consulte o CHANGELOG para detalhes completos.

🔧 Recursos

📝 Gerenciamento Completo de Notas: Ler, criar, atualizar e excluir notas do Simplenote
🔍 Busca Avançada: Operadores booleanos, correspondência de frases, filtros de tags e datas
⚡ Alto Desempenho: Cache em memória com sincronização em segundo plano
🔐 Autenticação Segura: Autenticação baseada em token via variáveis de ambiente
🔑 Criptografia de Cofre: Criptografia AES-256-GCM opcional no lado do cliente para notas sensíveis — o próprio Simplenote não possui criptografia em repouso
🧩 Compatível com MCP: Funciona com Claude Desktop e outros clientes MCP
🐳 Pronto para Docker: Containerização completa com builds em múltiplos estágios e endurecimento de segurança
📊 Monitoramento: Endpoints HTTP opcionais para saúde, prontidão e métricas
🧪 Testes Robustos: Suíte de testes abrangente com 1334 testes e integração contínua
🔒 Segurança Reforçada: Varredura de segurança regular com Bandit, pip-audit e verificações de dependências

🚀 Início Rápido

Pré-requisitos

Conta Simplenote (crie uma em simplenote.com)
Python 3.10+ (para instalações sem Docker) ou Docker

Opção 1: Docker (Recomendado)

A maneira mais rápida de começar é usando nossa imagem Docker pré-construída:

# Pull and run the latest image
docker run -d \
  --name simplenote-mcp \
  -e SIMPLENOTE_EMAIL=your.email@example.com \
  -e SIMPLENOTE_PASSWORD=your-password \
  -e MCP_TRANSPORT=http \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_AUTH_TOKEN=your-random-secret-token \
  -p 8000:8000 \
  docdyhr/simplenote-mcp-server:latest

MCP_HTTP_AUTH_TOKEN é obrigatório sempre que MCP_HTTP_HOST for algo diferente de 127.0.0.1/localhost — o servidor se recusa a iniciar caso contrário (veja a seção de Segurança abaixo). Sem MCP_TRANSPORT=http, o servidor roda por stdio por padrão e nada escuta na porta publicada.

Verificações de Saúde do Docker: o monitoramento de saúde é um endpoint HTTP separado da porta do protocolo MCP acima — está desativado por padrão e deve ser habilitado explicitamente com -e ENABLE_HTTP_ENDPOINT=true -e HTTP_HOST=0.0.0.0 -p 8080:8080 (o mapeamento -p do Docker encaminha para a interface de rede do contêiner, não para seu loopback, então HTTP_HOST deve ser 0.0.0.0 para que a porta publicada realmente o alcance — o padrão 127.0.0.1 só funciona se você estiver chamando esses endpoints de outro processo dentro do mesmo contêiner):

Saúde: http://localhost:8080/health
Prontidão: http://localhost:8080/ready
Métricas: http://localhost:8080/metrics (formato Prometheus)

O servidor se recusa a iniciar se HTTP_HOST for não-loopback e nenhum HTTP_ENDPOINT_AUTH_TOKEN estiver definido, pois esses endpoints estariam de outra forma acessíveis a qualquer pessoa que pudesse alcançar a porta. Defina um token de portador (verificado via Authorization: Bearer <token>, mesmo mecanismo do MCP_HTTP_AUTH_TOKEN acima) se precisar de um bind não-loopback — chamadores de loopback são sempre confiáveis independentemente, então isso nunca quebra uma verificação de saúde local. Prefira mantê-lo apenas em loopback e publicar com -p 127.0.0.1:8080:8080 em vez de -p 8080:8080 quando possível.

Ou use Docker Compose:

# Clone the repository for docker-compose.yml
git clone https://github.com/docdyhr/simplenote-mcp-server.git
cd simplenote-mcp-server

# Set environment variables
export SIMPLENOTE_EMAIL=your.email@example.com
export SIMPLENOTE_PASSWORD=your-password

# Run with Docker Compose
docker-compose up -d

Opção 2: Smithery (Instalação em um clique)

Instale automaticamente via Smithery:

npx -y @smithery/cli install @docdyhr/simplenote-mcp-server --client claude

Este método configura automaticamente o Claude Desktop com o servidor MCP.

Opção 3: Instalação Python Tradicional

git clone https://github.com/docdyhr/simplenote-mcp-server.git
cd simplenote-mcp-server
pip install -e .
simplenote-mcp-server

🗂 Mapa de Documentação e Arquivos

Comece com docs/DOCUMENTATION_GUIDE.md para um tour selecionado de documentação de usuário, desenvolvedor e operações, além de listas de verificação de manutenção.
Resumos históricos do projeto agora ficam em docs/archive/2025/, mantendo a raiz do repositório focada em roteiros e guias ativos.
Precisa de algo rápido? Execute rg "<topic>" docs/ ou vá para docs/index.md para o índice de conteúdo no estilo MkDocs.

🐳 Implantação Docker

Recursos do Contêiner

Builds em múltiplos estágios para tamanho de imagem otimizado
Endurecimento de segurança com usuário não-root e superfície de ataque mínima
Endpoints de monitoramento de saúde integrados
Limites de recursos e tratamento adequado de sinais
Suporte a volumes para dados persistentes

Usando Imagens Pré-construídas

A maneira mais fácil de usar o servidor é com nossas imagens Docker pré-construídas:

# Pull the latest image
docker pull docdyhr/simplenote-mcp-server:latest

# Run with Docker (see Quick Start above for the required MCP_HTTP_* env vars)
docker run -d \
  -e SIMPLENOTE_EMAIL=your.email@example.com \
  -e SIMPLENOTE_PASSWORD=your-password \
  -e MCP_TRANSPORT=http \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_AUTH_TOKEN=your-random-secret-token \
  -p 8000:8000 \
  docdyhr/simplenote-mcp-server:latest

# Or use Docker Compose (set MCP_HTTP_AUTH_TOKEN in your environment/.env first)
docker-compose up -d

Tags disponíveis:

latest - Última versão estável
v1.18.0 - Versão específica
main - Última build de desenvolvimento

Implantação em Produção

# Build and run the production container
docker-compose up -d

# Or build manually
docker build -t simplenote-mcp-server .
docker run -d \
  -e SIMPLENOTE_EMAIL=your.email@example.com \
  -e SIMPLENOTE_PASSWORD=your-password \
  -e MCP_TRANSPORT=http \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_AUTH_TOKEN=your-random-secret-token \
  -p 8000:8000 \
  simplenote-mcp-server

Desenvolvimento com Docker

# Use the development compose file for live code mounting
docker-compose -f docker-compose.dev.yml up

Recursos do Docker

Build em múltiplos estágios para tamanho de imagem otimizado (346MB)
Suporte multi-plataforma: linux/amd64 e linux/arm64
Endurecimento de segurança: Usuário não-root, sistema de arquivos somente leitura, sem novos privilégios
Verificações de saúde e políticas de reinicialização automática
Limites de recursos: 1 CPU, 512MB de memória
Registro: Volumes de log persistentes
Configuração baseada em ambiente
Pipeline CI/CD: Builds automatizados e publicação no Docker Hub
Varredura de segurança: Varredura de vulnerabilidades Trivy em todas as imagens
Assinatura de contêiner: Assinaturas Sigstore cosign para segurança da cadeia de suprimentos
Pronto para Kubernetes: Chart Helm de nível de produção com endurecimento de segurança
Atualizações automatizadas: Dependabot para dependências, fluxos de trabalho de versionamento automático
Monitoramento de saúde: Verificações de saúde contínuas e alertas
Notificações empresariais: Integração com Slack e e-mail para status de CI/CD

☸️ Implantação Kubernetes

Usando Helm (Recomendado)

Implante no Kubernetes com nosso chart Helm de nível de produção:

# Install from local chart
helm install my-simplenote ./helm/simplenote-mcp-server \
  --set simplenote.email="your-email@example.com" \
  --set simplenote.password="your-password"

# Or with external secrets (recommended for production)
helm install my-simplenote ./helm/simplenote-mcp-server \
  --set externalSecrets.enabled=true \
  --set externalSecrets.secretStore.name="vault-backend"

Recursos do Kubernetes

Endurecimento de segurança: Usuário não-root, sistema de arquivos somente leitura, capacidades removidas
Gerenciamento de recursos: Limites e solicitações de CPU/memória configurados
Auto-escalonamento: Suporte a Horizontal Pod Autoscaler
Verificações de saúde: Sondas de vivacidade e prontidão
Segredos externos: Integração com gerenciamento de segredos externo
Pronto para service mesh: Compatível com Istio e outros service meshes

Configuração de Produção

# values.yaml for production
replicaCount: 3
autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
resources:
  limits:
    cpu: 1000m
    memory: 512Mi
  requests:
    cpu: 500m
    memory: 256Mi

⚙️ Configuração

Variáveis de Ambiente

Variável	Obrigatória	Padrão	Descrição
`SIMPLENOTE_EMAIL`	Sim	-	E-mail da sua conta Simplenote
`SIMPLENOTE_PASSWORD`	Sim	-	Senha da sua conta Simplenote
`SYNC_INTERVAL_SECONDS`	Não	120	Intervalo de sincronização de cache em segundos
`CACHE_MAX_SIZE`	Não	10000	Máximo de notas mantidas em memória — defina ≥ seu total de notas
`LOG_LEVEL`	Não	INFO	Nível de registro (DEBUG, INFO, WARNING, ERROR)
`SIMPLENOTE_OFFLINE_MODE`	Não	false	Ignorar chamadas de API; usado para testes sem credenciais
`MCP_TRANSPORT`	Não	stdio	`stdio` ou `http` — o transporte do protocolo MCP
`MCP_HTTP_HOST`	Não	127.0.0.1	Host de bind quando `MCP_TRANSPORT=http`
`MCP_HTTP_AUTH_TOKEN`	Condicional	-	Token de portador; obrigatório se `MCP_HTTP_HOST` for não-loopback
`MCP_HTTP_ALLOWED_HOSTS`	Não	-	Lista de permissões separada por vírgulas para proteção contra DNS-rebinding
`MCP_HTTP_ALLOWED_ORIGINS`	Não	-	Lista de permissões de Origin separada por vírgulas (usada com o acima)
`ENABLE_HTTP_ENDPOINT`	Não	false	Habilitar o servidor separado `/health`, `/ready`, `/metrics`
`HTTP_HOST`	Não	127.0.0.1	Host de bind para o endpoint de monitoramento acima
`HTTP_PORT`	Não	8080	Porta para o endpoint de monitoramento acima
`HTTP_ENDPOINT_AUTH_TOKEN`	Condicional	-	Token de portador; obrigatório se `HTTP_HOST` for não-loopback

Integração com Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "simplenote": {
      "description": "Access and manage your Simplenote notes",
      "command": "simplenote-mcp-server",
      "env": {
        "SIMPLENOTE_EMAIL": "your.email@example.com",
        "SIMPLENOTE_PASSWORD": "your-password",
        "CACHE_MAX_SIZE": "10000"
      }
    }
  }
}

🔍 Busca Avançada

Busca poderosa com lógica booleana e filtros:

# Boolean operators
project AND meeting AND NOT cancelled

# Phrase matching
"action items" AND project

# Tag filtering
meeting tag:work tag:important

# Date ranges
project from:2023-01-01 to:2023-12-31

# Combined query
"status update" AND project tag:work from:2023-01-01 NOT cancelled

🛠️ Ferramentas Disponíveis

Ferramenta	Descrição	Parâmetros
`create_note`	Criar uma nova nota	`content`, `tags` (opcional)
`update_note`	Substituir todo o conteúdo da nota (destrutivo)	`note_id`, `content`, `tags` (opcional)
`delete_note`	Exclusão suave: mover nota para a Lixeira	`note_id`
`restore_note`	Restaurar uma nota — movê-la de volta da Lixeira	`note_id`
`permanent_delete_note`	Destruir irreversivelmente uma única nota (requer `confirm=true`)	`note_id`, `confirm`
`empty_trash`	Excluir permanentemente todas as notas na lixeira (simulação por padrão)	`dry_run` (padrão `true`), `confirm` (padrão `false`)
`get_note`	Obter uma nota por ID com conteúdo completo e metadados	`note_id`
`add_text`	Adicionar texto ao final ou início sem sobrescrever	`note_id`, `text`, `position` (`"end"` \| `"beginning"`)
`search_notes`	Pesquisa de texto completo com filtros e paginação	`query`, `limit`, `offset`, `tags`, `from_date`, `to_date`, `created_after`, `modified_after`, `pinned`, `fuzzy`, `sort_by`
`add_tags`	Adicionar tags a uma nota	`note_id`, `tags`
`remove_tags`	Remover tags específicas de uma nota	`note_id`, `tags`
`replace_tags`	Substituir todas as tags de uma nota	`note_id`, `tags`
`list_tags`	Listar todas as tags com contagem de notas	`sort_by` (`"alpha"` \| `"count"`)
`rename_tag`	Renomear uma tag em todas as notas atomicamente	`old_tag`, `new_tag`, `dry_run` (opcional)
`get_note_versions`	Listar histórico de versões de uma nota	`note_id`
`restore_version`	Reverter uma nota para uma versão anterior	`note_id`, `version_number`
`get_or_create_note`	Busca atômica ou criação por título	`title`, `tags` (opcional), `default_content` (opcional)
`append_to_daily_note`	Adicionar uma entrada com data e hora à nota de hoje	`text`, `tags` (opcional)
`replace_section`	Substituir uma seção Markdown sem tocar nas demais	`note_id`, `header`, `content`
`find_untagged_notes`	Encontrar notas sem tags	`limit` (opcional)
`bulk_tag`	Aplicar tags a múltiplas notas em uma única chamada	`note_ids`, `tags`
`export_notes`	Exportar notas para Markdown ou JSON	`format`, `tags` (opcional), `query` (opcional)
`find_and_merge_duplicates`	Detectar e mesclar notas duplicadas	`dry_run` (opcional), `similarity_threshold` (opcional)
`get_server_info`	Versão do servidor, autor e informações de depuração em tempo de execução	(sem parâmetros)

📊 Desempenho e Cache

Cache em memória com sincronização em segundo plano
Suporte a paginação para grandes coleções de notas
Consultas indexadas para tags e conteúdo
Cache de resultados de consulta para pesquisas repetidas
Uso otimizado da API com chamadas mínimas ao Simplenote

🎯 Melhorias Recentes

✅ Janeiro de 2025 - Desempenho e Qualidade de Código

Correção de Bug Crítico:

Corrigido timeout do Claude Desktop - Tempo de inicialização reduzido de 55+ segundos para < 1 segundo (melhoria de 98%)
Implementada execução em pool de threads para chamadas bloqueantes da API do Simplenote
Inicialização de cache verdadeiramente não bloqueante com carregamento em segundo plano
Resolvido anyio.BrokenResourceError durante o desligamento

Refatoração de Código - Fase 1 Concluída:

Complexidade do módulo de cache reduzida: 5 funções de alta complexidade (CC >= 15) → 0 (redução de 100%)
Manutenibilidade melhorada: MI do cache de 12,7 → 16,2 (+28%)
Extraídos 23 métodos auxiliares para melhor organização do código
Todos os 670 testes passando com cobertura de cache de 67% mantida
Consulte REFACTORING_PHASE1_COMPLETE.md para detalhes

Melhorias na Documentação:

Adicionado CHANGELOG.md abrangente com histórico completo de versões
Criado TESTING_CLAUDE_DESKTOP.md para guia de testes do usuário
Adicionadas ferramentas de análise de complexidade de código (check_complexity.py)
Documentado o plano de refatoração e relatórios de conclusão

Ferramentas de Qualidade:

Integrado Radon para análise automatizada de complexidade
Métricas de base: 22 funções com CC >= 15 (reduzido de 28)
Índice médio de manutenibilidade: 57,9 (mantido)
Zero erros de diagnóstico, todos os portões de qualidade aprovados

✅ Setembro de 2025 - Melhorias de Qualidade e Confiabilidade

✅ Melhorias de Qualidade e Confiabilidade

Estabilização da Suíte de Testes:

Corrigidos problemas de isolamento de testes que causavam falhas intermitentes
Melhorada a limpeza de testes com tratamento adequado de timeout
Aprimorado o gerenciamento de fixtures para maior confiabilidade dos testes
Resultados de teste consistentes em execuções individuais e em suíte

Otimização do Pipeline CI/CD:

Consolidados 28 workflows para 16 workflows ativos
Implementado workflow unificado de monitoramento combinando verificações de segurança, saúde e badges
Melhorado o relatório de cobertura de testes com base realista de 15,6%
Aprimorada a validação de build Docker e varredura de segurança

Melhorias na Qualidade do Código:

Todos os lintings (Ruff), formatação e verificação de tipos (MyPy) agora passam consistentemente
Zero vulnerabilidades de segurança de alta gravidade (verificado com Bandit, pip-audit, safety)
Formatação de código padronizada e configuração de hooks de pré-commit
Tratamento de erros aprimorado e mensagens de erro voltadas ao usuário

🔧 Experiência do Desenvolvedor

Testes Melhorados:

724 testes abrangentes cobrindo funcionalidades principais
Fixtures com escopo de função para melhor isolamento de testes
Base de cobertura realista estabelecida (15,6%)
Execução de testes simplificada com limpeza adequada

Documentação Aprimorada:

Atualizados guias de implantação com configuração Docker atual
Melhorada a documentação do endpoint de monitoramento de saúde
Adicionados guias de solução de problemas para problemas comuns
Documentação de status atual e roadmap

Melhorias no Container:

Builds Docker multi-estágio para tamanho de imagem otimizado
Endpoints integrados de monitoramento de saúde (/health, /ready, /metrics)
Endurecimento de segurança aprimorado com usuário não-root
Tratamento de sinais e desligamento gracioso melhorados

🧪 Testes e Avaliação

Avaliações MCP ✅

Status: ✅ FUNCIONANDO - Integração completa com mcp-evals usando wrapper TypeScript!

Este projeto inclui avaliações abrangentes usando mcp-evals para garantir confiabilidade e desempenho:

# Setup evaluation environment
npm install
npm run validate:evals

# Run evaluation suites
npm run eval:smoke          # Quick smoke tests (2-3 minutes) ✅ VERIFIED
npm run eval:basic          # Standard evaluations (5-10 minutes)
npm run eval:comprehensive  # Full evaluation suite (15-30 minutes)

Resultados de Testes Mais Recentes: 4/5 testes passando excelentemente (média 4,1/5):

Inicialização do Servidor: 4,6/5 ⭐ (Excelente)
Autenticação: 4,0/5 ⭐ (Bom)
Operações de Notas: 3,8/5 ⭐ (Bom)
Pesquisa: 5,0/5 ⭐ (Perfeito)
Tratamento de Erros: 1,4/5 ⚠️ (Precisa de melhorias)

Tipos de Avaliação

Testes de Fumaça: Validação de funcionalidade básica
Operações CRUD: Criação, leitura, atualização e exclusão de notas
Pesquisa e Filtragem: Pesquisa booleana, filtragem por tags, intervalos de datas
Tratamento de Erros: Autenticação, problemas de rede, casos extremos
Desempenho: Grandes conjuntos de dados, operações concorrentes
Segurança: Validação de entrada, aplicação de autenticação

Testes Automatizados

As avaliações são executadas automaticamente em:

Pull Requests: Testes de fumaça + básicos
Releases: Suíte de avaliação abrangente
Acionamento Manual: Matriz de testes completa com relatórios detalhados

As avaliações usam modelos GPT da OpenAI para avaliar:

Precisão: Correção das respostas
Completude: Minuciosidade dos resultados
Relevância: Adequação das respostas
Clareza: Legibilidade das respostas
Desempenho: Eficiência das operações

📁 Consulte evals/README.md para documentação detalhada da avaliação.

Testes Tradicionais

# Python unit tests
pytest

# Code quality checks
ruff check .
mypy simplenote_mcp

🛡️ Segurança

Autenticação baseada em token via variáveis de ambiente
Sem credenciais codificadas em imagens Docker
Containers com segurança reforçada com usuários não-root
Sistema de arquivos somente leitura em containers de produção
Limites de recursos para prevenir abuso
Transporte HTTP MCP é fail-closed por padrão: MCP_TRANSPORT=http recusa iniciar em qualquer MCP_HTTP_HOST não-loopback, a menos que MCP_HTTP_AUTH_TOKEN esteja definido (um segredo bearer compartilhado, verificado via comparação em tempo constante). Binds loopback (127.0.0.1/localhost) funcionam sem token, correspondendo ao nível de confiança de processo local do stdio. Defina MCP_HTTP_ALLOWED_HOSTS/MCP_HTTP_ALLOWED_ORIGINS (separados por vírgula) para habilitar proteção contra rebinding de DNS para binds não-loopback. Isso é destinado a redes privadas (atrás de VPN/Tailscale/túnel SSH) — um token compartilhado estático não possui nenhuma das propriedades de revogação/auditoria/exclusão do OAuth, então evite expô-lo diretamente à internet pública mesmo com um token definido.

🚨 Solução de Problemas

Problemas Comuns

Problemas de Autenticação:

Verifique se SIMPLENOTE_EMAIL e SIMPLENOTE_PASSWORD estão definidos corretamente
Verifique se há erros de digitação nas credenciais

Problemas com Docker:

# Check container logs
docker-compose logs

# Restart services
docker-compose restart

# Rebuild if needed
docker-compose up --build

Conexão com Claude Desktop:

# Verify tools are available
./simplenote_mcp/scripts/verify_tools.sh

# Monitor logs
./simplenote_mcp/scripts/watch_logs.sh

Comandos de Diagnóstico

# Test connectivity
python simplenote_mcp/tests/test_mcp_client.py

# Check server status
./simplenote_mcp/scripts/check_server_pid.sh

# Clean up and restart
./simplenote_mcp/scripts/cleanup_servers.sh

📚 Desenvolvimento

Configuração Rápida com mcp-evals

# One-command setup including evaluations
./setup-dev-env-with-evals.sh

# Or manual setup
git clone https://github.com/docdyhr/simplenote-mcp-server.git
cd simplenote-mcp-server
pip install -e ".[dev,test]"
npm install  # For mcp-evals

Desenvolvimento Local

# Run the server
python simplenote_mcp_server.py

# Run Python tests
pytest

# Run mcp-evals
npm run eval:smoke    # Quick validation
npm run eval:basic    # Standard tests
npm run eval:all      # Full test suite

# Code quality
ruff check .
ruff format .
mypy simplenote_mcp

Ambiente de Desenvolvimento

O script de configuração cria:

Ambiente de desenvolvimento Python com todas as dependências
Ambiente Node.js para mcp-evals
Arquivos de configuração de exemplo
Hooks de pre-commit
Validação para todos os arquivos de avaliação

Estratégia de Testes

Testes Unitários: pytest tradicional em Python para a lógica central
Testes de Integração: Testes de conformidade com o protocolo MCP
Testes de Fumaça: Validação rápida da funcionalidade básica
Testes de Avaliação: Avaliação baseada em LLM do uso em cenários reais
Testes de Desempenho: Testes de carga e estresse

Executando Avaliações MCP

Método Docker (Recomendado)

Devido a possíveis problemas de permissão com tsx, recomendamos executar as avaliações MCP no Docker:

# Run smoke tests
./scripts/run-evals-docker.sh smoke

# Run basic evaluations
./scripts/run-evals-docker.sh basic

# Run comprehensive evaluations
./scripts/run-evals-docker.sh comprehensive

# Run all evaluations
./scripts/run-evals-docker.sh all

Método Direto (se as permissões permitirem)

npm run eval:smoke
npm run eval:basic
npm run eval:comprehensive
npm run eval:all

Desenvolvimento com Docker

# Development with live code reload
docker-compose -f docker-compose.dev.yml up

# Build and test
docker build -t simplenote-mcp-server:test .
docker run --rm simplenote-mcp-server:test --help

🤝 Contribuindo

Contribuições são bem-vindas! Por favor, leia CONTRIBUTING.md para as diretrizes.

📄 Licença

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

🔗 Projetos Relacionados

⭐ Apoie o Projeto

Se você achar este projeto útil, considere dar uma estrela no GitHub! Seu apoio ajuda a:

🚀 Aumentar a visibilidade para outros desenvolvedores que possam se beneficiar desta ferramenta
💪 Motivar o desenvolvimento contínuo e a manutenção
📈 Construir comunidade em torno do ecossistema Model Context Protocol
🛡️ Validar confiança por meio do engajamento da comunidade

⭐ Dê uma estrela a este repositório — leva apenas um clique e significa muito!