iflow-mcp_ahnlabio-bicscan-mcp 0.1.0__py3-none-any.whl

bicscan_mcp/__init__.py

@@ -0,0 +1,10 @@
+import asyncio
+
+from . import server
+
+
+def main() -> None:
+    asyncio.run(server.main())
+
+
+__all__ = ["main", "server"]

bicscan_mcp/server.py

@@ -0,0 +1,131 @@
+import asyncio
+import logging
+import os
+from typing import Any
+from urllib.parse import urljoin
+
+import httpx
+from dotenv import load_dotenv
+from mcp.server import FastMCP
+
+load_dotenv()
+
+logger = logging.getLogger("bicscan-mcp")
+logger.setLevel(logging.INFO)
+
+# add console handler
+console_handler = logging.StreamHandler()
+formatter = logging.Formatter(
+    "%(asctime)s - %(name)s:%(lineno)s - %(levelname)s - %(message)s"
+)
+console_handler.setFormatter(formatter)
+logger.addHandler(console_handler)
+
+# add file handler
+# file_handler = logging.FileHandler("./data/bicscan-mcp.log")
+# file_handler.setFormatter(formatter)
+# logger.addHandler(file_handler)
+
+# Add more detailed logging
+logger.info("FastMCP server initialized with name: BICScan")
+
+# Initialize FastMCP server
+mcp = FastMCP("BICScan")
+
+# Constants
+BICSCAN_API_BASE = "https://api.bicscan.io"
+BICSCAN_API_KEY = os.getenv("BICSCAN_API_KEY")
+TEST_MODE = os.getenv("TEST_MODE", "false").lower() == "true"
+
+
+async def post_request(
+    endpoint: str, data: dict[str, Any] | None = None
+) -> dict[str, Any] | None:
+    """Make a request to BICScan API with proper error handling."""
+    # Test mode: return mock data
+    if TEST_MODE:
+        logger.info(f"TEST_MODE: Returning mock data for {endpoint}")
+        return {
+            "summary": {
+                "bicscan_score": 0,
+                "risk_level": "low",
+                "address": data.get("query", "unknown") if data else "unknown"
+            },
+            "assets": [],
+            "status": "test_mode"
+        }
+
+    headers = {
+        "User-Agent": "bicscan-mcp/1.0",
+        "Accept": "application/json",
+        "X-Api-Key": BICSCAN_API_KEY,
+    }
+    url = urljoin(BICSCAN_API_BASE, endpoint)
+
+    async with httpx.AsyncClient() as client:
+        try:
+            logger.info(f"Making request to {url}")
+            logger.debug(f"{headers=} {data=}")
+            response = await client.post(url, headers=headers, json=data, timeout=30)
+            response.raise_for_status()
+            logger.info(f"Received response: {response.status_code}")
+            return response.json()
+        except httpx.HTTPStatusError as http_err:
+            logger.error(f"Received response: {http_err}, {response.text}")
+            return response.json()
+        except Exception as e:
+            logger.exception(f"Received response: {e}, {response.text}")
+            return {}
+
+
+@mcp.tool()
+async def get_risk_score(address: str) -> dict:
+    """Get Risk Score for Crypto, Domain Name, ENS, CNS, KNS or even Hostname Address
+
+    Args:
+        address: EOA, CA, ENS, CNS, KNS or even HostName
+    Returns:
+        Dict: where summary.bicscan_score is from 0 to 100. 100 is high risk.
+    """
+
+    logger.info(f"Getting risk score for address: {address}")
+    endpoint = "/v1/scan"
+    data = {
+        "query": address,
+        "sync": True,
+        "assets": False,
+    }
+
+    return await post_request(endpoint, data=data)
+
+
+@mcp.tool()
+async def get_assets(address: str) -> dict:
+    """Get Assets holdings by CryptoAddress
+
+    Args:
+        address: EOA, CA, ENS, CNS, KNS.
+    Returns:
+        Dict: where assets is a list of assets
+    """
+
+    logger.info(f"Getting assets for address: {address}")
+    endpoint = "/v1/scan"
+    data = {
+        "query": address,
+        "sync": True,
+        "assets": True,
+        "engines": ["ofac"],
+    }
+
+    return await post_request(endpoint, data=data)
+
+
+async def main() -> None:
+    """Run the MCP BICScan server."""
+    # Import here to avoid issues with event loops
+    await mcp.run_stdio_async()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

