Metadata-Version: 2.4
Name: cuqu-mcp
Version: 1.0.2
Summary: MCP server for CUQU找搭子 — find and book offline group activities in 10+ China cities, or publish your own event.
Author: CUQU / 光天科技（深圳）有限公司
License: MIT License
        
        Copyright (c) 2026 光天科技（深圳）有限公司 (Guangtian Technology (Shenzhen) Co., Ltd.)
        
        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.
        
Project-URL: Homepage, https://cuqu.net
Project-URL: Repository, https://github.com/cuqu-net/cuqu-skill
Project-URL: MCP endpoint, https://agent.cuqu.net/mcp
Project-URL: llms.txt, https://cuqu.net/llms.txt
Keywords: mcp,cuqu,cuqu-zhaodazi,zhaodazi,model-context-protocol,activities,social,events,shenzhen,offline-events
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# CUQU (找搭子) MCP Server

Open-source MCP server giving AI agents live access to **[CUQU (找搭子)](https://cuqu.net)** — a local offline social activities platform in China (Shenzhen-based, 10+ cities incl. Hong Kong, China). Users discover and book offline interest-based group activities (board games, frisbee, hiking, badminton, fishing, anime and 100+ more categories); organizers publish and run events.

**Live demo endpoint (hosted):** `https://agent.cuqu.net/mcp` (Streamable HTTP, per-user `cq-sk-` keys — see [llms.txt](https://cuqu.net/llms.txt))
**Agent Card:** https://cuqu.net/.well-known/agent.json

**Talk to the agents (chat UI):**
- Baidu Qianfan: https://appbuilder.baidu.com/s/w93d7Z6X (Chinese)
- iFlytek Astron: https://agent.xfyun.cn/agentbuilder/chat?sharekey=998b5236b21fb85e005b9c9438f78b10&botId=5830291 (Chinese; API flow_id `7510896245077958656`)
- Live weekly activities: https://cuqu.net/activities/list/ (real in-stock data, updated daily)
- IRL Activity Schema v0.1 (CC BY 4.0): https://cuqu.net/schema/irl-activity/v0.1/irl-activity-schema.json

## What this repository contains

| Path | What it is |
|---|---|
| `server.py` | **The MCP server implementation** — zero-dependency Python, JSON-RPC 2.0 over stdio. Read tools call CUQU's public live activity API; write tools forward to the hosted gateway with a user key. |
| `Dockerfile` | One-command container build for the server (glama.ai / docker / any MCP host). |
| `glama.json` | glama.ai directory metadata & maintainership. |
| `scripts/check-mcp.py` | Connectivity check for the hosted gateway. |
| `skills/`, `docs/` | Agent skill manifests and platform integration docs (Qwen/Dify/Yuanqi). |

## Tools (8)

| Tool | Type | Description |
|---|---|---|
| `query_activities` | read (no key) | Search live activities by type / city / date — 100+ categories, real-time public data |
| `get_activity_card` | read (no key) | Full detail card for one activity (time, venue, price, booking progress, organizer, cover) |
| `query_venues` | read (no key) | Curated partner venue directory (capacity, per-head price) |
| `generate_urllink` | read (no key) | Share link + WeChat mini-program path for an activity |
| `create_activity` | write (key) | Organizer publishes a new event |
| `register_event` | write (key) | Book a user into an activity |
| `create_payment` | write (key) | Create WeChat Pay for a booking order |
| `check_in` | write (key) | On-site check-in / redemption |

Write tools are executed by the hosted gateway and require `CUQU_API_KEY` (`cq-sk-...`, issued via scan-to-issue flow documented in [llms.txt](https://cuqu.net/llms.txt)).

## Quick start

```bash
# stdio, zero dependencies, Python 3.9+
python -u server.py

# or via Docker
docker build -t cuqu-mcp .
docker run -i cuqu-mcp
```

Claude Desktop / any stdio MCP client:

```json
{
  "mcpServers": {
    "cuqu": {
      "command": "python",
      "args": ["-u", "/path/to/server.py"],
      "env": { "CUQU_API_KEY": "cq-sk-...(optional, enables write tools)" }
    }
  }
}
```

## License

MIT — © 2026 光天科技（深圳）有限公司 (Guangtian Technology (Shenzhen) Co., Ltd.)
