Assistentes e agentes de IA
Usar a Mapit com IA
Duas formas de usar a Mapit com IA: perguntar a um assistente pela própria mota, ou pôr um agente de programação a escrever o código que a consulta.
Beta, gratuita por agora. O meu Mapit e o serviço por trás dele são uma beta: podem mudar ou deixar de funcionar, não têm garantia de disponibilidade e, por agora, a Mapit não os cobra. Não depender deles para emergências nem para recuperar uma mota roubada: para isso, usar a aplicação Mapit. Ver as condições da beta.
Perguntar a um assistente pela mota
O meu Mapit liga um assistente de IA à conta Mapit. Perguntar «Onde está a minha mota?», «Que trajetos fiz ontem?» ou «Quando termina a minha subscrição?». Iniciar sessão com a conta Mapit na página da Mapit e escolher o que o assistente pode ver. Ele nunca recebe a palavra-passe.
Plugin ou conector
O meu Mapit existe de duas formas. O plugin reúne o conector O meu Mapit e duas skills. O marketplace mapit-iot/ai-plugin (um repositório do GitHub) é adicionado no Claude Code e no Codex, mais abaixo. No claude.ai, um administrador da organização adiciona-o em Definições da organização > Plugins e skills > Marketplaces, a partir de uma cópia privada (ver claude.ai mais abaixo). Se o assistente não tiver plugins, adicionar antes o conector pelo respetivo URL, como no claude.ai e no ChatGPT mais abaixo.
claude.ai
Nas Definições, abrir Conectores e adicionar um conector personalizado chamado O meu Mapit com o URL https://api.mapit.me/mcp. Depois ligá-lo e iniciar sessão com a conta Mapit.
Os proprietários dos planos Team e Enterprise podem dar o plugin a toda a organização: nas Definições da organização, abrir Plugins e skills, depois Marketplaces, e adicionar o repositório do GitHub que contém uma cópia de mapit-iot/ai-plugin. A Anthropic só aceita aí repositórios privados ou internos, pelo que é preciso copiá-lo primeiro para um repositório privado da organização. Os restantes adicionam o conector como acima.
ChatGPT
Adicionar um conector personalizado (uma aplicação que usa MCP) chamado O meu Mapit com o URL https://api.mapit.me/mcp e iniciar sessão com a conta Mapit. O sítio onde estão os conectores personalizados no ChatGPT depende do plano e da versão da aplicação.
Claude Code
Instalar o plugin da Mapit a partir do marketplace mapit-iot/ai-plugin:
/plugin marketplace add mapit-iot/ai-plugin
/plugin install mapit@mapit Depois executar /mcp, escolher plugin:mapit:my-mapit e iniciar sessão. O plugin também adiciona duas skills que ajudam o assistente a responder a perguntas sobre a mota e a calcular totais dos trajetos.
OpenAI Codex
Instalar o plugin a partir do mesmo marketplace mapit-iot/ai-plugin:
codex plugin marketplace add mapit-iot/ai-plugin
codex plugin add mapit@mapit Depois, iniciar sessão com a conta Mapit na primeira utilização.
Qualquer outro cliente MCP
Adicionar um servidor MCP remoto com o URL https://api.mapit.me/mcp. Usar o transporte Streamable HTTP e início de sessão com OAuth: o cliente abre a página de início de sessão da Mapit, autoriza-o e ele guarda um token, nunca a palavra-passe.
https://api.mapit.me/mcp O que o assistente pode e não pode fazer
- Só leitura. Pode consultar a conta, os veículos, a subscrição, onde cada veículo comunicou pela última vez, e os trajetos e estatísticas de condução. Não pode alterar nada nem enviar comandos à mota.
- Localização e trajetos só se forem marcados. Na página de início de sessão escolhe-se se a localização e o histórico de trajetos são partilhados. Se não forem marcados, o assistente não os pode ver.
- Último dado comunicado, não em direto. Uma posição é o que o localizador enviou por último, e o assistente diz quando. Não pode seguir a mota em direto.
- Só a conta do cliente. Vê os veículos do cliente, tal como a aplicação Mapit os mostra.
- O controlo é do cliente. Ver e terminar cada ligação em login.mapit.me/connections. Aplica-se no pedido seguinte.
O Claude, o ChatGPT e os outros assistentes ligados desta forma estão na lista de aplicações aprovadas. A utilização é para fins pessoais e não comerciais, nos termos das condições de utilização da API e do aviso de privacidade da API.
Programar com um agente de IA
Dar estes endereços ao agente de programação. Cada página da documentação também está disponível em Markdown: acrescentar .md ao endereço. Os três ficheiros abaixo estão em inglês, tal como as instruções para o agente; as cópias em Markdown destas páginas estão em português.
https://developers.mapit.me/llms.txt: um índice de todas as páginas, com uma linha sobre cada uma.https://developers.mapit.me/llms-full.txt: toda a documentação num só ficheiro Markdown.https://developers.mapit.me/openapi.json: a descrição OpenAPI, com todos os endpoints, parâmetros e campos.
Instruções para o agente
Colar isto nas instruções do agente (por exemplo, AGENTS.md ou CLAUDE.md) ou no início de uma tarefa:
You are writing code against the Mapit API (beta).
Docs index: https://developers.mapit.me/llms.txt
All docs in one file: https://developers.mapit.me/llms-full.txt
OpenAPI spec: https://developers.mapit.me/openapi.json
- Base URL: https://api.mapit.me/v1
- Auth: send a personal key as "Authorization: Bearer $MAPIT_KEY". Read the key
from an environment variable. Never hard-code it, print it or log it.
- Rate limit: 30 requests a minute per key or access token, for the REST API and the MCP connector. Bursts above it may be tolerated, never rely on them. On 429, wait Retry-After seconds.
Poll /status at most once a minute. See https://developers.mapit.me/limits.md
- Every 200 answer has an ETag: send it back in If-None-Match. 304 means
nothing changed.
- Version 1 only gains fields: ignore fields you do not know.
- Ids and cursors are opaque: store them, never build or parse them.
Follow nextCursor until it is null.
- Positions are last reported, not live: show when (lastLocationAt).
- Location and routes need permission on the key: 403 means it lacks it.
- Read-only, except disconnecting apps and keys. Never call DELETE unless
the user asks.
- Personal, non-commercial use: the user's own vehicles only.
- Python: use the aiomapit package instead of raw HTTP. Python: aiomapit
Em Python, o caminho mais rápido é o aiomapit, o cliente assíncrono oficial da Mapit (Python 3.12 ou mais recente). Tem tipos, trata da paginação e é o que a integração do Home Assistant usa. Criar primeiro uma chave pessoal.
pip install aiomapit import asyncio, os
from aiomapit import MapitClient
async def main():
async with MapitClient(os.environ["MAPIT_KEY"]) as client:
async for status in client.iter_statuses():
if status.state:
print(status.vehicle_id, status.state.latitude, status.state.longitude)
asyncio.run(main()) Noutras linguagens, é possível gerar um cliente a partir da referência ou do ficheiro OpenAPI.