iflow_mcp_ahnlabio_bicscan_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: iflow-mcp_ahnlabio-bicscan-mcp
+Version: 0.1.0
+Summary: BICScan MCP Server
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp[cli]>=1.5.0
+Requires-Dist: python-dotenv>=1.0.1
+Description-Content-Type: text/markdown
+
+# BICScan MCP Server
+
+A powerful and efficient Blockchain address risk scoring API MCP Server, leveraging the BICScan API to provide comprehensive risk assessments and asset information for blockchain addresses, domains, and decentralized applications (dApps).
+
+🎉 We're listed on https://github.com/modelcontextprotocol/servers for official integration 🎉
+
+
+https://github.com/user-attachments/assets/f9425429-1cb1-4508-b962-81351075258b
+
+## Key Features
+- **Risk Scoring**: Obtain risk scores for various blockchain entities, including crypto addresses, domain names, and decentralized application URLs, with scores ranging from 0 to 100, where 100 indicates high risk.
+- **Asset Information**: Retrieve detailed asset holdings for specified crypto addresses, including cryptocurrencies and tokens, with support for multiple blockchain networks.
+- **Real-time Scanning**: Utilize the BICScan API to perform real-time scans and receive up-to-date information on potential risks and asset holdings.
+- **Secure and Reliable**: Built with robust error handling and logging to ensure secure and reliable operations.
+
+## Example Output
+
+## How to use.
+
+You con either use Python with `uv` or `docker` depending on your preference.
+
+Depending on your environment, you can choose to use either `uv`, `docker`, or `uvx`.
+
+### 1. Running with `uv`
+
+#### 1-1. Requirements
+1. Python 3.10 or higher
+2. uv 0.6.x
+3. git
+
+#### 1.2. Clone the repository
+```sh
+git clone https://github.com/ahnlabio/bicscan-mcp
+```
+
+#### 1.3. Config `claude_desktop_config.json`
+
+Append following to `claude_desktop_config.json`.
+
+Make sure to replace:
+ - `YOUR_BICSCAN_REPO_DIR_HERE`: to something like `C:\\Users\\ABC\\repo\\bicscan-mcp` or `/home/abc/repo/bicscan-mcp` similarly.
+ - `YOUR_BICSCAN_API_KEY_HERE`: to free API key can be obtained from https://bicscan.io (details below)
+
+```json
+{
+  "mcpServers": {
+    ... some other mcp servers ...,
+    "bicscan": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "YOUR_BICSCAN_REPO_DIR_HERE",
+        "run",
+        "bicscan-mcp"
+      ],
+      "env": {
+        "BICSCAN_API_KEY": "YOUR_BICSCAN_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+### 2. Running with `Docker`
+
+#### 2.1. Requirements
+1. Docker environment
+
+#### 2.2. Clone the repository
+```sh
+git clone https://github.com/ahnlabio/bicscan-mcp
+```
+
+#### 2.3. Build Docker image.
+
+Just run `make` in the repository directory to build docker image.
+
+#### 2.4. Config
+Append following to `claude_desktop_config.json`
+
+Make sure to replace:
+ - `YOUR_BICSCAN_API_KEY_HERE` to API key obtained from https://bicscan.io (details below)
+
+```json
+{
+  "mcpServers": {
+    ... some other mcp servers ...,
+    "bicscan": {
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "--interactive",
+        "--env", "BICSCAN_API_KEY=YOUR_BICSCAN_API_KEY_HERE",
+        "bicscan-mcp"
+      ]
+    }
+  }
+}
+```
+
+### 3. Running with `uvx`
+
+#### 3.1. Requirements
+1. Python 3.10 or higher
+2. uv 0.6.x
+3. git
+
+#### 3.2. Config `claude_desktop_config.json`
+
+Append following to `claude_desktop_config.json`.
+
+Make sure to replace:
+ - `YOUR_BICSCAN_API_KEY_HERE`: to free API key can be obtained from https://bicscan.io (details below)
+
+```json
+{
+  "mcpServers": {
+    ... some other mcp servers ...,
+    "bicscan": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/ahnlabio/bicscan-mcp",
+        "bicscan-mcp"
+      ],
+      "env": {
+        "BICSCAN_API_KEY": "YOUR_BICSCAN_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+## How to obtain Free BICScan API Key?
+
+1. Visit `https://bicscan.io` and register.
+2. Go to profile and create "Create App"
+3. Enter name and description on your choice.
+4. Replace `YOUR_BICSCAN_API_KEY_HERE` part from above config to your newly obtained key.
+5. restart the Claude Desktop.

iflow_mcp_ahnlabio_bicscan_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+bicscan_mcp/__init__.py,sha256=LeC-t6pNHUKezhSnITJBHAelVaZhng01BoheShm0nn0,131
+bicscan_mcp/server.py,sha256=aiRgBRTdCh_XsSO83Xs8-3lXWSr3uo3q7AwUguJ8uxY,3638
+iflow_mcp_ahnlabio_bicscan_mcp-0.1.0.dist-info/METADATA,sha256=d6GY0hoX4UcXKXborEkXfYocVwvDO92Rflf13-ihioU,4136
+iflow_mcp_ahnlabio_bicscan_mcp-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+iflow_mcp_ahnlabio_bicscan_mcp-0.1.0.dist-info/entry_points.txt,sha256=9WTgz31t0pNUlkkrkb9IkS08pRROWkKC1FRy1BNQ8q0,49
+iflow_mcp_ahnlabio_bicscan_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=QmypwNL8ez3ouD9DIskbTWQ4279KbPrc52qWuh_6y54,1088
+iflow_mcp_ahnlabio_bicscan_mcp-0.1.0.dist-info/RECORD,,

iflow_mcp_ahnlabio_bicscan_mcp-0.1.0.dist-info/WHEEL

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

iflow_mcp_ahnlabio_bicscan_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bicscan-mcp = bicscan_mcp:main

iflow_mcp_ahnlabio_bicscan_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AhnLab Blockchain Company, INC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.