findgoods-mcp-server 0.2.0__tar.gz

findgoods_mcp_server-0.2.0/.env.example

@@ -0,0 +1,6 @@
+# WholesaleShopAPI 连接配置
+WHOLESALE_SHOP_API_URL=https://api.wholesale.goodsmart.jp
+
+# MCP Server 配置
+MCP_SERVER_HOST=0.0.0.0
+MCP_SERVER_PORT=8000

findgoods_mcp_server-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: python -m pytest tests/ -q

findgoods_mcp_server-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write   # 创建 GitHub Release
+  id-token: write   # PyPI Trusted Publishing (OIDC)
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install build tool
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/findgoods-mcp-server
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

findgoods_mcp_server-0.2.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Environment
+.env
+.venv/
+venv/
+
+# IDE & Tools
+.vscode/
+.idea/
+.claude/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+Thumbs.db

findgoods_mcp_server-0.2.0/CLAUDE.md

@@ -0,0 +1,149 @@
+# CLAUDE.md
+
+本文件为 Claude Code (claude.ai/code) 提供本仓库的开发指引。
+
+## 项目概述
+
+FindGoods MCP Server — GoodsMart Shop API 的 MCP 薄封装层。将日本二次元商品批发能力通过 MCP 协议暴露给 AI Agent。不建独立数据库，所有数据实时调用 GoodsMart Shop API。
+
+## 构建和运行
+
+```bash
+# 安装依赖
+pip install -e ".[dev]"
+
+# MCP Server 模式（stdio transport，供 MCP 客户端连接）
+python -m findgoods_mcp
+
+# CLI 模式（供 AI Agent 直接 shell 调用，token 高效）
+findgoods --help
+findgoods search-products --keyword "フィギュア"
+findgoods login --email user@example.com --password xxx
+
+# 也可通过 python -m 进入 CLI 模式
+python -m findgoods_mcp cli search-products --keyword "フィギュア"
+
+# 用 MCP Inspector 测试
+npx @modelcontextprotocol/inspector python -m findgoods_mcp
+
+# 运行测试
+python -m pytest tests/ -q
+```
+
+## 技术栈
+
+- **语言**: Python 3.11+
+- **MCP 框架**: FastMCP >= 2.0.0（`@mcp.tool()` 装饰器）
+- **HTTP 客户端**: httpx（异步调用 GoodsMart Shop API）
+- **配置**: pydantic-settings + .env
+- **CLI 框架**: click >= 8.1（`findgoods` 命令行入口）
+- **包管理**: pyproject.toml + hatchling
+- **测试**: pytest + pytest-asyncio
+
+## 架构
+
+```
+# MCP 模式（schema 注入 context，适合 MCP 客户端）
+AI Agent ←MCP Protocol→ FastMCP Server → WholesaleShopClient → Shop API
+
+# CLI 模式（shell exec，节省 90%+ token，适合 Claude Code 等）
+AI Agent → shell exec "findgoods <cmd>" → WholesaleShopClient → Shop API
+
+src/findgoods_mcp/
+├── server.py          # FastMCP 实例 + Tool 注册（MCP 模式）
+├── cli.py             # Click CLI 入口 — 自动从 MCP 注册表生成命令（CLI 模式）
+├── config.py          # 环境变量配置
+├── __main__.py        # 双模式入口: python -m findgoods_mcp [cli]
+├── api_client/
+│   └── client.py      # WholesaleShopClient — HTTP 请求 + JWT Token 自动管理
+├── tools/
+│   ├── auth.py        # 注册、登录、密码重置、认证检查 (6 tools)
+│   ├── search.py      # 商品搜索、分类、制造商/作品列表 (4 tools)
+│   ├── product.py     # 商品详情、关联商品 (2 tools)
+│   ├── cart.py        # 购物车 CRUD (5 tools)
+│   ├── checkout.py    # 结算下单、支付方式、支付链接 (4 tools)
+│   ├── order.py       # 订单查询、订单明细统计 (5 tools)
+│   ├── address.py     # 配送地址 CRUD (5 tools)
+│   ├── shipment.py    # 出库管理、运费计算、运费支付 (6 tools)
+│   ├── wishlist.py    # 收藏夹 CRUD (4 tools)
+│   ├── pay.py         # GM Pay 余额、交易、充值 (4 tools)
+│   └── profile.py     # 用户档案、仪表板、报价、公告、问询 (8 tools)
+└── utils/
+    └── formatting.py  # 商品数据格式化（价格计算、库存判断）
+```
+
+**总计 53 个 MCP Tools / CLI Commands**，覆盖 Web 商城的全部 Shop API 接口。
+
+## 关键设计
+
+- **MCP + CLI 双模式**: 53 个工具同时以 MCP 和 CLI 方式暴露，共享同一套业务逻辑
+- **CLI 自动生成**: cli.py 从 FastMCP 注册表读取工具，通过类型推断自动生成 click 命令
+- **CLI Token 持久化**: 登录后 token 保存到 `~/.findgoods/token.json`，跨进程保持登录
+- **唯一数据源**: GoodsMart Shop API，不建独立数据库
+- **JWT Token 自动管理**: login → 保存 token → 请求自动携带 → 过期自动刷新
+- **搜索/浏览无需登录**: 商品搜索、分类、公告等只读工具不要求认证
+- **交易需要登录**: 购物车、下单、支付、出库等需要先 `findgoods_login`
+- **购物车→结算流程**: 搜索商品 → 加入购物车 → 选择支付方式 → 创建订单
+- **价格计算**: `floor(list_price × discount_rate)` — 一律向下取整，不四舍五入
+
+## 核心领域概念
+
+- **JAN Code**: 日本商品条码（等同于 EAN/UPC）
+- **折扣率** (`discount_rate`): 0.3~1.0，批发价 = floor(定価 × 掛率)
+- **消费税**: 10%，批发价含税 = floor(批发价 × 1.1)
+- **库存状态**: `in_stock`(现货/即纳) / `pre_order`(预约品) / `out_of_stock`(无货)
+- **order_unit**: 发注単位（如 12），数量必须是其倍数
+- **GM Pay**: 预充值余额，有效期 183 天，可用于订单/运费支付
+- 所有价格以 JPY（日元）为单位
+
+## 上游 API 端点
+
+GoodsMart Shop API（`/api/shop/*`）：
+
+### 认证
+- `POST /api/shop/auth/register` — 注册
+- `GET  /api/shop/auth/confirm-email/<token>` — 邮箱确认
+- `POST /api/shop/auth/login` — 登录
+- `POST /api/shop/auth/refresh` — 刷新 Token
+- `POST /api/shop/auth/forgot-password` — 忘记密码
+- `POST /api/shop/auth/reset-password` — 重置密码
+
+### 商品
+- `GET  /api/shop/goods` — 商品搜索（keyword, category_id, manufacturer, original, sort 等）
+- `GET  /api/shop/goods/<id>` — 商品详情
+- `GET  /api/shop/goods/<id>/related` — 关联商品
+- `GET  /api/shop/goods/categories` — 分类列表
+- `GET  /api/shop/goods/manufacturers` — 制造商列表
+- `GET  /api/shop/goods/originals` — 作品/IP 列表
+
+### 购物车 & 结算
+- `GET/POST/DELETE /api/shop/cart` — 购物车操作
+- `PUT/DELETE /api/shop/cart/<id>` — 购物车项操作
+- `POST /api/shop/checkout` — 创建订单（从购物车）
+- `GET  /api/shop/checkout/payment-methods` — 支付方式
+- `POST /api/shop/checkout/stripe-checkout-url` — Stripe 支付链接
+- `POST /api/shop/checkout/nage-checkout-url` — N-Age 支付链接
+- `GET  /api/shop/checkout/bank-transfer-info` — 银行转账信息
+
+### 订单 & 出库
+- `GET  /api/shop/orders` — 订单列表
+- `GET  /api/shop/orders/<id>` — 订单详情
+- `GET  /api/shop/orders/summary` — 订单统计
+- `GET  /api/shop/order-items` — 跨订单商品明细
+- `GET  /api/shop/shipping-carriers` — 承运商列表
+- `GET/POST /api/shop/shipments` — 出库单列表/申请
+- `POST /api/shop/shipments/calculate-fee` — 运费试算
+- `POST /api/shop/shipments/<id>/pay` — 运费支付
+
+### 用户 & 其他
+- `GET/PUT /api/shop/profile` — 用户档案
+- `PUT  /api/shop/profile/password` — 修改密码
+- `GET  /api/shop/dashboard` — 仪表板统计
+- `GET/POST/DELETE /api/shop/wishlist` — 收藏夹
+- `GET/POST/PUT/DELETE /api/shop/addresses` — 配送地址
+- `GET  /api/shop/pay/balance` — GM Pay 余额
+- `GET  /api/shop/pay/transactions` — 交易记录
+- `POST /api/shop/pay/topup` — 充值
+- `GET  /api/shop/quotes` — 报价单
+- `GET  /api/shop/notices` — 系统公告
+- `POST /api/shop/contact` — 客户问询

