mcp-zoomeye-org 0.1.0__py3-none-any.whl

mcp_zoomeye_org/__init__.py

@@ -0,0 +1,19 @@
+from .server import serve
+
+
+def main():
+    """MCP ZoomEye Server - ZoomEye search for MCP"""
+    import argparse
+    import asyncio
+
+    parser = argparse.ArgumentParser(
+        description="give a model the ability to handle ZoomEye queries"
+    )
+    parser.add_argument("--key", type=str, help="ZoomEye API Key")
+
+    args = parser.parse_args()
+    asyncio.run(serve(args.key))
+
+
+if __name__ == "__main__":
+    main()

mcp_zoomeye_org/__main__.py

@@ -0,0 +1,3 @@
+from mcp_zoomeye_org import main
+
+main()

mcp_zoomeye_org/prompts.py

@@ -0,0 +1,203 @@
+SEARCH_SYNTAX_GUIDE = """
+### Search Syntax Guide
+
+- Search Scope covers devices (IPv4, IPv6) and websites (domains).
+- When entering a search string, the system will match keywords in "global" mode, including content from various
+  protocols such as HTTP, SSH, FTP, etc. (e.g., HTTP/HTTPS protocol headers, body, SSL, title, and other protocol
+  banners).
+- Search strings are case-insensitive and will be segmented for matching (the search results page provides a "
+  segmentation" test feature). When using == for search, it enforces exact case-sensitive matching with strict syntax.
+- Please use quotes for search strings (e.g., "Cisco System" or 'Cisco System'). If the search string contains quotes,
+  use the escape character, e.g.,"a\"b". If the search string contains parentheses, use the escape character, e.g.,
+  portinfo\(\).
+
+### The logical operators of the syntax：
+
+- =， Search for assets containing keywords
+  title="knownsec"
+  Search for websites with titles containing Knownsec's assets
+- ==， Accurate search, indicating a complete match of keywords (case sensitive), can search for data with empty values
+  title=="knownsec"
+  Precise search, which means exact match of keywords (case sensitive), and can search for data with empty values Search
+  for assets with the website title "Knownsec"
+- ||， Enter "||" in the search box to indicate the logical operation of "or"
+  service="ssh" || service="http"
+  Search for SSH or HTTP data
+- &&， Enter "&&" in the search box to indicate the logical operation of "and"
+  device="router" && after="2020-01-01"
+  Search for routers after Jan 1, 2020
+- !=， Enter "!=" in the search box to indicate the logical operation of "not"
+  country="US" && subdivisions!="new york"
+  Search for data in united states excluding new york
+- ()， Enter "()" in the search box to indicate the logical operation of "priority processing"
+  (country="US" && port!=80) || (country="US" && title!="404 Not Found")
+  Search excluding port 80 in US or "404 not found" in the US
+- *，Fuzzy search, use * for search
+  title="*google"
+  Fuzzy search, use * to search Search for assets containing Knowsec in the website title, and the title can start with
+  any character
+
+### Grammatical keywords
+
+#### Geographical Location Search
+
+- country="CN"    Search for country assets
+  Input country abbreviations or names, e.g.
+  country="china"
+- subdivisions="beijing"  Search for assets in the specified administrative region
+  Input in English, e.g.
+  subdivisions="beijing"
+- city="changsha" Search for city assets
+  Input in English, e.g.
+  city="changsha"
+
+#### Certificate Search
+
+- ssl="google"    Search for assets with "google" string in ssl certificate Often used to search for corresponding
+  targets by product name and company name
+- ssl.cert.fingerprint="F3C98F223D82CC41CF83D94671CCC6C69873FABF" Search for certificate-related fingerprint assets
+- ssl.chain_count=3 Search for SSL chain count assets
+- ssl.cert.alg="SHA256-RSA"   Search for signature algorithms supported by certificates
+- ssl.cert.issuer.cn="pbx.wildix.com" Search for the common domain name of the user certificate issuer
+- ssl.cert.pubkey.rsa.bits=2048 Search for rsa_bits certificate public key bit number
+- ssl.cert.pubkey.ecdsa.bits=256 Search for ecdsa_bits certificate public key bit number
+- ssl.cert.pubkey.type="RSA"  Search for the public key type of the certificate
+- ssl.cert.serial="18460192207935675900910674501" Search for certificate serial number
+- ssl.cipher.bits="128"   Search for encryption suite bit number
+- ssl.cipher.name="TLS_AES_128_GCM_SHA256"    Search for encryption suite name
+- ssl.cipher.version="TLSv1.3"    Search for encryption suite version
+- ssl.version="TLSv1.3"   Search for the SSL version of the certificate
+- ssl.cert.subject.cn="example.com"   Search for the common domain name of the user certificate holder
+- ssl.jarm="29d29d15d29d29d00029d29d29d29dea0f89a2e5fb09e4d8e099befed92cfa"   Search for assets related to Jarm
+  Fingerprint content
+- ssl.ja3s=45094d08156d110d8ee97b204143db14 Find assets related to specific JA3S fingerprints
+
+#### IP or Domain Name Related Information Search
+
+- ip="8.8.8.8"    Search for assets related to the specified IPv4 address
+  ip="2600:3c00::f03c:91ff:fefc:574a" Search for assets related to specified IPv6 address
+- cidr="52.2.254.36/24"   Search for C-class assets of IP
+  cidr="52.2.254.36/16"is the B class of the IP, cidr="52.2.254.36/8"is the A class of the IP, e.g.
+  cidr="52.2.254.36/16"
+  cidr="52.2.254.36/8"
+- org="Stanford University"   Search for assets of related organizations Used to locate IP assets corresponding to
+  universities, structures, and large Internet companies
+- isp="China Mobile"  Search for assets of related network service providers Can be supplemented with org data
+- asn=42893 Search for IP assets related to corresponding ASN (Autonomous system number)
+- port=80 Search for related port assets Currently does not support simultaneous open multi-port target search
+- hostname="google.com"       Search for assets of related IP "hostname"
+- domain="baidu.com"  Search for domain-related assets Used to search domain and subdomain data
+
+- banner="FTP" Search by protocol messages Used for searching HTTP response header data
+- http.header="http"   Search by HTTP response header Used for searching HTTP response header data
+- http.header_hash="27f9973fe57298c3b63919259877a84d"  Search by the hash values calculated from HTTP header.
+- http.header.server="Nginx"   Search by server of the HTTP header Used for searching the server data in HTTP response
+  headers
+- http.header.version="1.2"    Search by version number in the HTTP header
+- http.header.status_code="200"    Search by HTTP response status code Search for assets with HTTP response status code
+  200 or other status codes, such as 302, 404, etc.
+- http.body="document" Search by HTML body
+- http.body_hash="84a18166fde3ee7e7c974b8d1e7e21b4"    Search by hash value calculated from HTML body
+
+#### Fingerprint Search
+
+- app="Cisco ASA SSL VPN" Search for Cisco ASA-SSL-VPN devices For more app rules, please refer to [object Object].
+  Entering keywords such as "Cisco" in the search box will display related app prompts
+- service="ssh"   Search for assets related to the specified service protocol Common service protocols include: http,
+  ftp,
+  ssh, telnet, etc. (other services can be found in the domain name sidebar aggregation display of search results)
+- device="router" Search for router-related device types Common types include router, switch, storage-misc, etc. (other
+  types can be found in the domain name sidebar aggregation display of search results)
+- os="RouterOS"   Search for related operating systems Common systems include Linux, Windows, RouterOS, IOS, JUNOS,
+  etc. (
+  other systems can be found in the domain name sidebar aggregation display of search results)
+- title="Cisco"   Search for data with "Cisco" in the title of the HTML content
+- industry="government"   Search for assets related to the specified industry type Common industry types include
+  technology, energy, finance, manufacturing, etc. (other types can be supplemented with org data)
+
+- product="Cisco"  Search for assets with "Cisco" in the component information Support mainstream asset component
+  search
+- protocol="TCP"   Search for assets with the transmission protocol as TCP Common transmission protocols include TCP,
+  UDP, TCP6, SCTP
+- is_honeypot="True"   Filter for honeypot assets
+
+#### Time Node or Interval Related Search
+
+- after="2020-01-01" && port="50050"  Search for assets with an update time after Jan 1, 2020 and a port 50050 Time
+  filters need to be combined with other filters
+- before="2020-01-01" && port="50050" Search for assets with an update time before Jan 1, 2020 and a port 50050 Time
+  filters need to be combined with other filters
+
+#### Dig
+
+- dig="baidu.com 220.181.38.148"  Search for assets with related dig content
+
+#### Iconhash
+
+- iconhash="f3418a443e7d841097c714d69ec4bcb8" Analyze the target data by MD5 and search for assets with related content
+  based on the icon Search for assets with the "google" icon
+- iconhash="1941681276"   Analyze the target data by MMH3 and search for assets with related content based on the icon
+  Search for assets with the "amazon" icon
+
+#### Filehash
+
+- filehash="0b5ce08db7fb8fffe4e14d05588d49d9" Search for assets with related content based on the parsed file data
+  Search
+  for assets parsed with "Gitlab"
+
+### Syntax Examples:
+
+- Search for all assets of China Merchants Group in Arabic
+  org="مكتب التجار الصيني" || ssl="مكتب التجار الصيني"
+
+- Search for Starlink devices
+  app=Starlink || device=Starlink
+
+- Search for network devices running http service on port 80
+  port=80 && service="http"
+
+- Search for network devices running ssl on port 443 in Nagoya
+  city=nagoya && port=443 && service=ssl
+
+- Search for network devices running Windows operating system in the United States
+  country=us && os=windows
+
+- Search for devices running Microsoft NTP application
+  app="Microsoft NTP"
+
+- Search for webcams in Tokyo
+  city=tokyo && device=webcam
+
+- Search for industrial control devices with component 6ES7 315-2EH14-0AB0 running on port 102
+  port=102 && module_id=6ES7 215-1BG40-0XB0
+
+- Search for assets indexed after 2020-01-01 with port 50050 open
+  after="2020-01-01" && port=50050
+
+- Search for assets in Delta, Canada
+  country=Canada && city=Delta
+
+- Search for assets in Poland with Linux system and port 22
+  os=linux && port=22 && country=PL
+
+- Search for FTP service with hostname example
+  service=ftp && hostname=example
+
+- Search for IPv4 assets
+  is_ipv4=true
+
+- Search for IPv6 assets
+  is_ipv6=true
+
+- Search for IP assets containing "FreeBSD", including both IPv4 and IPv6
+  FreeBSD && (is_ipv4=true || is_ipv6=true)
+
+- Search for website assets containing FreeBSD
+  FreeBSD && is_domain=true
+
+- Search for assets with "Knownsec" in the body
+  http.body="Knownsec"
+
+- Search for specific Header hash
+  http.header_hash="9763f6e29aa78e7ca2179ac82decbc25"
+"""

