Evlek MCP Server

MCP de propriedade nativa de IA para o Chipre do Norte (KKTC) — 9 ferramentas, dados ao vivo do evlek.app, hospedado, sem necessidade de autenticação.

GitHub

Documentação

Servidor Evlek MCP

Descoberta de imóveis com tecnologia de IA para o Norte de Chipre (KKTC). Construído sobre o Model Context Protocol — funciona no Claude, ChatGPT, Gemini, Cursor e em qualquer cliente compatível com MCP.

O servidor Evlek MCP dá aos agentes de IA acesso estruturado e em tempo real aos dados de imóveis do Norte de Chipre — pesquise anúncios ativos, compare cidades e distritos e acompanhe o índice de preços. Todos os dados são obtidos ao vivo de evlek.app. A Evlek não oferece estimativa de rendimento de aluguel ou retorno de investimento: os valores são apenas fatos descritivos de preço pedido, nunca uma avaliação, previsão ou recomendação. Ferramentas de título de propriedade (koçan) e procedimentos legais estão deliberadamente fora da superfície: essa taxonomia não passou por uma auditoria jurídica independente do KKTC.

Escopo da licença

Este repositório é licenciado sob MIT para o manifesto público, documentação, exemplos e clientes de referência aqui contidos. O serviço hospedado Evlek, o aplicativo web evlek.app, os aplicativos móveis, o banco de dados de anúncios, os prompts de IA, a lógica de negócios, os ativos de marca, o nome, o logotipo e o trade dress permanecem proprietários e não são licenciados sob MIT. Consulte LICENSE para detalhes.

Por que Evlek MCP

Prioridade em IA. Construído para fluxos de trabalho agênticos desde o primeiro dia — não adaptado de uma API de anúncios legada.
Multilíngue. Respostas em TR, EN, RU, DE, AR: passe locale (ou escreva a consulta search nesse idioma) e o texto, os nomes de comodidades, os formatos de números e os links o acompanham. Nomes de lugares são resolvidos em qualquer um dos cinco idiomas.
Anúncios com verificação. A Evlek apresenta contexto de verificação de anúncios e contas quando disponível, e o MCP omite campos de contato para preservar o funil de revelação/contato da Evlek.
Feito para a região. Otimizado para as 6 cidades do Norte de Chipre (Lefkoşa, Girne, Gazimağusa, İskele, Güzelyurt, Lefke) e mais de 100 distritos.
Nível de produção. Alinhado ao OWASP MCP Top 10 — validação de entrada com Zod, sanitização de saída, limite de taxa (60/min/IP, 500/min global), observabilidade com Sentry.

Início rápido

Clientes com capacidade remota (preferido)

A maioria dos clientes MCP modernos (Claude, Cursor, VS Code) conecta-se diretamente ao endpoint HTTP Streamable — sem necessidade de ponte local:

{
  "mcpServers": {
    "evlek": {
      "url": "https://evlek.app/api/mcp"
    }
  }
}

ChatGPT (conector + Deep Research)

Adicione https://evlek.app/api/mcp como um conector personalizado. A Evlek expõe ferramentas search e fetch compatíveis com OpenAI, portanto funciona em conectores ChatGPT e Deep Research além do modo de desenvolvedor.

Claude Desktop (ponte stdio legada)

Se o seu cliente suporta apenas servidores stdio, use a ponte mcp-remote fixada. Adicione isto a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "evlek": {
      "command": "npx",
      "args": ["-y", "mcp-remote@0.1.16", "https://evlek.app/api/mcp"]
    }
  }
}

Reinicie o Claude Desktop. O servidor "evlek" aparece na lista de ferramentas.

MCP Inspector (teste antes de instalar)

npx @modelcontextprotocol/inspector https://evlek.app/api/mcp

API direta (cURL)

curl -X POST https://evlek.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Mais configurações: examples/

Servidor stdio local (este repositório)

Este repositório também é um servidor MCP executável. Ele responde a initialize / tools/list inteiramente localmente a partir do contrato de ferramentas incorporado (tools.json) e busca dados ao vivo da API de dados Evlek quando uma ferramenta é chamada. Ele implementa apenas ferramentas — não declara a capacidade resources ou prompts, portanto resources/list e prompts/list retornam um erro MCP normal de "método não encontrado" nesta ponte; essas primitivas (veja abaixo) são exclusivas do endpoint hospedado, acessíveis via URL HTTP Streamable acima. Ele também fala qualquer versão do protocolo MCP que a @modelcontextprotocol/sdk fixada suporta durante initialize (atualmente 2025-11-25), não necessariamente o 2026-07-28 do endpoint hospedado — os esquemas de ferramentas são idênticos de qualquer forma.