findgoods_mcp_server-0.2.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: findgoods-mcp-server
+Version: 0.2.0
+Summary: MCP Server for Japanese anime merchandise wholesale — powered by GoodsMart
+Project-URL: Homepage, https://findgoods.ai
+Project-URL: Repository, https://github.com/findgoods-ai/findgoods-mcp-server
+License: MIT
+Keywords: anime,b2b,japan,mcp,wholesale
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.0
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# FindGoods MCP Server
+
+MCP Server for Japanese anime merchandise wholesale, powered by [GoodsMart](https://findgoods.ai).
+
+Exposes 53 tools covering the full GoodsMart Shop API — search products, manage cart, place orders, track shipments, and more.
+
+## Installation
+
+```bash
+pip install findgoods-mcp-server
+```
+
+## Usage
+
+### As MCP Server (for AI clients like Claude Desktop)
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "findgoods": {
+      "command": "python",
+      "args": ["-m", "findgoods_mcp"],
+      "env": {
+        "WHOLESALE_SHOP_API_URL": "https://api.wholesale.goodsmart.jp"
+      }
+    }
+  }
+}
+```
+
+### As CLI (token-efficient, for AI agents like Claude Code)
+
+```bash
+findgoods login --email user@example.com --password xxx
+findgoods search-products --keyword "フィギュア"
+findgoods add-to-cart --goods-id "xxx" --quantity 6
+findgoods create-order --payment-method bank
+findgoods --help
+```
+
+## Configuration
+
+Set the API endpoint via environment variable or `.env` file:
+
+```
+WHOLESALE_SHOP_API_URL=https://api.wholesale.goodsmart.jp
+```
+
+## License
+
+MIT

findgoods_mcp_server-0.2.0/README.md

@@ -0,0 +1,53 @@
+# FindGoods MCP Server
+
+MCP Server for Japanese anime merchandise wholesale, powered by [GoodsMart](https://findgoods.ai).
+
+Exposes 53 tools covering the full GoodsMart Shop API — search products, manage cart, place orders, track shipments, and more.
+
+## Installation
+
+```bash
+pip install findgoods-mcp-server
+```
+
+## Usage
+
+### As MCP Server (for AI clients like Claude Desktop)
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "findgoods": {
+      "command": "python",
+      "args": ["-m", "findgoods_mcp"],
+      "env": {
+        "WHOLESALE_SHOP_API_URL": "https://api.wholesale.goodsmart.jp"
+      }
+    }
+  }
+}
+```
+
+### As CLI (token-efficient, for AI agents like Claude Code)
+
+```bash
+findgoods login --email user@example.com --password xxx
+findgoods search-products --keyword "フィギュア"
+findgoods add-to-cart --goods-id "xxx" --quantity 6
+findgoods create-order --payment-method bank
+findgoods --help
+```
+
+## Configuration
+
+Set the API endpoint via environment variable or `.env` file:
+
+```
+WHOLESALE_SHOP_API_URL=https://api.wholesale.goodsmart.jp
+```
+
+## License
+
+MIT

