convez.ai
MCP ServerIntegração & APIsIntermediário
lenaxia

HortusFox MCP Server

lenaxia/hortusfox-mcp

Integre gestão de plantas HortusFox nativamente com Claude

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que expõe a API REST do HortusFox (sistema de gestão de plantas) para clientes LLM. Oferece 37 ferramentas distribuídas em 7 domínios (plantas, localizações, tarefas, inventário, calendário, chat, backup) com suporte a recursos multimídia, modo somente leitura configurável e proteção contra taxa de requisições.

Instalação

$npx convez-ai lenaxia/hortusfox-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Assistentes de cuidado de plantas com consultas a banco de dados pessoal
  • Automação de logging e atualização de plantas via conversação natural
  • Gerenciamento de tarefas e calendário de manutenção integrado ao chat

Veredito

MCP server robusto e bem testado (99%+ cobertura) para HortusFox, com configuração segura padrão (read-only) e controle fino via variáveis de ambiente. Ideal para quem mantém HortusFox e quer estender capacidades com IA conversacional.

README

A tradução para o português deste README ainda está na fila.

hortusfox-mcp

An MCP (Model Context Protocol) server that exposes the HortusFox REST API to LLM clients.

Features

  • 37 tools across 7 domains: plants, locations, tasks, inventory, calendar, chat, backup
  • 11 resources (plant photos, logs, gallery) via hortusfox:// URIs
  • Read-only mode by default; writes gated behind HORTUSFOX_ENABLE_WRITES
  • Backup tools gated behind HORTUSFOX_ENABLE_BACKUP
  • Confirm-before-delete pattern on all remove operations
  • Token-bucket rate limiter to protect the upstream API
  • 257 tests (unit + integration + e2e + live), 99%+ statement coverage

Quick Start

npm install
npm run build

Configure your MCP client (e.g. Claude Desktop) with:

{
  "mcpServers": {
    "hortusfox": {
      "command": "node",
      "args": ["/path/to/hortusfox-mcp/dist/index.js"],
      "env": {
        "HORTUSFOX_BASE_URL": "http://your-hortusfox-install",
        "HORTUSFOX_API_TOKEN": "your-api-token"
      }
    }
  }
}

Configuration

All settings are via environment variables:

VariableRequiredDefaultDescription
HORTUSFOX_BASE_URLyes—Base URL of your HortusFox instance (e.g. http://localhost:8080)
HORTUSFOX_API_TOKENyes—API token generated in HortusFox admin panel
HORTUSFOX_ENABLE_WRITESnotrueSet false for read-only mode (11 tools)
HORTUSFOX_ENABLE_BACKUPnofalseSet true to enable backup export/import tools
HORTUSFOX_VERIFY_TLSnotrueSet false to skip TLS certificate verification
HORTUSFOX_TIMEOUT_MSno10000Request timeout in milliseconds
HORTUSFOX_MAX_RATE_PER_SECno10Max requests per second to the upstream API

Tool Reference

Plants (18 tools)

ToolModeDescription
plants_listreadList plants with optional filters (location, limit, sort)
plants_searchreadSearch plants by expression
plants_getreadGet full plant detail
plants_log_fetchreadFetch plant log entries
plants_gallery_listreadList gallery photos for a plant
plants_addwriteAdd a new plant
plants_update_attributewriteUpdate a single attribute (partial update)
plants_removewriteRemove a plant (confirm required)
plants_photo_setwriteSet plant photo from URL
plants_gallery_addwriteAdd gallery photo from URL
plants_gallery_editwriteEdit gallery item label (partial update)
plants_gallery_removewriteRemove gallery item (confirm required)
plants_attributes_addwriteAdd custom attribute to a plant
plants_attributes_editwriteEdit custom attribute (full-field — see audit note)
plants_attributes_removewriteRemove custom attribute (confirm required)
plants_log_addwriteAdd a log entry
plants_log_editwriteEdit a log entry (partial update)
plants_log_removewriteRemove a log entry (confirm required)

Locations (2 tools, read-only)

ToolDescription
locations_listList all locations
locations_infoGet details for a single location

Tasks (5 tools)

ToolModeDescription
tasks_listreadList open or completed tasks
tasks_addwriteAdd a new task
tasks_editwriteEdit a task (partial update; set recurring_scope with recurring_time)
tasks_completewriteMark a task done
tasks_removewriteRemove a task (confirm required)

Inventory (6 tools)

ToolModeDescription
inventory_listreadList all inventory items
inventory_addwriteAdd an item (group token required)
inventory_editwriteEdit an item (full-field — see audit note)
inventory_incrementwriteIncrement amount by 1
inventory_decrementwriteDecrement amount by 1
inventory_removewriteRemove an item (confirm required)

Calendar (4 tools)

ToolModeDescription
calendar_listreadList calendar entries in a date range
calendar_addwriteAdd a calendar entry
calendar_editwriteEdit an entry (full-field — see audit note)
calendar_removewriteRemove an entry (confirm required)

Chat (2 tools)

ToolModeDescription
chat_listreadFetch recent chat messages
chat_postwritePost a message

Backup (2 tools, HORTUSFOX_ENABLE_BACKUP=true)

ToolDescription
backup_exportExport selected data types to a backup file
backup_importImport from backup (confirm required, destructive)

Resources

URIDescription
hortusfox://plant/{id}/photoPlant's primary photo
hortusfox://plant/{id}/logPlant's log entries
hortusfox://plant/{id}/galleryPlant's gallery photos

Upstream API Quirks

Some HortusFox edit endpoints clobber null fields — they UPDATE all columns unconditionally rather than skipping omitted parameters. This server mitigates by making all affected fields required on the corresponding MCP tools:

  • plants_attributes_edit — requires datatype + content + label
  • inventory_edit — requires name, description, tags, location, amount, group
  • calendar_edit — requires name, date_from

Additionally, tasks_edit has a subtle issue: omitting recurring_scope defaults it to "hours" server-side, silently overwriting an existing scope. Always set recurring_scope when passing recurring_time.

Development

npm run typecheck     # type-check without emitting
npm test              # run all unit + integration + e2e tests
npm run test:live     # run live tests (requires HortusFox running locally)
npm run coverage      # generate coverage report

License

MIT

Ver o original no GitHub

Bom para

Relacionados