Evlek — Northern Cyprus Property Mcp

Evlek MCP 服务

面向 AI 的北塞浦路斯（KKTC）房产发现服务。基于 Model Context Protocol 构建，可在 Claude、ChatGPT、Gemini、Cursor 以及任何兼容 MCP 的客户端中使用。

Evlek MCP 服务为 AI Agent 提供对北塞浦路斯房产数据的结构化实时访问能力——搜索在售房源、比较城市和地区，并追踪价格指数。所有数据均实时来自 evlek.app。Evlek 不提供租金收益率或投资回报估算：相关数字仅为描述性挂牌价事实，不构成估值、预测或建议。产权证（koçan）和法律程序工具有意不纳入服务范围：相关分类尚未通过独立的 KKTC 法律审计。

许可范围

本仓库采用 MIT 许可证，适用于此处包含的公开清单、文档、示例和参考客户端。托管的 Evlek 服务、evlek.app Web 应用、移动应用、房源数据库、AI 提示词、业务逻辑、品牌资产、名称、徽标和商业外观仍为专有内容，不受 MIT 许可证授权。详情请参阅 LICENSE。

---

为什么选择 Evlek MCP

• AI 优先。 从第一天起就为 Agent 工作流而构建，而不是在传统房源 API 上改造而成。
• 多语言。 支持以 TR、EN、RU、DE、AR 作答：传入 locale（或使用相应语言编写 search 查询），文本、配套设施名称、数字格式和链接都会相应切换。地点名称支持这五种语言。
• 关注验证状态的房源。 Evlek 会在可用时展示房源和账户的验证信息；MCP 不提供联系字段，以保留 Evlek 的信息展示／联系转化流程。
• 专为本地区打造。 针对北塞浦路斯的 6 个城市（Lefkoşa、Girne、Gazimağusa、İskele、Güzelyurt、Lefke）和 100 多个地区进行了优化。
• 达到生产级标准。 符合 OWASP MCP Top 10 要求——使用 Zod 输入验证、输出清理、速率限制（60 次／分钟／IP，500 次／分钟／全局）和 Sentry 可观测性。

---

快速开始

支持远程连接的客户端（首选）

大多数现代 MCP 客户端（Claude、Cursor、VS Code）都可直接连接 Streamable HTTP 端点，无需本地桥接：

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

ChatGPT（连接器 + Deep Research）

添加 https://evlek.app/api/mcp 作为自定义连接器。Evlek 提供兼容 OpenAI 的 search 和 fetch 工具，因此除了开发者模式，也可用于 ChatGPT 连接器和 Deep Research。

Claude Desktop（旧版 stdio 桥接）

如果你的客户端仅支持 stdio 服务，请使用固定版本的 mcp-remote 桥接。将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

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

重启 Claude Desktop。“evlek”服务会出现在工具列表中。

MCP Inspector（安装前测试）

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

直接调用 API（cURL）

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

更多配置：examples/

---

本地 stdio 服务（此存储库）

此存储库也可作为可运行的 MCP 服务。它完全从嵌入的工具契约（tools.json）在本地响应 initialize / tools/list，并在调用工具时从 Evlek 数据 API 获取实时数据。它仅实现工具，不声明 resources 或 prompts 能力，因此在此桥接服务上，resources/list 和 prompts/list 会返回标准的 MCP“method not found”错误；这些原语（见下文）仅由托管端点提供，可通过上方的 Streamable HTTP URL 访问。它还会在 initialize 期间使用固定版本的 @modelcontextprotocol/sdk 所支持的 MCP 协议版本（目前为 2025-11-25），不一定与托管端点的 2026-07-28 版本相同——两种情况下的工具架构都相同。

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

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

对其进行冒烟测试（启动服务并通过 stdio 使用真实 MCP 通信）：

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

可用工具

8 个工具 · 协议 2026-07-28 · Streamable HTTP JSON-RPC 2.0

