MapitProgramadores Beta mapit.me ↗

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

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.

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.