npx github:Evlek/evlek-mcp        # or: npm install && npm start

{
  "mcpServers": {
    "evlek": {
      "command": "npx",
      "args": ["-y", "github:Evlek/evlek-mcp"]
    }
  }
}

Teste rápido (inicia o servidor e fala MCP real via stdio):

npm test              # live: initialize + tools/list + a real tools/call
OFFLINE=1 npm test    # offline: introspection works with zero network

Ferramentas disponíveis

8 ferramentas · protocolo 2026-07-28 · Streamable HTTP JSON-RPC 2.0

Ferramenta	Título	Descrição
`search_listings`	Pesquisar anúncios de imóveis no Norte de Chipre	Use quando o usuário quiser encontrar ou ver anúncios de imóveis; os resultados são mostrados com fotos reais no widget Evlek. Pesquise anúncios ativos da Evlek de venda e aluguel de longo prazo no Norte de Chipre (KKTC/TRNC; preços em GBP, salvo se uma moeda for fornecida; 2+1 significa 2 quartos) com filtros estruturados: transação, cidade, distrito, tipo de imóvel, quartos, preço, áreas, comodidades, universidade próxima. Passe o idioma do usuário como `locale` (tr\|en\|ru\|de\|ar): o texto, os nomes de comodidades, os formatos de números e os links o acompanham. Retorna no máximo 10 anúncios por chamada, cada um como uma linha legível (tipo, local, preço, quartos, área, uma frase determinística, notas de dados, link canônico) além de um cartão estruturado; continue com o `nextCursor` de um grupo. Sem `transaction`, anúncios de venda e aluguel vêm como dois grupos separados, cada um com seu próprio cursor que só é válido junto com a transação daquele grupo. Nomes de lugares em qualquer idioma são resolvidos; um lugar desconhecido retorna sugestões em vez de resultados. Uma comodidade que não pode ser filtrada é informada como não aplicada. Para um único anúncio, use `get_listing`. Retorna apenas preço pedido anunciado e fatos do anúncio: não é avaliação, verificação de alegações específicas do imóvel, previsão, classificação ou recomendação.
`search`	Pesquisar anúncios de imóveis Evlek	Use apenas para pesquisa e consultas de citação (deep research). Para mostrar anúncios ao usuário, use search_listings. Pesquise anúncios ativos de imóveis no Norte de Chipre (KKTC/TRNC) na Evlek com uma consulta de texto livre em turco, inglês, russo, alemão ou árabe. Retorna anúncios correspondentes como id/título/url para a ferramenta de busca, mais recentes primeiro (venda e aluguel como dois grupos quando a consulta não nomeia nenhum). O idioma da resposta segue o idioma da consulta. Mesmos dados de search_listings: esta forma fixa existe para o contrato do conector ChatGPT/OpenAI. Use quando: o chamador tem apenas uma consulta de texto livre ("apartamento 2+1 em Kyrenia abaixo de 150000 libras", "EVL-100464"). Não use para: filtros estruturados, paginação ou outro idioma de resposta: use search_listings.
`fetch`	Buscar detalhes completos de um anúncio Evlek	Busque os detalhes completos de um anúncio Evlek: título, preço, localização, quartos, áreas, comodidades, notas de qualidade de dados e o link canônico. O id é o id do anúncio (UUID) de um resultado de pesquisa, um número de anúncio como EVL-100464 ou um link de anúncio evlek.app; o idioma da resposta segue o link (inglês caso contrário). Um anúncio que não está disponível (não existe, não é público ou foi removido) sempre recebe a mesma resposta. Mesmos dados de get_listing: esta forma fixa apenas com id existe para o contrato do conector ChatGPT/OpenAI. Use quando: um id de pesquisa é conhecido. Não use para: descoberta (use search primeiro) ou outro idioma de resposta (use get_listing).
`get_listing`	Obter um anúncio Evlek	Obtenha os detalhes completos de UM anúncio Evlek público (venda ou aluguel de longo prazo) no idioma do usuário. `ref` é o id do anúncio (UUID), o número do anúncio (EVL-100464 ou apenas 100464) ou um link de anúncio evlek.app em qualquer idioma. Retorna o preço, quartos, banheiros, área construída e área do terreno (sempre separadas), a localização aproximada, características, o nome do escritório, datas, notas de qualidade de dados, fotos com legendas quando existem, imagens de virtual staging com IA antes/depois quando o escritório as aprovou (sempre rotuladas como geradas por IA) e o link canônico. Detalhes de contato nunca são incluídos: envie o usuário para o link. Um anúncio desconhecido ou não mais público responde found:false com código NOT_FOUND (isso não é um erro). Passe o idioma do usuário como `locale` (tr, en, ru, de ou ar).
`compare_listings`	Comparar anúncios Evlek	Compare de 2 a 4 anúncios Evlek públicos lado a lado no idioma do usuário: preço, preço por m² (apenas quando a área construída é confiável), quartos, banheiros, área construída e área do terreno (sempre separadas), localização, mobília, características principais e notas de qualidade de dados, além de alguns destaques descritivos (menor preço, maior área interna, anunciado mais recentemente). `ids` aceita ids de anúncios (UUID), números de anúncios (EVL-100464) ou links de anúncios evlek.app, em qualquer combinação; a ordem fornecida é mantida. Anúncios de venda e aluguel nunca são classificados entre si: uma solicitação mista é mostrada em dois grupos com um aviso. Uma referência desconhecida ou não mais pública é listada em `missingIds` com código NOT_FOUND (isso não é um erro). Apenas fatos descritivos: sem avaliação e sem recomendação. Passe o idioma do usuário como `locale` (tr, en, ru, de ou ar).
`market_stats`	Estatísticas de mercado do Norte de Chipre	Estatísticas de mercado para o Norte de Chipre a partir de preços pedidos de anúncios públicos ativos (não vendas, avaliações ou previsões). Sem cidade = a ilha por cidade; uma cidade = seus distritos; várias = lado a lado; cidade + distrito = um perfil de distrito. Venda e aluguel são relatados separadamente. Cada valor tem activeCount (anúncios públicos no escopo) e sampleCount (a amostra limpa por trás da estatística); abaixo de 10 anúncios amostrados, é omitido. Passe o locale.
`list_locations`	Listar locais Evlek	Liste os lugares que a Evlek conhece no Norte de Chipre (6 cidades, distritos, vilarejos, subáreas, pontos de referência, a região de Karpaz) com suas contagens públicas de anúncios de venda e aluguel de longo prazo. Chame primeiro quando não tiver certeza de como um lugar é escrito: cada nome e id retornado é aceito pelas outras ferramentas. Passe `city` (qualquer grafia ou idioma) para um lugar em detalhes. Nomes são em turco ou latim; grafias em russo, alemão e árabe são aceitas como entrada, mas não listadas.
`convert_currency`	Conversão de moeda (GBP/EUR/USD/TRY)	Converte um valor entre GBP, EUR, USD e TRY com as taxas de câmbio que a Evlek armazena (atualizadas diariamente) e retorna todos os quatro equivalentes. Apenas conversão de moeda: sem plano de pagamento, depósito ou cronograma de parcelas, imposto, taxa ou estimativa de custo de aquisição, sem aconselhamento. Taxas com mais de 24 horas são sinalizadas como desatualizadas; além de 72 horas (ou quando nenhuma está armazenada) nenhuma conversão é produzida (FX_UNAVAILABLE).

