urlDNA

เซิร์ฟเวอร์ MCP urlDNA

บล็อก

urlDNA MCP Server ช่วยให้เอเจนต์ LLM ที่เน้นความปลอดภัย เช่น OpenAI GPT, Google Gemini และ Claude Desktop สามารถใช้เครื่องมือได้โดยตรง โดยเป็นอินเทอร์เฟซโดยตรงสำหรับโต้ตอบกับแพลตฟอร์มข่าวกรองภัยคุกคาม urlDNA ผ่าน API

พื้นที่เก็บข้อมูลนี้เปิดเผยชุดเครื่องมือเดียวกันผ่านสองทรานสปอร์ต:

• stdio สำหรับการผสานรวมกับเดสก์ท็อปในเครื่อง เช่น Claude Desktop
• streamable-http สำหรับการปรับใช้แบบโฮสต์ เช่น Cloud Run

---

การติดตั้งและการตั้งค่า

โปรเจกต์นี้ใช้ uv สำหรับการจัดการแพ็กเกจ Python ที่รวดเร็ว

ข้อกำหนดเบื้องต้น

ติดตั้ง uv หากคุณยังไม่ได้ติดตั้ง:

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or with pip
pip install uv

เริ่มต้นอย่างรวดเร็ว

1. โคลนและตั้งค่าโปรเจกต์:

git clone <repository-url>
cd urlDNA-mcp-server
uv sync

2. รันเซิร์ฟเวอร์ MCP ในเครื่อง (โหมด stdio):

uv run python urldna_mcp/run.py

3. รันเซิร์ฟเวอร์ MCP ในโหมด HTTP แบบสตรีมได้:

uv run python urldna_mcp/server.py

เซิร์ฟเวอร์ที่โฮสต์จะอ่านตัวแปรสภาพแวดล้อมเหล่านี้:

• PORT: พอร์ต HTTP ที่จะผูก ค่าเริ่มต้นคือ 8080
• MCP_PATH: เส้นทางปลายทาง MCP สาธารณะ ค่าเริ่มต้นคือ /

การพัฒนา

# Install development dependencies
uv sync --dev

# Run tests (when available)
uv run pytest

# Format code
uv run black .

# Type checking
uv run mypy .

# Lint code
uv run flake8 .

---

เซิร์ฟเวอร์ MCP ที่โฮสต์

เซิร์ฟเวอร์ urlDNA MCP ได้ถูกโฮสต์และพร้อมใช้งานแล้วที่:

https://mcp.urldna.io/

เซิร์ฟเวอร์นี้เข้าถึงได้ผ่าน HTTP แบบสตรีมได้ ซึ่งเหมาะสำหรับ Cloud Run และแพลตฟอร์มที่ขับเคลื่อนด้วยคำขออื่น ๆ

คุณสามารถใช้ได้โดยตรงกับแพลตฟอร์มหรือ LLM ใด ๆ ที่รองรับข้อกำหนด MCP (เช่น Claude Desktop, OpenAI GPT, Google Gemini)

---

เครื่องมือที่รองรับ

การสแกน

เครื่องมือ	คำอธิบาย
fast_check	ตรวจสอบทันทีว่า URL ถูกสแกนแล้วหรือไม่ คืนค่า SAFE / MALICIOUS / UNRATED
new_scan	ส่ง URL เพื่อสแกนแบบเต็มและรอผลลัพธ์ (~30–60 วินาที)
get_scan	ดึงผลการสแกนแบบสมบูรณ์ตาม ID

การค้นหา

เครื่องมือ	คำอธิบาย
search	ค้นหาการสแกนโดยใช้ CQL (Custom Query Language) ผ่านโดเมน, IP, เทคโนโลยี, ธงที่เป็นอันตราย และอื่น ๆ รองรับนิพจน์ AND และ OR พร้อมการแบ่งหน้า (หน้า 2+ ต้องใช้ PREMIUM)

คำค้นหาที่บันทึกไว้