工具	标题	描述
search_listings	搜索北塞浦路斯房源	当用户想查找或查看房源时使用此工具；结果会在 Evlek 小组件中显示真实照片。搜索 Evlek 上北塞浦路斯（KKTC/TRNC）的在售和长期出租房源（除非指定货币，否则价格以 GBP 计；2+1 表示 2 间卧室），并支持结构化筛选：交易类型、城市、地区、房产类型、卧室数、价格、面积、设施、附近大学。将用户的语言作为 locale 传入（tr|en|ru|de|ar）：文本、设施名称、数字格式和链接会使用相应语言。每次调用最多返回 10 条房源，每条房源包含一行易读信息（类型、地点、价格、房间数、面积、一句确定性描述、数据说明、规范链接）以及一张结构化卡片；继续查询时使用某一组的 nextCursor。如果没有提供 transaction，在售和出租房源会分成两组返回，每组都有自己的游标，且游标只能与该组的交易类型一起使用。任何语言的地点名称都可以解析；未知地点会返回建议而非结果。无法用于筛选的设施会标明未应用。如需查询单条房源，请使用 get_listing。仅返回挂牌的要价和房源信息：不提供估值、对特定房产声明的核实、预测、排名或建议。
search	搜索 Evlek 房源	仅用于研究和引用查询（深度研究）。若要向用户展示房源，请改用 search_listings。使用土耳其语、英语、俄语、德语或阿拉伯语的自由文本查询，在 Evlek 上搜索北塞浦路斯（KKTC/TRNC）的实时房源。按最新发布顺序返回匹配房源的 id/title/url，供 fetch 工具使用（如果查询未指定在售或出租，则分成两组）。回答语言与查询语言一致。数据与 search_listings 相同：此固定形式用于满足 ChatGPT/OpenAI 连接器契约。适用场景：调用方只有自由文本查询（“Kyrenia 低于 150000 镑的 2+1 公寓”、“EVL-100464”）。不适用于：结构化筛选、分页或使用其他回答语言；这些情况请使用 search_listings。
fetch	获取 Evlek 房源详情	获取一条 Evlek 房源的完整详情：标题、价格、位置、房间数、面积、设施、数据质量说明和规范链接。id 可以是搜索结果中的房源 id（UUID）、房源编号（例如 EVL-100464）或 evlek.app 房源链接；回答语言与链接语言一致（否则使用英语）。对于不可用的房源（不存在、未公开或已下架），始终返回相同的回答。数据与 get_listing 相同：此固定的仅 id 形式用于满足 ChatGPT/OpenAI 连接器契约。适用场景：已知搜索结果中的 id。不适用于：发现房源（请先使用 search）或使用其他回答语言（请使用 get_listing）。
get_listing	获取 Evlek 房源	使用用户的语言获取一条公开 Evlek 房源（在售或长期出租）的完整详情。ref 可以是房源 id（UUID）、房源编号（EVL-100464 或仅 100464），也可以是任意语言的 evlek.app 房源链接。返回价格、房间数、浴室数、建筑面积和地块面积（始终分开列出）、大致位置、特色、房屋中介名称、日期、数据质量说明、存在时附带说明文字的照片、经房屋中介批准的 AI 虚拟布置前后对比图片（始终标注为 AI 生成），以及规范链接。不会包含联系方式：请将用户引导至链接。对于未知或已不再公开的房源，返回 found:false 和代码 NOT_FOUND（这不属于错误）。将用户的语言作为 locale 传入（tr、en、ru、de 或 ar）。
compare_listings	比较 Evlek 房源	使用用户的语言并排比较 2 至 4 条公开 Evlek 房源：价格、每 m² 价格（仅在建筑面积可信时提供）、房间数、浴室数、建筑面积和地块面积（始终分开列出）、位置、家具配置、主要特色和数据质量说明，以及若干描述性亮点（最低价格、最大室内面积、最新发布）。ids 可以包含房源 id（UUID）、房源编号（EVL-100464）或 evlek.app 房源链接，格式可以混用；结果会保留输入顺序。在售和出租房源绝不会互相比排名：混合请求会分成两组显示，并附带警告。未知或已不再公开的引用会列在 missingIds 中，代码为 NOT_FOUND（这不属于错误）。仅提供描述性信息：不提供估值或建议。将用户的语言作为 locale 传入（tr、en、ru、de 或 ar）。
market_stats	北塞浦路斯市场统计数据	北塞浦路斯的市场统计数据，基于当前公开房源的要价（不代表成交价、估值或预测）。未指定城市 = 按城市统计整个岛屿；指定一个城市 = 统计其各地区；指定多个城市 = 并排展示；指定城市和地区 = 该地区的概况。在售和出租数据分开报告。每个数值都包含 activeCount（范围内的公开房源数）和 sampleCount（统计数据所依据的清理后样本数）；样本房源少于 10 条时不提供该数值。传入 locale。
list_locations	列出 Evlek 地点	列出 Evlek 在北塞浦路斯收录的地点（6 个城市、地区、村庄、子区域、地标、卡尔帕兹地区），以及各地点公开在售和长期出租房源的数量。不确定地点名称的拼写时，请先调用此工具：返回的每个名称和 id 都可用于其他工具。传入 city（任意拼写或语言）可查看单个地点的详情。名称使用土耳其语或拉丁字母；接受俄语、德语和阿拉伯语拼写作为输入，但不会以这些语言列出名称。
convert_currency	货币转换（GBP/EUR/USD/TRY）	使用 Evlek 存储的汇率（每日更新）转换 GBP、EUR、USD 和 TRY 之间的金额，并返回四种货币的等值金额。仅进行货币转换：不提供付款计划、押金或分期安排、税费、手续费或购置成本估算，也不提供建议。汇率超过 24 小时会标记为过期；超过 72 小时（或没有存储汇率）时不执行转换（FX_UNAVAILABLE）。
每个工具都声明了 annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }——整个接口均为只读。