Toda ferramenta declara annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false } — toda a superfície é somente leitura.

Widgets interativos (MCP Apps / SEP-1865)

Cinco ferramentas adicionalmente vinculam uma visualização HTML em sandbox (_meta.ui.resourceUri) que hosts com capacidade MCP Apps (Claude web/desktop) renderizam inline na conversa:

Ferramenta	Widget	O que você obtém
`search_listings`, `search`	`ui://evlek/listing-cards-v3-11.html`	Cartões de anúncios (foto de capa, preço, localização); abrir um mostra a visualização de detalhes do anúncio; no ChatGPT, "Mostrar no mapa" abre um mapa em tela cheia de cada correspondência
`get_listing`, `fetch`	`ui://evlek/listing-detail-v3-8.html`	Galeria de fotos, ficha técnica e virtual staging com IA antes/depois (sempre divulgado como IA)
`market_stats`	`ui://evlek/price-index-v3-6.html`	Estatísticas de preço pedido por cidade / distrito

compare_listings, list_locations e convert_currency não têm widget. Os URIs de widget mudaram de -v2 para -v3 na 3.0.0 para que um host nunca sirva um modelo v2 em cache contra dados v3. A 3.0.1 os moveu para -v3-1, a 3.0.2 para -v3-2, a 3.0.3 para -v3-3 e a 3.1.0 para -v3-4 (cartões e detalhes, depois -v3-5); a 3.1.4 serve cartões -v3-11, detalhes -v3-8 e índice de preços -v3-6. Os URIs v3 mais antigos continuam respondendo com o conteúdo atual. Regra desde a 3.1.0: o conteúdo de um widget nunca muda sob um URI com o qual foi publicado (um host armazena em cache um modelo por URI), portanto um widget alterado recebe um novo URI. No ChatGPT (3.0.2, search desde 3.0.3) os dados de listagem chegam ao widget através do resultado _meta["evlek/widget"], que o ChatGPT mostra apenas ao widget; para search_listings e get_listing o modelo recebe um resumo curto (contagens, faixa de preço, números de listagem). Outros clientes recebem o structuredContent completo como antes.