mcp_zoomeye_org/server.py

@@ -0,0 +1,181 @@
+import json
+import os
+from enum import Enum
+from typing import Optional, Sequence
+
+import httpx
+from dotenv import load_dotenv
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent, ImageContent, EmbeddedResource
+
+from .prompts import SEARCH_SYNTAX_GUIDE
+
+load_dotenv()
+
+
+class ZoomeyeTools(str, Enum):
+    ZOOMEYE_SEARCH = "zoomeye_search"
+    """Search query for ZoomEye."""
+    ZOOMEYE_VULDB_BY_ID = "zoomeye_vuldb_by_id"
+    """Query vulnerability by ID."""
+
+    ZOOMEYE_VULDB_BY_KEYWORD = "zoomeye_vuldb_by_keyword"
+    """Query vulnerability by keyword."""
+
+
+def zoomeye_search(qbase64: str, page: int = 1, pagesize: int = 10, fields: str = "", sub_type: str = "",
+                   facets: str = "", ignore_cache: bool = False):
+    """Search query for ZoomEye.
+    ### Parameters
+    |Parameter|Type|Required|Description|
+    | ----- | ----- | ----- | ----- |
+    |qbase64|string|true|Base64 encoded query string. For more, refer to Related references.|
+    |fields|string|false|The fields to return, separated by commas. Default: ip, port, domain, update_time. For more, refer to Response field description|
+    |sub_type|string|false|Data type, supports v4, v6, and web. Default is v4.|
+    |page|integer|false|View asset page number|
+    |pagesize|integer|false|Number of records per page, default is 10, maximum is 10,000.|
+    |facets|string|false|Statistical items, separated by commas if there are multiple. Supports country, subdivisions, city, product, service, device, OS, and port.|
+    |ignore_cache|boolean|false|Whether to ignore the cache. false, supported by Business plan and above.|
+    """
+    service = ZoomeyeService()
+    return service.query(qbase64=qbase64, page=page, pagesize=pagesize, fields=fields, sub_type=sub_type, facets=facets,
+                         ignore_cache=ignore_cache)
+
+
+class ZoomeyeService:
+    def __init__(self, key: Optional[str] = None):
+        self.key = key
+        self.base_url = "https://api.zoomeye.org"
+        if not self.key:
+            self.key = os.getenv("ZOOMEYE_API_KEY")
+
+    async def get_client(self):
+        proxy = None
+        https_proxy = os.getenv("https_proxy")
+        http_proxy = os.getenv("http_proxy")
+        if https_proxy or http_proxy:
+            proxy = https_proxy or http_proxy
+        return httpx.AsyncClient(proxy=proxy)
+
+    async def query(self, qbase64, page=1, pagesize=10, fields=None, sub_type=None, facets=None, ignore_cache=None):
+        """Query ZoomEye API with the given parameters.
+        
+        Args:
+            qbase64 (str): Base64 encoded query string.
+            page (int, optional): Page number. Defaults to 1.
+            pagesize (int, optional): Number of records per page. Defaults to 10.
+            fields (str, optional): Fields to return, comma separated. Defaults to None.
+            sub_type (str, optional): Data type (v4, v6, web). Defaults to None.
+            facets (str, optional): Statistical items, comma separated. Defaults to None.
+            ignore_cache (bool, optional): Whether to ignore cache. Defaults to None.
+            
+        Returns:
+            dict: The API response data.
+            
+        Raises:
+            ValueError: If API key is not provided or API request fails.
+        """
+        if not self.key:
+            raise ValueError(
+                "ZoomEye API key is required. Please set it via environment variable ZOOMEYE_API_KEY or pass it to the constructor.")
+
+        url = f"{self.base_url}/v2/search"
+        headers = {"API-KEY": self.key, "Content-Type": "application/json"}
+
+        # Prepare request data
+        data = {"qbase64": qbase64, "page": page, "pagesize": pagesize}
+
+        # Add optional parameters if provided
+        if fields:
+            data["fields"] = fields
+        if sub_type:
+            data["sub_type"] = sub_type
+        if facets:
+            data["facets"] = facets
+        if ignore_cache is not None:
+            data["ignore_cache"] = ignore_cache
+
+        try:
+            client = await self.get_client()
+            async with client:
+                response = await client.post(url, headers=headers, json=data)
+                response.raise_for_status()  # Raise exception for HTTP errors
+                return response.json()
+        except httpx.HTTPError as e:
+            raise ValueError(f"Error querying ZoomEye API: {str(e)}")
+        except json.JSONDecodeError:
+            raise ValueError("Invalid JSON response from ZoomEye API")
+
+
+async def serve(key: str | None = None) -> None:
+    server = Server("mcp-zoomeye")
+    zoomeye_service = ZoomeyeService(key=key)
+
+    @server.list_tools()
+    async def list_tools() -> list[Tool]:
+        """Tool list"""
+        return [Tool(name=ZoomeyeTools.ZOOMEYE_SEARCH, description=SEARCH_SYNTAX_GUIDE, inputSchema={"type": "object",
+                                                                                                     "properties": {
+                                                                                                         "qbase64": {
+                                                                                                             "type": "string",
+                                                                                                             "description": "Base64 encoded query string for ZoomEye search", },
+                                                                                                         "page": {
+                                                                                                             "type": "integer",
+                                                                                                             "description": "View asset page number, default is 1",
+                                                                                                             "default": 1},
+                                                                                                         "pagesize": {
+                                                                                                             "type": "integer",
+                                                                                                             "description": "Number of records per page, default is 10, maximum is 1000",
+                                                                                                             "default": 10,
+                                                                                                             "maximum": 1000},
+                                                                                                         "fields": {
+                                                                                                             "type": "string",
+                                                                                                             "description": "The fields to return, separated by commas. Default: ip, port, domain, update_time"},
+                                                                                                         "sub_type": {
+                                                                                                             "type": "string",
+                                                                                                             "description": "Data type, supports v4, v6, and web. Default is v4",
+                                                                                                             "enum": [
+                                                                                                                 "v4",
+                                                                                                                 "v6",
+                                                                                                                 "web"]},
+                                                                                                         "facets": {
+                                                                                                             "type": "string",
+                                                                                                             "description": "Statistical items, separated by commas if there are multiple. Supports country, subdivisions, city, product, service, device, OS, and port"},
+                                                                                                         "ignore_cache": {
+                                                                                                             "type": "boolean",
+                                                                                                             "description": "Whether to ignore the cache. Supported by Business plan and above"}},
+                                                                                                     "required": [
+                                                                                                         "qbase64"], }, )]
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict) -> Sequence[TextContent | ImageContent | EmbeddedResource]:
+        """Handle tool calls for zoomeye queries."""
+        try:
+            match name:
+                case ZoomeyeTools.ZOOMEYE_SEARCH:
+                    qbase64 = arguments.get("qbase64")
+                    if not qbase64:
+                        raise ValueError("Missing required argument: qbase64")
+
+                    page = arguments.get("page", 1)
+                    pagesize = arguments.get("pagesize", 10)
+                    fields = arguments.get("fields")
+                    sub_type = arguments.get("sub_type")
+                    facets = arguments.get("facets")
+                    ignore_cache = arguments.get("ignore_cache")
+
+                    result = await zoomeye_service.query(qbase64=qbase64, page=page, pagesize=pagesize, fields=fields,
+                                                         sub_type=sub_type, facets=facets, ignore_cache=ignore_cache)
+                case _:
+                    raise ValueError(f"Unknown tool: {name}")
+
+            formatted_result = json.dumps(result, ensure_ascii=False, indent=2)
+            return [TextContent(type="text", text=formatted_result if result is not None else "")]
+
+        except Exception as e:
+            raise ValueError(f"Error processing mcp-zoomeye-org query: {str(e)}")
+
+    options = server.create_initialization_options()
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, options)