交互式小组件（MCP Apps / SEP-1865）

其中五个工具还会绑定一个沙盒 HTML 视图（_meta.ui.resourceUri），支持 MCP Apps 的宿主（Claude web/desktop）会在对话中内嵌渲染该视图：

工具	小组件	内容
search_listings、search	ui://evlek/listing-cards-v3-11.html	房源卡片（封面照片、价格、位置）；打开卡片后会显示房源详情视图；在 ChatGPT 中，“在地图上显示”会打开全屏地图，展示所有匹配结果
get_listing、fetch	ui://evlek/listing-detail-v3-8.html	照片画廊、规格表，以及 AI 虚拟布置前后对比（始终标明由 AI 生成）
market_stats	ui://evlek/price-index-v3-6.html	按城市 / 区域展示的挂牌价统计

compare_listings、list_locations 和 convert_currency 没有小组件。3.0.0 版将小组件 URI 从 -v2 改为 -v3，以避免宿主将缓存的 v2 模板用于 v3 数据。3.0.1 版将 URI 改为 -v3-1，3.0.2 版改为 -v3-2，3.0.3 版改为 -v3-3，3.1.0 版改为 -v3-4（随后卡片和详情改为 -v3-5）；3.1.4 版使用卡片 -v3-11、详情 -v3-8 和价格指数 -v3-6。较早的 v3 URI 仍会返回当前内容。自 3.1.0 版起的规则：小组件的内容在其发布时所用的 URI 下永不更改（宿主会按 URI 缓存模板），因此内容有变化的小组件会使用新 URI。

在 ChatGPT 中（3.0.2 版起；search 从 3.0.3 版起），房源数据通过结果 _meta["evlek/widget"] 传递给小组件；ChatGPT 只向小组件显示此数据。对于 search_listings 和 get_listing，模型会收到简短摘要（数量、价格范围、房源编号）。其他客户端仍会像之前一样获取完整的 structuredContent。

视图是静态、独立的 HTML——无需打包器，也不依赖第三方 JS。房源数据仅在运行时通过 postMessage 传入，并使用 textContent 写入，绝不使用 innerHTML。CSP 按资源声明（_meta.ui.csp），并限制为公开的房源照片来源。

完整的输入架构、参数详情和响应示例，请参阅 TOOLS.md。

资源（12 个）和资源模板（2 个）

托管端点上的 resources/list 会返回 12 个资源——9 个只读的 evlek:// 数据资源，以及上文所述的 3 个 ui:// 交互式小组件资源（预先声明，以便宿主预缓存）。参数化模板单独通过 resources/templates/list 返回：

• 模板（2 个）： evlek://price-index/{city} · evlek://district/{city}/{district}
• 数据资源（9 个）： 各城市的价格指数（girne、iskele、lefkosa、gazimagusa、guzelyurt、lefke）、一个示例区域资料（Girne/Alsancak），以及 2 份方位指南——evlek://guides/neighborhood-personas、evlek://guides/universities。
• 小组件资源（3 个）： ui://evlek/listing-cards-v3-11.html、ui://evlek/listing-detail-v3-8.html、ui://evlek/price-index-v3-6.html——请参阅上文“交互式小组件”。

3.0.0 中重命名的工具（已弃用的别名）

3.0.0 将 12 个 v2 工具整合为 8 个。下方的旧名称不再出现在 tools/list 中，但托管端点仍会在一个版本周期内响应这些名称：调用会被转换为新工具并执行，结果以 Deprecated: … Use <new> instead. 行开头（并包含 structuredContent.deprecated）。这些别名将在 3.1.0 中移除——请立即切换到新名称。

旧名称（v2）	新名称（3.0.0）	参数变化
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；type → transaction（默认为 sale）
compare_cities	market_stats	cities → city；type → transaction（默认为 sale）
get_district_profile	market_stats	保留 city、district
payment_plan	convert_currency	price → amount（该名称仍预留给未来的分期付款工具）

名称未变的工具：search_listings、search、fetch、list_locations、 convert_currency。search_listings、list_locations 和 convert_currency 新增了参数和规范名称（例如 transaction、priceMin/priceMax、 sort、cursor、amount、locale）——请参阅 TOOLS.md。托管端点仍接受 v2 名称 type、maxPrice 和 price。2.0.0 及更早版本中移除的工具（get_yield_estimate、suggest_neighborhood、 student_housing、get_market_overview、get_legal_info）仍会返回协议错误，并指出替代工具，而不会提供别名。