As visualizações são HTML estático e autocontido — sem bundler, sem JS de terceiros. Os dados de listagem chegam a elas apenas em tempo de execução via postMessage e são gravados com textContent, nunca innerHTML. A CSP é declarada por recurso (_meta.ui.csp) e limitada à origem pública de fotos de listagens.

Consulte TOOLS.md para esquemas de entrada completos, detalhes de parâmetros e exemplos de resposta.

Recursos (12) e modelos de recursos (2)

resources/list retorna 12 recursos no endpoint hospedado — 9 recursos de dados evlek:// somente leitura, mais os 3 recursos de widget interativo ui:// descritos acima (pré-declarados para que um host possa pré-cacheá-los). Os modelos parametrizados são separados, via resources/templates/list:

Modelos (2): evlek://price-index/{city} · evlek://district/{city}/{district}
Recursos de dados (9): índices de preço por cidade (girne, iskele, lefkosa, gazimagusa, guzelyurt, lefke), um perfil de distrito de amostra (Girne/Alsancak) e 2 guias de orientação — evlek://guides/neighborhood-personas, evlek://guides/universities.
Recursos de widget (3): ui://evlek/listing-cards-v3-11.html, ui://evlek/listing-detail-v3-8.html, ui://evlek/price-index-v3-6.html — consulte "Widgets interativos" acima.

Ferramentas renomeadas na 3.0.0 (aliases obsoletos)

A 3.0.0 consolida as 12 ferramentas da v2 em 8. Os nomes antigos abaixo não estão mais em tools/list, mas o endpoint hospedado ainda os atende por uma versão: a chamada é traduzida para a nova ferramenta, executada, e o resultado começa com uma linha Deprecated: … Use <new> instead. (além de structuredContent.deprecated). Os aliases são removidos na 3.1.0 — mude para os novos nomes agora.

Nome antigo (v2)	Novo nome (3.0.0)	Mudança de argumento
`get_listing_detail`	`get_listing`	`propertyId` / `property_id` → `ref`
`get_listing_by_number`	`get_listing`	`listingNumber` / `listing_number` → `ref`
`compare_properties`	`compare_listings`	`listingIds` / `listing_ids` → `ids`
`get_price_index`	`market_stats`	`city` mantido; `type` → `transaction` (padrão `sale`)
`compare_cities`	`market_stats`	`cities` → `city`; `type` → `transaction` (padrão `sale`)
`get_district_profile`	`market_stats`	`city`, `district` mantidos
`payment_plan`	`convert_currency`	`price` → `amount` (o nome permanece reservado para uma futura ferramenta de parcelamento)

Nomes inalterados: search_listings, search, fetch, list_locations, convert_currency. search_listings, list_locations e convert_currency ganharam novos parâmetros e nomes canônicos (ex.: transaction, priceMin/priceMax, sort, cursor, amount, locale) — consulte TOOLS.md. Os nomes da v2 type, maxPrice e price ainda são aceitos no endpoint hospedado. Ferramentas removidas na 2.0.0 e anteriores (get_yield_estimate, suggest_neighborhood, student_housing, get_market_overview, get_legal_info) ainda retornam um erro de protocolo indicando a substituição, não um alias.