findgoods_mcp_server-0.2.0/SKILL.md

@@ -0,0 +1,102 @@
+# FindGoods CLI
+
+Japanese anime & otaku merchandise wholesale tool. Search 50,000+ products, check stock, get wholesale prices, manage cart, and place orders — all from the command line.
+
+## Prerequisites
+
+```bash
+pip install findgoods-mcp-server
+```
+
+## Quick Reference
+
+```bash
+# List all commands
+findgoods --help
+
+# Get help for a specific command
+findgoods <command> --help
+```
+
+## Usage Flow
+
+### 1. Browse (no login required)
+
+```bash
+# Search products by keyword
+findgoods search-products --keyword "フィギュア"
+
+# Filter by series, manufacturer, price, stock
+findgoods search-products --keyword "鬼滅の刃" --in-stock-only --max-price 5000
+
+# Sort options: newest, popular, price_asc, price_desc, release_date_desc, discount
+findgoods search-products --keyword "ワンピース" --sort popular --per-page 10
+
+# Browse categories, manufacturers, series
+findgoods get-categories
+findgoods list-manufacturers --keyword "Good Smile"
+findgoods list-series --keyword "初音ミク"
+
+# Get product details
+findgoods get-product --goods-id "<product_id>"
+```
+
+### 2. Login
+
+```bash
+findgoods login --email user@example.com --password xxx
+# Token auto-saved to ~/.findgoods/token.json — persists across calls
+
+findgoods check-auth    # Verify login status
+findgoods logout        # Clear saved token
+```
+
+### 3. Cart & Order
+
+```bash
+# Add to cart (quantity must be multiple of order_unit)
+findgoods add-to-cart --goods-id "<product_id>" --quantity 6
+findgoods get-cart
+
+# Manage delivery address
+findgoods create-address --name "山田太郎" --postal-code "100-0001" \
+  --prefecture "東京都" --city "千代田区" --address-line1 "千代田1-1" --phone "03-1234-5678"
+
+# Place order (payment: bank, pay, stripe, wechat, alipay)
+findgoods create-order --payment-method bank
+```
+
+### 4. Orders & Shipping
+
+```bash
+findgoods get-orders
+findgoods get-order --order-id "<order_id>"
+
+# Request shipment
+findgoods calculate-shipping-fee --order-item-ids '["<id1>","<id2>"]' \
+  --address-id "<addr_id>" --carrier "yamato"
+findgoods create-shipment --order-item-ids '["<id1>"]' \
+  --address-id "<addr_id>" --carrier "yamato"
+```
+
+### 5. GM Pay (prepaid balance)
+
+```bash
+findgoods get-pay-balance
+findgoods get-topup-plans
+findgoods topup-pay --plan-id "<plan_id>" --payment-method stripe
+```
+
+## Key Concepts
+
+- **JAN Code**: Japanese barcode (= EAN/UPC), used as product identifier
+- **Wholesale price**: `floor(list_price × discount_rate)` — always rounded down
+- **Tax**: 10% consumption tax, `floor(wholesale_price × 1.1)`
+- **order_unit**: Minimum order unit (e.g. 6), quantity must be a multiple
+- **Stock status**: `in_stock` (ready to ship), `pre_order` (upcoming), `out_of_stock`
+- All prices in JPY (Japanese Yen), tax excluded unless noted
+
+## Output Format
+
+All commands output JSON to stdout. Parse with `jq` or read directly.
+Errors return `{"error": "..."}` with exit code 1.