เครื่องมือ	คำอธิบาย
list_queries	แสดงรายการคำค้นหาที่บันทึกไว้ทั้งหมดสำหรับผู้ใช้ที่ตรวจสอบสิทธิ์
get_query	ดึงคำค้นหาที่บันทึกไว้และตัวกรองตาม ID
create_query	สร้างคำค้นหาที่บันทึกใหม่ด้วยเงื่อนไขตัวกรอง CQL หนึ่งรายการขึ้นไป
update_query	อัปเดตชื่อและตัวกรองของคำค้นหาที่มีอยู่ (แทนที่ทั้งหมด)
delete_query	ลบคำค้นหาที่บันทึกไว้ตาม ID อย่างถาวร
query_scans	ดึงการสแกนที่ตรงกันทั้งหมดสำหรับคำค้นหาที่บันทึกไว้

การตรวจสอบแบรนด์

เครื่องมือ	คำอธิบาย
list_brands	แสดงรายการแบรนด์ที่มีอยู่พร้อมการค้นหาชื่อและตัวกรองการมองเห็น (ALL / FREE / PREMIUM / USER_BRANDS)
get_brand	ดึงรายละเอียดทั้งหมดของแบรนด์เฉพาะตาม ID
brand_scans	รับการสแกนทั้งหมดที่เกี่ยวข้องกับแบรนด์ รองรับการกรอง CQL เพิ่มเติม

เอกสารอ้างอิง API

เครื่องมือ	คำอธิบาย
search_docs	ดึง OpenAPI และเอกสารประกอบฉบับเต็มของ urlDNA

---

การผสานรวมกับ Claude Desktop

หากต้องการผสานรวม urlDNA MCP server ใน Claude Desktop ให้อัปเดต claude_desktop_config.json ของคุณ:

{
  "mcpServers": {
    "urlDNA": {
      "command": "uv",
      "args": [
        "--directory",
        "<YOUR_PATH>\\urldna_mcp",
        "run",
        "urldna_mcp\\run.py"
      ],
      "env": {
        "x-api-key": "<urlDNA_API_KEY>"
      }
    }
  }
}

แทนที่ <YOUR_PATH> ด้วยไดเรกทอรีหลักที่มีพื้นที่เก็บข้อมูลนี้ และ <urlDNA_API_KEY> ด้วยคีย์ API ของคุณจาก https://urldna.io

สำหรับไคลเอนต์ MCP ที่โฮสต์ ให้ชี้ไปที่ https://mcp.urldna.io/ หรือ MCP_PATH ที่คุณปรับใช้เอง

เมื่อกำหนดค่าแล้ว คุณสามารถสั่ง Claude ด้วยภาษาธรรมชาติ เช่น:

"ค้นหาใน urlDNA สำหรับการสแกนที่เป็นอันตรายที่มีชื่อคล้าย paypal"

"สร้างคำค้นหาที่บันทึกไว้สำหรับการสแกนบนมือถือจากอิตาลีที่ถูกทำเครื่องหมายว่าเป็นอันตราย"

"แสดงการสแกนทั้งหมดที่เกี่ยวข้องกับแบรนด์ Google"

Claude จะเรียกใช้เครื่องมือที่ถูกต้องโดยอัตโนมัติและส่งคืนผลลัพธ์จากแพลตฟอร์ม urlDNA

---

การใช้เซิร์ฟเวอร์ MCP กับ OpenAI GPT

from openai import OpenAI

# Initialize OpenAI client (assumes OPENAI_API_KEY is set via environment variable)
client = OpenAI()