mcp_zoomeye_org-0.1.0.dist-info/METADATA

@@ -0,0 +1,440 @@
+Metadata-Version: 2.4
+Name: mcp-zoomeye-org
+Version: 0.1.0
+Summary: A Model Context Protocol server providing tools for ZoomEye queries for LLMs
+Author-email: zoomeye team <zoomeye@knownsec.com>
+License: MIT
+Keywords: llm,mcp,zoomeye
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: requests>=2.32.3
+Description-Content-Type: text/markdown
+
+# 🚀 ZoomEye MCP Server
+
+A Model Context Protocol (MCP) server that provides network asset information based on query conditions. This server allows Large Language Models (LLMs) to obtain network asset information by querying ZoomEye using dorks and other search parameters.
+
+## 🔔 Announcement
+
+🎉 We are excited to announce the official open-source release of **ZoomEye MCP Server** — a powerful Model Context Protocol (MCP) server that brings real-time cyber asset intelligence to AI assistants and development environments.
+
+🚀 Free Trial: 7-Day FREE Access to ZoomEye MCP!
+Experience ZoomEye MCP — the AI-powered cyberspace asset search engine — absolutely free for 7 days!
+
+🔍 Search global internet assets, track real-time changes, and unlock AI-driven insights — all in one place.
+
+👉 How to claim:
+
+1. Follow us on Twitter: [@zoomeye_team](https://x.com/zoomeye_team)
+2. DM us "MCP" and your MCP setup screenshot
+3. Get instant access to your 7-day membership
+
+🎁 Limited-time free trial — explore the power of AI asset search today!
+
+💡 Provide insightful feedback that gets officially adopted, and you'll unlock **even more rewards**!
+
+🔧 Fully compatible with leading MCP environments:
+
+- Claude Desktop
+- Cursor
+- Windsurf
+- Cline
+- Continue
+- Zed
+- Cherry Studio
+- Chatbox
+
+🔗 Explore ZoomEye MCP Server on:
+
+- GitHub: [knownsec/mcp_zoomeye_org](https://github.com/knownsec/mcp_zoomeye_org)
+- MCP.so: [mcp.so/server/mcp_zoomeye](https://mcp.so/server/mcp_zoomeye/zoomeye-ai)
+- Smithery: [smithery.ai/server/@zoomeye-ai/mcp_zoomeye](https://smithery.ai/server/@zoomeye-ai/mcp_zoomeye)
+- Cursor Directory: [cursor.directory/mcp/zoomeye](https://cursor.directory/mcp/zoomeye)
+- Pulse MCP: [pulsemcp.com/servers/zoomeye](https://www.pulsemcp.com/servers/zoomeye)
+- Glama MCP: [glama.ai/mcp/servers](https://glama.ai/mcp/servers)
+
+We welcome everyone to use, explore, and contribute!
+
+## 🔑 How can I get a ZoomEye API key?
+
+To use this MCP server, you’ll need a ZoomEye API key.
+
+1. Go to https://www.zoomeye.org
+2. Register or log in
+3. Click your avatar → **Profile**
+4. Copy your **API-KEY**
+5. Set the environment variable:
+   
+   `export ZOOMEYE_API_KEY="your_api_key_here"`
+
+![zoomeye1](./zoomeye1.png)
+
+![zoomeye2](./zoomeye2.png)
+
+## Features
+
+- Query ZoomEye for network asset information using dorks
+- Caching mechanism to improve performance and reduce API calls
+- Automatic retry mechanism for failed API requests
+- Comprehensive error handling and logging
+
+## Available Tools
+
+- `zoomeye_search` - Get network asset information based on query conditions.
+  - Required parameters:
+    - `qbase64` (string): Base64 encoded query string for ZoomEye search
+  - Optional parameters:
+    - `page` (integer): View asset page number, default is 1
+    - `pagesize` (integer): Number of records per page, default is 10, maximum is 1000
+    - `fields` (string): The fields to return, separated by commas
+    - `sub_type` (string): Data type, supports v4, v6, and web. Default is v4
+    - `facets` (string): Statistical items, separated by commas if there are multiple
+    - `ignore_cache` (boolean): Whether to ignore the cache
+
+## Usage Guide
+
+### Basic Usage
+
+Once the server is running, you can interact with it through your AI assistant or development environment. Here's how to use it:
+
+1. **Start the server** using one of the installation methods above
+2. **Configure your AI assistant** (Claude Desktop, Cursor, Windsurf, Cline, Continue, Zed, etc.) to use the server
+3. **Query network information** using natural language
+
+![searchexample](example.png)
+
+### Search Syntax Guide
+
+- Search Scope covers devices (IPv4, IPv6) and websites (domains).
+- When entering a search string, the system will match keywords in "global" mode, including content from various
+  protocols such as HTTP, SSH, FTP, etc. (e.g., HTTP/HTTPS protocol headers, body, SSL, title, and other protocol
+  banners).
+- Search strings are case-insensitive and will be segmented for matching (the search results page provides a "
+  segmentation" test feature). When using == for search, it enforces exact case-sensitive matching with strict syntax.
+- Please use quotes for search strings (e.g., "Cisco System" or 'Cisco System'). If the search string contains quotes,
+  use the escape character, e.g.,"a\"b". If the search string contains parentheses, use the escape character, e.g.,
+  portinfo\(\).
+
+You can see more detailed search syntax rules in [prompts.py](src/mcp_zoomeye_org/prompts.py).
+
+For more information on the ZoomEye Search API, refer to the [ZoomEye API v2 documentation](https://www.zoomeye.org/doc).
+
+## Getting Started
+
+### Prerequisites
+
+1. **ZoomEye API Key**
+   
+   - Register for an account at [ZoomEye](https://www.zoomeye.org/)
+   - Obtain your API key from your account settings
+   - The API key will be used to authenticate your requests to the ZoomEye API
+2. **Python Environment**
+   
+   - Python 3.10 or higher is required
+   - Alternatively, you can use Docker to run the server without installing Python
+
+## Installation
+
+### Using PIP
+
+Alternatively, you can install `mcp-zoomeye-org` via pip:
+
+```bash
+pip install mcp-zoomeye-org
+```
+
+After installation, you can run it as a script using the following command:
+
+```bash
+python -m mcp_zoomeye_org
+```
+
+### Using uv
+
+[`uv`](https://docs.astral.sh/uv/) is a fast Python package installer and resolver written in Rust. It's a modern alternative to pip that offers significant performance improvements.
+
+#### Installation of uv
+
+```bash
+# Install uv using curl (macOS/Linux)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Or using PowerShell (Windows)
+irm https://astral.sh/uv/install.ps1 | iex
+
+# Or using Homebrew (macOS)
+brew install uv
+```
+
+#### Using uvx to run mac-zoomeye-org
+
+No specific installation is required when using [`uvx`](https://docs.astral.sh/uv/guides/tools/), which allows you to run Python packages directly:
+
+#### Installing with uv
+
+Alternatively, you can install the package using uv:
+
+```bash
+# Install in the current environment
+uv pip install mac-zoomeye-org
+
+# Or create and install in a new virtual environment
+uv venv
+uv pip install mac-zoomeye-org
+```
+
+## Configuration
+
+### Environment Variables
+
+The ZoomEye MCP server requires the following environment variable:
+
+- `ZOOMEYE_API_KEY`: Your ZoomEye API key for authentication
+
+You can set this environment variable in several ways:
+
+1. **Export in your shell session**:
+   
+   ```bash
+   export ZOOMEYE_API_KEY="your_api_key_here"
+   ```
+
+### Configure Claude.app
+
+Add the following in Claude settings:
+
+<details>
+<summary>Using uvx</summary>
+
+```json
+"mcpServers": {
+  "zoomeye": {
+    "command": "uvx",
+    "args": ["mac-zoomeye-org"],
+    "env": {
+        "ZOOMEYE_API_KEY": "your_api_key_here"
+    }
+  }
+}
+```
+
+</details>
+
+
+<details>
+<summary>Installed via pip</summary>
+
+```json
+"mcpServers": {
+  "zoomeye": {
+    "command": "python",
+    "args": ["-m", "mcp_server_zoomeye"],
+    "env": {
+        "ZOOMEYE_API_KEY": "your_api_key_here"
+    }
+  }
+}
+```
+
+</details>
+
+### Configure Zed
+
+Add the following in Zed's settings.json:
+
+<details>
+<summary>Using uvx</summary>
+
+```json
+"context_servers": [
+  "mac-zoomeye-org": {
+    "command": "uvx",
+    "args": ["mac-zoomeye-org"],
+    "env": {
+        "ZOOMEYE_API_KEY": "your_api_key_here"
+    }
+  }
+],
+```
+
+</details>
+
+<details>
+<summary>Installed via pip</summary>
+
+```json
+"context_servers": {
+  "mac-zoomeye-org": {
+    "command": "python",
+    "args": ["-m", "mcp_server_zoomeye"],
+    "env": {
+        "ZOOMEYE_API_KEY": "your_api_key_here"
+    }
+  }
+},
+```
+
+</details>
+
+## Example Interactions
+
+### Example 1: Retrieve global Apache Tomcat assets
+
+```json
+{
+  "name": "zoomeye_search",
+  "arguments": {
+    "qbase64": "app=\"Apache Tomcat\""
+  }
+}
+```
+
+Response:
+
+```json
+{
+  "code": 60000,
+  "message": "success",
+  "total": 163139107,
+  "query": "app=\"Apache Tomcat\"",
+  "data": [
+    {
+      "url": "https://1.1.1.1:443",
+      "ssl.jarm": "29d29d15d29d29d00029d29d29d29dea0f89a2e5fb09e4d8e099befed92cfa",
+      "ssl.ja3s": "45094d08156d110d8ee97b204143db14",
+      "iconhash_md5": "f3418a443e7d841097c714d69ec4bcb8",
+      "robots_md5": "0b5ce08db7fb8fffe4e14d05588d49d9",
+      "security_md5": "0b5ce08db7fb8fffe4e14d05588d49d9",
+      "ip": "1.1.1.1",
+      "domain": "www.google.com",
+      "hostname": "SPACEX",
+      "os": "windows",
+      "port": 443,
+      "service": "https",
+      "title": ["GoogleGoogle appsGoogle Search"],
+      "version": "1.1.0",
+      "device": "webcam",
+      "rdns": "c01031-001.cust.wallcloud.ch",
+      "product": "OpenSSD",
+      "header": "HTTP/1.1 302 Found Location: https://www.google.com/?gws_rd=ssl Cache-Control: private...",
+      "header_hash": "27f9973fe57298c3b63919259877a84d",
+      "body": "HTTP/1.1 302 Found Location: https://www.google.com/?gws_rd=ssl Cache-Control: private...",
+      "body_hash": "84a18166fde3ee7e7c974b8d1e7e21b4",
+      "banner": "SSH-2.0-OpenSSH_7.6p1 Ubuntu-4ubuntu0.3",
+      "update_time": "2024-07-03T14:34:10",
+      "header.server.name": "nginx",
+      "header.server.version": "1.8.1",
+      "continent.name": "Europe",
+      "country.name": "Germany",
+      "province.name": "Hesse",
+      "city.name": "Frankfurt",
+      "lon": "118.753262",
+      "lat": "32.064838",
+      "isp.name": "aviel.ru",
+      "organization.name": "SERVISFIRST BANK",
+      "zipcode": "210003",
+      "idc": 0,
+      "honeypot": 0,
+      "asn": 4837,
+      "protocol": "tcp",
+      "ssl": "SSL Certificate Version: TLS 1.2 CipherSuit: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256...",
+      "primary_industry": "Finance",
+      "sub_industry": "bank",
+      "rank": 60
+    }
+  ]
+}
+```
+
+## Debugging and Troubleshooting
+
+### Using MCP Inspector
+
+The Model Context Protocol Inspector is a tool that helps debug MCP servers by simulating client interactions. You can use it to test your ZoomEye MCP server:
+
+```bash
+# For uvx installation
+npx @modelcontextprotocol/inspector uvx mac-zoomeye-org
+
+# If developing locally
+cd path/to/servers/src/mcp_server_zoomeye
+npx @modelcontextprotocol/inspector uv run mac-zoomeye-org
+```
+
+### Common Issues
+
+1. **Authentication Errors**
+   
+   - Ensure your ZoomEye API key is correct and properly set as an environment variable
+   - Check that your API key has not expired or been revoked
+2. **Connection Issues**
+   
+   - Verify your internet connection
+   - Check if the ZoomEye API is experiencing downtime
+3. **No Results**
+   
+   - Your query might be too specific or contain syntax errors
+   - Try simplifying your query or using different search terms
+4. **Rate Limiting**
+   
+   - ZoomEye API has rate limits based on your account type
+   - Space out your requests or upgrade your account for higher limits
+
+## Advanced Usage
+
+### Caching
+
+The ZoomEye MCP server implements caching to improve performance and reduce API calls:
+
+- Responses are cached based on the query parameters
+- Cache duration is configurable (default: 1 hour)
+- You can bypass the cache by setting `ignore_cache` to `true` in your query
+
+### Custom Fields
+
+You can request specific fields in your query results by using the `fields` parameter:
+
+```json
+{
+  "name": "zoomeye_search",
+  "arguments": {
+    "qbase64": "app=\"Apache\"",
+    "fields": "ip,port,domain,service,os,country,city"
+  }
+}
+```
+
+### Pagination
+
+For queries that return many results, you can paginate through them:
+
+```json
+{
+  "name": "zoomeye_search",
+  "arguments": {
+    "qbase64": "app=\"Apache\"",
+    "page": 2,
+    "pagesize": 20
+  }
+}
+```
+
+## Contributing
+
+We encourage contributions to mac-zoomeye-org to help expand and improve its functionality. Whether it's adding new related tools, enhancing existing features, or improving documentation, your input is valuable.
+
+For examples of other MCP servers and implementation patterns, see:
+https://github.com/modelcontextprotocol/servers
+
+Pull requests are welcome! Feel free to contribute new ideas, bug fixes, or enhancements to make mac-zoomeye-org more robust and practical.
+
+## License
+
+mac-zoomeye-org is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more information, see the LICENSE file in the project repository.

mcp_zoomeye_org-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+mcp_zoomeye_org/__init__.py,sha256=M9-z6h2rrMvPUTCtAw0j_iGphrD8KiFQXylwBfa0qj8,440
+mcp_zoomeye_org/__main__.py,sha256=DSxm3VDrBM5-hCe_ccFSbTu2jgVO64XuWJxLDR9iBFU,40
+mcp_zoomeye_org/prompts.py,sha256=swFBgG77S9n1OMIUyuSyWDRWSmnuG3ZE24e5r1Rp26w,10308
+mcp_zoomeye_org/server.py,sha256=V5umTNmAAERVWEfz7qlP8aKphzD36j1nj0jYUIs0CCE,10759
+mcp_zoomeye_org-0.1.0.dist-info/METADATA,sha256=jAc7iufy5F43CS7Yg0cu6F5GRvcY6a2bubWub3v2Ft0,12950
+mcp_zoomeye_org-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mcp_zoomeye_org-0.1.0.dist-info/entry_points.txt,sha256=g8ocdd0a8JWOz6QbOTbFOKXKkDRppzfp3cxpNtNpjfI,57
+mcp_zoomeye_org-0.1.0.dist-info/RECORD,,

mcp_zoomeye_org-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_zoomeye_org-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-zoomeye-org = mcp_zoomeye_org:main