Prompts (2)

property_scenario — Cenário de propriedade ilustrativo com fatos reais separados
student_rental_scenario — Cenário ilustrativo de aluguel estudantil

Exemplos de prompts

"Encontre apartamentos de 2 quartos para alugar em Girne por menos de £1.500/mês."
"Mostre-me apartamentos em Girne por menos de £150.000."
"Qual é o preço médio de venda por metro quadrado em Lefkoşa?"
"Compare Kyrenia e Famagusta — qual tem mais listagens ativas e como os preços médios pedidos diferem?"
"Como é um perfil de distrito para Alsancak?"
"Converta £150.000 para EUR, USD e TRY."

Cobertura

Cidades: 6 (Girne, İskele, Lefkoşa, Gazimağusa, Güzelyurt, Lefke)
Distritos: 100+
Moeda: GBP principal; TRY/USD/EUR normalizados para GBP no servidor usando taxas de câmbio diárias ao vivo
Descrições de ferramentas: EN · Respostas: TR · EN · RU · DE · AR (locale)

Arquitetura

O servidor Evlek MCP é executado como um endpoint hospedado em https://evlek.app/api/mcp. Ele fala o Model Context Protocol via Streamable HTTP (JSON-RPC 2.0), protocolVersion 2026-07-28, e expõe ferramentas, recursos, modelos de recursos e prompts. Os metadados de descoberta são publicados em /.well-known/mcp.json.

Este repositório contém:

server.json — Manifesto do Registro MCP
tools.json — Contrato de ferramentas ao vivo (o que o servidor stdio local responde tools/list)
TOOLS.md — Referência completa de ferramentas (esquemas JSON + exemplos)
CHANGELOG.md — Mudanças notáveis na superfície de ferramentas, incluindo ferramentas removidas/renomeadas
examples/ — Arquivos de configuração para Claude Desktop, Cursor, VS Code
CONTRIBUTING.md — Como relatar problemas e propor melhorias na documentação

Arquivos de contrato

tools.json e TOOLS.md são uma projeção do servidor ao vivo, gerados por pnpm mcp:export-public no repositório de origem e copiados aqui verbatim. Nunca os edite manualmente; o fluxo de trabalho Contract Drift compara tools.json com o tools/list ao vivo diariamente e em cada PR.
server.json não é essa projeção. É o manifesto de publicação do Registro MCP e deve manter a forma do registro: name é app.evlek/mcp-server (padrão ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$) e description tem no máximo 100 caracteres. Uma sincronização atualiza apenas seu version, a contagem de ferramentas em description e a lista de ferramentas _meta. (Copiar o próprio server.json da exportação aqui foi o que falhou na publicação do registro v2.1.0.)

A implementação completa do servidor (esquemas de banco de dados, rotas de API, engenharia de prompts de IA, pipeline de listagens) está hospedada em evlek.app e permanece proprietária.

Modelo de segurança

Conforme OWASP MCP Top 10: limite de taxa por IP de 60/min, global de 500/min, timeout rígido de 30s, validação de entrada Zod, sanitização de saída (defesa contra injeção de prompt), máximo de 10 resultados por consulta, chave anônima Supabase + RLS, sem vazamento de stack traces, observabilidade Sentry.

Para relatar um problema de segurança, envie um e-mail para hello@evlek.app.

Status

Versão MCP: 3.1.4 (ao vivo)
Protocolo: 2026-07-28
Primitivas: 8 ferramentas · 9 recursos de dados + 3 recursos de widget interativo · 2 modelos de recursos · 2 prompts
Autenticação: nenhuma (somente leitura pública)
Endpoint: https://evlek.app/api/mcp
Registro MCP: app.evlek/mcp-server

Licença

MIT — consulte LICENSE. O MIT cobre apenas o manifesto público, a documentação, os exemplos e os clientes de referência neste repositório (consulte Escopo da licença acima). O serviço Evlek hospedado (aplicativo web, aplicativos móveis, dados de listagem, prompts de IA, esquemas de banco de dados, lógica de negócios) é proprietário.

Aviso de marca registrada: "Evlek" é uma marca registrada de Onur Dokuzoğlu. A licença MIT não concede direitos de uso do nome, logotipo ou identidade visual "Evlek", exceto conforme descrito neste README. Para solicitar permissão de uso da marca, entre em contato com hello@evlek.app.