提示词（2）

• property_scenario — 房产情景示例，包含单独列出的实时事实
• student_rental_scenario — 学生租房情景示例

---

示例提示词

• “查找 Girne 的两居室出租公寓，月租低于 £1,500。”
• “显示 Girne 中售价低于 £150,000 的公寓。”
• “Lefkoşa 的每平方米销售中位价是多少？”
• “比较 Kyrenia 和 Famagusta——哪座城市的在售房源更多？两地的挂牌中位价有何差异？”
• “Alsancak 的区域概况是什么样的？”
• “将 £150,000 兑换为 EUR、USD 和 TRY。”

---

覆盖范围

• **城市：**6 个（Girne、İskele、Lefkoşa、Gazimağusa、Güzelyurt、Lefke）
• **区域：**100+
• **货币：**主要使用 GBP；TRY/USD/EUR 在服务端使用每日实时汇率换算为 GBP
• **工具说明：**EN · **回答：**TR · EN · RU · DE · AR（locale）

---

架构

Evlek MCP 服务以托管端点的形式运行，地址为 https://evlek.app/api/mcp。它通过 Streamable HTTP（JSON-RPC 2.0）使用 Model Context Protocol，采用 protocolVersion 2026-07-28，并公开工具、资源、资源模板和提示词。发现元数据发布在 /.well-known/mcp.json。

此代码库包含：

• server.json — MCP Registry 清单
• tools.json — 实时工具契约（本地 stdio 服务对 tools/list 的响应内容）
• TOOLS.md — 完整工具参考（JSON 架构 + 示例）
• CHANGELOG.md — 工具接口的重要变更，包括移除或重命名的工具
• examples/ — Claude Desktop、Cursor、VS Code 的配置文件
• CONTRIBUTING.md — 如何提交问题并提出文档改进建议

合约文件（contract files）

• tools.json 和 TOOLS.md 是实时服务的投影，由源代码仓库中的 pnpm mcp:export-public 生成，并原样复制到此处。切勿手动编辑；Contract Drift 工作流每天及每次 PR 时都会将 tools.json 与实时的 tools/list 进行比对。
• server.json 不是该投影。它是 MCP Registry 发布清单，必须保留 Registry 格式：name 为 app.evlek/mcp-server（模式 ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$），且 description 最多 100 个字符。同步时只会更新其 version、description 中的工具数量，以及 _meta 工具列表。（将导出文件自带的 server.json 复制到此处，正是 v2.1.0 Registry 发布失败的原因。）

完整的服务实现（数据库架构、API 路由、AI 提示词工程、房源信息处理流程）托管在 evlek.app，并且仍为专有内容。

安全模型

根据 OWASP MCP Top 10：按 IP 限流，每分钟 60 次；全局限流，每分钟 500 次；30 秒硬超时；Zod 输入验证；输出清理（提示词注入防护）；每次查询最多返回 10 条结果；Supabase 匿名密钥 + RLS；不泄露堆栈跟踪；Sentry 可观测性。

如需报告安全问题，请发送邮件至 [email protected]。

---

状态

• MCP 版本： 3.1.4（在线）
• 协议： 2026-07-28
• 原语： 8 个工具 · 9 个数据资源 + 3 个交互式小组件资源 · 2 个资源模板 · 2 个提示词
• 身份验证： 无（公开只读）
• 端点： https://evlek.app/api/mcp
• MCP Registry： app.evlek/mcp-server

---

许可证

MIT — 请参阅 LICENSE。MIT 仅适用于此仓库中的公开清单、文档、示例和参考客户端（请参阅上文的许可证范围）。托管的 Evlek 服务（Web 应用、移动应用、房源数据、AI 提示词、数据库架构、业务逻辑）为专有内容。

商标声明：“Evlek”是 Onur Dokuzoğlu 的商标。除本 README 中所述情形外，MIT 许可证不授予使用“Evlek”名称、徽标或品牌标识的权利。如需申请品牌使用许可，请联系 [email protected]。

---

链接

• 网站： evlek.app
• iOS： App Store
• Android： Google Play
• MCP 端点： https://evlek.app/api/mcp
• MCP 文档： evlek.app/mcp
• MCP Registry： app.evlek/mcp-server
• Model Context Protocol： modelcontextprotocol.io
• 联系： [email protected]

---

由一位建筑师而非软件公司在北塞浦路斯打造。由 Anthropic Claude、Supabase、Vercel 和 Model Context Protocol 提供支持。