findgoods_mcp_server-0.2.0/a2a/agent.json

@@ -0,0 +1,65 @@
+{
+  "name": "FindGoods Supply",
+  "description": "Japanese anime & otaku merchandise wholesale supplier. Direct sourcing from Tokyo. Search 5000+ products including figures, Nendoroids, prize figures, and goods from major manufacturers (Good Smile Company, Bandai, Kotobukiya, etc.). Get real-time wholesale prices, check stock, and place orders. Supports pre-order and in-stock items.",
+  "url": "https://mcp.findgoods.ai",
+  "version": "1.0.0",
+  "provider": {
+    "organization": "GoodsMart",
+    "url": "https://goodsmart.jp",
+    "location": "Tokyo, Japan"
+  },
+  "capabilities": {
+    "streaming": false,
+    "pushNotifications": false
+  },
+  "authentication": {
+    "schemes": ["Bearer"]
+  },
+  "defaultInputModes": ["text/plain", "application/json"],
+  "defaultOutputModes": ["application/json"],
+  "skills": [
+    {
+      "id": "product-search",
+      "name": "Product Search & Browse",
+      "description": "Search and browse anime figures, goods, and accessories from Japanese manufacturers. Filter by series/IP, manufacturer, price range, discount rate, and availability. Includes recommendations and quote sheets.",
+      "tags": ["anime", "figure", "merchandise", "wholesale", "japan", "search"],
+      "examples": [
+        "Search for Hatsune Miku figures",
+        "Find Jujutsu Kaisen merchandise under 5000 JPY",
+        "Show me new arrivals from Good Smile Company",
+        "List all available One Piece products"
+      ]
+    },
+    {
+      "id": "wholesale-pricing",
+      "name": "Wholesale Pricing",
+      "description": "Get real-time wholesale prices with discount rates. All prices in JPY. Tax rate is 10% (Japan consumption tax).",
+      "tags": ["wholesale", "pricing", "B2B"],
+      "examples": [
+        "What is the wholesale price for this Nendoroid?",
+        "Show me products with discount rate above 40%"
+      ]
+    },
+    {
+      "id": "order-management",
+      "name": "Order & Payment",
+      "description": "Place wholesale orders and manage the full payment lifecycle: deposit → balance → shipping fee. Generates WisePay payment links for each step. Track order status and delivery.",
+      "tags": ["order", "payment", "shipping", "logistics"],
+      "examples": [
+        "Place an order for 10 units of this figure",
+        "Get the payment link for my order",
+        "Check my order status",
+        "Show my pending bills"
+      ]
+    },
+    {
+      "id": "account-management",
+      "name": "Account Registration",
+      "description": "Register as a wholesale buyer. Requires company information. Applications are reviewed within 1 business day.",
+      "tags": ["registration", "account", "B2B"],
+      "examples": [
+        "Register a new wholesale buyer account"
+      ]
+    }
+  ]
+}