response = client.responses.create(
    model="gpt-3.5-turbo",  # Note: MCP tool use requires a Responses API-compatible model
    input=[
        {
            "role": "system",
            "content": [{"type": "input_text", "text": "You are a cybersecurity analyst using urlDNA."}]
        },
        {
            "role": "user",
          "content": [{"type": "input_text", "text": "Search in urlDNA for malicious scans with title like paypal or login"}]
        }
    ],
    text={"format": {"type": "text"}},
    reasoning={},
    tools=[
        {
            "type": "mcp",
            "server_label": "urlDNA",
            "server_url": "https://mcp.urldna.io/",
            "headers": {
                "x-api-key": "<URLDNA_API_KEY>"  # Replace with your urlDNA API key
            },
            "allowed_tools": [
                # --- Scanning ---
                "new_scan",       # Submit a URL for a full scan and wait for the result
                "get_scan",       # Retrieve a scan result by ID
                "fast_check",     # Lightweight instant safety check (SAFE / MALICIOUS / UNRATED)

                # --- Search ---
                "search",         # Search scans using CQL (Custom Query Language, AND/OR supported)

                # --- Saved Queries (PREMIUM) ---
                "list_queries",
                "get_query",
                "create_query",
                "update_query",
                "delete_query",
                "query_scans",

                # --- Brand Monitoring (PREMIUM) ---
                "list_brands",
                "get_brand",
                "brand_scans",

                # --- API Reference ---
                "search_docs",
            ],
            "require_approval": "never"
        }
    ],
    temperature=0.7,
    top_p=1,
    max_output_tokens=2048,
    store=True
)

print(response.output)

---

การใช้เซิร์ฟเวอร์ MCP กับ Google Gemini

Gemini เชื่อมต่อกับเซิร์ฟเวอร์ urlDNA MCP ผ่าน fastmcp และเครื่องมือจะถูกค้นพบโดยอัตโนมัติแทนที่จะส่งเป็นรายการ allowed_tools

import os
import asyncio
from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport
from google import genai

async def main():
    # 1. Connect FastMCP client directly to streamable-http
    transport = StreamableHttpTransport(
        "https://mcp.urldna.io/",
        headers={"x-api-key": os.getenv("URLDNA_API_KEY", "YOUR_KEY")},
    )
    client_mcp = Client(transport)

    async with client_mcp:
        ai = genai.Client(vertexai=True, project=os.getenv("GOOGLE_CLOUD_PROJECT", "YOUR_PROJECT_ID"))
        response = await ai.aio.models.generate_content(
            model="gemini-2.5-flash",
            contents="Search in urlDNA for malicious scans with title like paypal",
            # Pass the live MCP session (not just tool declarations) so Gemini
            # can automatically call tools and receive their results.
            config=genai.types.GenerateContentConfig(tools=[client_mcp.session]),
        )

        print(response.text)


if __name__ == "__main__":
    asyncio.run(main())

---

การปรับใช้คอนเทนเนอร์

สร้างและรันด้วย Docker:

# Build the container
docker build -t urldna-mcp-server .

# Run the server
docker run -p 8080:8080 -e x-api-key=<URLDNA_API_KEY> urldna-mcp-server

# Optional: override the public MCP path if you do not want /
docker run -p 8080:8080 -e MCP_PATH=/custom-path -e x-api-key=<URLDNA_API_KEY> urldna-mcp-server

# Cloud Run example
gcloud run deploy urldna-mcp-server \
  --source . \
  --allow-unauthenticated \
  --set-env-vars MCP_PATH=/

ไวยากรณ์การค้นหา

เครื่องมือ search และ brand_scans ส่งต่อ CQL ที่ให้ไว้โดยตรงไปยัง API ของ urlDNA คุณสามารถรวมเงื่อนไขด้วย AND หรือ OR

ตัวอย่าง:

malicious = true AND technology LIKE wordpress
domain = google.com OR domain = youtube.com
(domain = paypal.com OR title LIKE paypal) AND country_code = IT

---

การมีส่วนร่วม

1. Fork พื้นที่เก็บข้อมูล
2. สร้างสาขาฟีเจอร์: git checkout -b feature-name
3. ติดตั้ง dependencies สำหรับการพัฒนา: uv sync --dev
4. ทำการเปลี่ยนแปลงและตรวจสอบให้แน่ใจว่าการทดสอบผ่าน
5. จัดรูปแบบโค้ด: uv run black .
6. ส่ง pull request

---

การติดต่อและการสนับสนุน

สำหรับการสนับสนุนหรือการเข้าถึง API โปรดเยี่ยมชม https://urldna.io หรือส่งอีเมลไปที่ urldna@urldna.io