capmonster-mcp 0.1.4__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- capmonster_mcp-0.1.4/.github/workflows/ci.yml +184 -0
- capmonster_mcp-0.1.4/.gitignore +11 -0
- capmonster_mcp-0.1.4/PKG-INFO +113 -0
- capmonster_mcp-0.1.4/README.md +96 -0
- capmonster_mcp-0.1.4/capmonster_agent/PROMPT.md +64 -0
- capmonster_mcp-0.1.4/capmonster_agent/PROMPT_JS.md +64 -0
- capmonster_mcp-0.1.4/capmonster_agent/SKILL.md +646 -0
- capmonster_mcp-0.1.4/capmonster_mcp/__init__.py +6 -0
- capmonster_mcp-0.1.4/capmonster_mcp/config.py +8 -0
- capmonster_mcp-0.1.4/capmonster_mcp/middleware.py +25 -0
- capmonster_mcp-0.1.4/capmonster_mcp/server.py +546 -0
- capmonster_mcp-0.1.4/mcp.example.json +15 -0
- capmonster_mcp-0.1.4/pyproject.toml +41 -0
- capmonster_mcp-0.1.4/tests/__init__.py +0 -0
- capmonster_mcp-0.1.4/tests/test_tools.py +480 -0
- capmonster_mcp-0.1.4/ts/.gitignore +3 -0
- capmonster_mcp-0.1.4/ts/README.md +61 -0
- capmonster_mcp-0.1.4/ts/biome.json +23 -0
- capmonster_mcp-0.1.4/ts/mcp.json +15 -0
- capmonster_mcp-0.1.4/ts/package-lock.json +1916 -0
- capmonster_mcp-0.1.4/ts/package.json +48 -0
- capmonster_mcp-0.1.4/ts/src/__tests__/capmonster.test.ts +143 -0
- capmonster_mcp-0.1.4/ts/src/__tests__/docs.test.ts +76 -0
- capmonster_mcp-0.1.4/ts/src/__tests__/openapi.test.ts +77 -0
- capmonster_mcp-0.1.4/ts/src/__tests__/tasks.test.ts +95 -0
- capmonster_mcp-0.1.4/ts/src/__tests__/test-utils.ts +23 -0
- capmonster_mcp-0.1.4/ts/src/capmonster.ts +116 -0
- capmonster_mcp-0.1.4/ts/src/config.ts +11 -0
- capmonster_mcp-0.1.4/ts/src/docs.ts +110 -0
- capmonster_mcp-0.1.4/ts/src/openapi.ts +101 -0
- capmonster_mcp-0.1.4/ts/src/server.ts +393 -0
- capmonster_mcp-0.1.4/ts/src/tasks.ts +56 -0
- capmonster_mcp-0.1.4/ts/tsconfig.json +17 -0
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: ["**"]
|
|
6
|
+
tags: ["v*"]
|
|
7
|
+
pull_request:
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
test:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
steps:
|
|
13
|
+
- name: Checkout
|
|
14
|
+
uses: actions/checkout@v4
|
|
15
|
+
with:
|
|
16
|
+
fetch-depth: 0
|
|
17
|
+
|
|
18
|
+
- name: Set up Python
|
|
19
|
+
uses: actions/setup-python@v5
|
|
20
|
+
with:
|
|
21
|
+
python-version: "3.11"
|
|
22
|
+
|
|
23
|
+
- name: Install dependencies
|
|
24
|
+
run: pip install -e ".[dev]"
|
|
25
|
+
|
|
26
|
+
- name: Run tests
|
|
27
|
+
run: pytest tests/
|
|
28
|
+
|
|
29
|
+
- name: Set up Node
|
|
30
|
+
uses: actions/setup-node@v4
|
|
31
|
+
with:
|
|
32
|
+
node-version: "20"
|
|
33
|
+
cache: "npm"
|
|
34
|
+
cache-dependency-path: ts/package-lock.json
|
|
35
|
+
|
|
36
|
+
- name: Install ts dependencies
|
|
37
|
+
working-directory: ts
|
|
38
|
+
run: npm ci
|
|
39
|
+
|
|
40
|
+
- name: Run ts tests
|
|
41
|
+
working-directory: ts
|
|
42
|
+
run: npm test
|
|
43
|
+
|
|
44
|
+
publish-test:
|
|
45
|
+
needs: test
|
|
46
|
+
if: startsWith(github.ref, 'refs/tags/v')
|
|
47
|
+
runs-on: ubuntu-latest
|
|
48
|
+
outputs:
|
|
49
|
+
version: ${{ steps.version.outputs.version }}
|
|
50
|
+
steps:
|
|
51
|
+
- name: Checkout
|
|
52
|
+
uses: actions/checkout@v4
|
|
53
|
+
with:
|
|
54
|
+
fetch-depth: 0
|
|
55
|
+
|
|
56
|
+
- name: Require tag on main
|
|
57
|
+
run: |
|
|
58
|
+
if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
|
|
59
|
+
echo "::error::Tag ${GITHUB_REF_NAME} is not on main. Tags must be created on main."
|
|
60
|
+
exit 1
|
|
61
|
+
fi
|
|
62
|
+
|
|
63
|
+
- name: Derive version from tag
|
|
64
|
+
id: version
|
|
65
|
+
run: |
|
|
66
|
+
version="${GITHUB_REF_NAME#v}"
|
|
67
|
+
echo "version=$version" >> "$GITHUB_OUTPUT"
|
|
68
|
+
|
|
69
|
+
- name: Set up Python
|
|
70
|
+
uses: actions/setup-python@v5
|
|
71
|
+
with:
|
|
72
|
+
python-version: "3.11"
|
|
73
|
+
|
|
74
|
+
- name: Install build tools
|
|
75
|
+
run: pip install build
|
|
76
|
+
|
|
77
|
+
- name: Build Python package
|
|
78
|
+
run: python -m build
|
|
79
|
+
|
|
80
|
+
- name: Upload Python package artifact
|
|
81
|
+
uses: actions/upload-artifact@v4
|
|
82
|
+
with:
|
|
83
|
+
name: python-dist
|
|
84
|
+
path: dist/
|
|
85
|
+
|
|
86
|
+
- name: Publish Python package to TestPyPI
|
|
87
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
88
|
+
with:
|
|
89
|
+
repository-url: https://test.pypi.org/legacy/
|
|
90
|
+
user: __token__
|
|
91
|
+
password: ${{ secrets.TEST_PYPI_API_TOKEN }}
|
|
92
|
+
|
|
93
|
+
- name: Set up Node
|
|
94
|
+
uses: actions/setup-node@v4
|
|
95
|
+
with:
|
|
96
|
+
node-version: "20"
|
|
97
|
+
registry-url: https://registry.npmjs.org
|
|
98
|
+
|
|
99
|
+
- name: Set npm package version from tag
|
|
100
|
+
working-directory: ts
|
|
101
|
+
run: npm version "${{ steps.version.outputs.version }}" --no-git-tag-version --allow-same-version
|
|
102
|
+
|
|
103
|
+
- name: Install ts dependencies
|
|
104
|
+
working-directory: ts
|
|
105
|
+
run: npm ci
|
|
106
|
+
|
|
107
|
+
- name: Build ts package
|
|
108
|
+
working-directory: ts
|
|
109
|
+
run: npm run build
|
|
110
|
+
|
|
111
|
+
- name: Publish npm package under rc tag
|
|
112
|
+
working-directory: ts
|
|
113
|
+
run: npm publish --tag rc
|
|
114
|
+
env:
|
|
115
|
+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
|
116
|
+
|
|
117
|
+
verify:
|
|
118
|
+
needs: publish-test
|
|
119
|
+
runs-on: ubuntu-latest
|
|
120
|
+
steps:
|
|
121
|
+
- name: Set up Python
|
|
122
|
+
uses: actions/setup-python@v5
|
|
123
|
+
with:
|
|
124
|
+
python-version: "3.11"
|
|
125
|
+
|
|
126
|
+
- name: Wait for TestPyPI to index the release
|
|
127
|
+
run: sleep 30
|
|
128
|
+
|
|
129
|
+
- name: Install from TestPyPI and check version
|
|
130
|
+
run: |
|
|
131
|
+
version="${{ needs.publish-test.outputs.version }}"
|
|
132
|
+
pip install --index-url https://test.pypi.org/simple/ \
|
|
133
|
+
--extra-index-url https://pypi.org/simple/ \
|
|
134
|
+
"capmonster-mcp==$version"
|
|
135
|
+
python -c "
|
|
136
|
+
import capmonster_mcp
|
|
137
|
+
assert capmonster_mcp.__version__ == '$version', capmonster_mcp.__version__
|
|
138
|
+
print('OK:', capmonster_mcp.__version__)
|
|
139
|
+
"
|
|
140
|
+
|
|
141
|
+
- name: Set up Node
|
|
142
|
+
uses: actions/setup-node@v4
|
|
143
|
+
with:
|
|
144
|
+
node-version: "20"
|
|
145
|
+
|
|
146
|
+
- name: Install from npm rc tag and check version
|
|
147
|
+
run: |
|
|
148
|
+
version="${{ needs.publish-test.outputs.version }}"
|
|
149
|
+
mkdir verify-npm && cd verify-npm
|
|
150
|
+
npm init -y >/dev/null
|
|
151
|
+
npm install "capmonster-mcp@rc"
|
|
152
|
+
installed=$(node -p "require('capmonster-mcp/package.json').version")
|
|
153
|
+
if [ "$installed" != "$version" ]; then
|
|
154
|
+
echo "::error::expected $version, got $installed"
|
|
155
|
+
exit 1
|
|
156
|
+
fi
|
|
157
|
+
echo "OK: $installed"
|
|
158
|
+
|
|
159
|
+
publish-prod:
|
|
160
|
+
needs: [publish-test, verify]
|
|
161
|
+
runs-on: ubuntu-latest
|
|
162
|
+
steps:
|
|
163
|
+
- name: Download Python package artifact
|
|
164
|
+
uses: actions/download-artifact@v4
|
|
165
|
+
with:
|
|
166
|
+
name: python-dist
|
|
167
|
+
path: dist/
|
|
168
|
+
|
|
169
|
+
- name: Publish Python package to PyPI
|
|
170
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
171
|
+
with:
|
|
172
|
+
user: __token__
|
|
173
|
+
password: ${{ secrets.PYPI_API_TOKEN }}
|
|
174
|
+
|
|
175
|
+
- name: Set up Node
|
|
176
|
+
uses: actions/setup-node@v4
|
|
177
|
+
with:
|
|
178
|
+
node-version: "20"
|
|
179
|
+
registry-url: https://registry.npmjs.org
|
|
180
|
+
|
|
181
|
+
- name: Promote npm rc tag to latest
|
|
182
|
+
run: npm dist-tag add "capmonster-mcp@${{ needs.publish-test.outputs.version }}" latest
|
|
183
|
+
env:
|
|
184
|
+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: capmonster-mcp
|
|
3
|
+
Version: 0.1.4
|
|
4
|
+
Summary: MCP server for solving captchas via CapMonster Cloud (test publish)
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Requires-Python: >=3.11
|
|
7
|
+
Requires-Dist: fastmcp
|
|
8
|
+
Requires-Dist: httpx>=0.27
|
|
9
|
+
Requires-Dist: pydantic-settings>=2.0
|
|
10
|
+
Requires-Dist: pydantic>=2.0
|
|
11
|
+
Provides-Extra: dev
|
|
12
|
+
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
|
|
13
|
+
Requires-Dist: pytest>=8.0.0; extra == 'dev'
|
|
14
|
+
Requires-Dist: respx>=0.20.0; extra == 'dev'
|
|
15
|
+
Requires-Dist: ruff>=0.4.0; extra == 'dev'
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
|
|
18
|
+
# CapMonster Cloud MCP Server (Model Context Protocol)
|
|
19
|
+
|
|
20
|
+
[](https://opensource.org/licenses/MIT)
|
|
21
|
+
[](https://modelcontextprotocol.io/)
|
|
22
|
+
|
|
23
|
+
An **Model Context Protocol (MCP)** server for CapMonster Cloud, available as a Python package
|
|
24
|
+
and as a TypeScript port ([`ts/`](ts)).
|
|
25
|
+
|
|
26
|
+
This server is the **solve brain**: it lists supported captcha types, serves CapMonster's live
|
|
27
|
+
docs, and creates/polls solve tasks against the CapMonster Cloud REST API. It has **no browser of
|
|
28
|
+
its own** — pair it with a browser-driving MCP (e.g.
|
|
29
|
+
[`mcp-patchright-mainworld`](https://www.npmjs.com/package/mcp-patchright-mainworld)) that does
|
|
30
|
+
the page work (navigation, interaction, reading the live DOM/network, and injecting the solved
|
|
31
|
+
token back into the page). See [`capmonster_agent/SKILL.md`](capmonster_agent/SKILL.md) for the
|
|
32
|
+
full step-by-step procedure for analyzing a captcha-protected page and solving it this way.
|
|
33
|
+
|
|
34
|
+
**[👉 Get your Free API Key and Start Bypassing CAPTCHAs](https://dash.capmonster.cloud/Account/SignUp?utm_source=github&utm_medium=referral&utm_campaign=mcp_repo_readme)**
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## âš¡ Supported CAPTCHAs
|
|
39
|
+
|
|
40
|
+
Your AI Agent will be able to automatically bypass, among others:
|
|
41
|
+
- **reCAPTCHA** (v2, v2 Enterprise, v3)
|
|
42
|
+
- **Cloudflare Turnstile** and Cloudflare Challenge (managed challenge / `cf_clearance`)
|
|
43
|
+
- **FunCaptcha** (Arkose)
|
|
44
|
+
- **GeeTest** (v3 and v4)
|
|
45
|
+
- **Enterprise Anti-Bot Systems:** AWS WAF, DataDome, Imperva, TSPD, Binance, Prosopo, Yidun,
|
|
46
|
+
TenDI, Hunt, Altcha, Basilisk, and more
|
|
47
|
+
- **Image-to-Text & Complex Image Tasks**
|
|
48
|
+
|
|
49
|
+
The authoritative, current list is served live from CapMonster's OpenAPI spec via the
|
|
50
|
+
`get_supported_tasks` tool — **hCaptcha is not currently supported**, despite appearing in some
|
|
51
|
+
of CapMonster's own marketing copy.
|
|
52
|
+
|
|
53
|
+
## 📦 Installation
|
|
54
|
+
|
|
55
|
+
Requires Python 3.11+ and a valid CapMonster API Key. Run it with `uvx` (no local clone needed):
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
uvx capmonster-mcp
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Prefer TypeScript/Node? See [`ts/README.md`](ts/README.md) for the npm-published port — same
|
|
62
|
+
tools, same behavior.
|
|
63
|
+
|
|
64
|
+
## 🔌 Using with an MCP client (e.g. Claude Desktop)
|
|
65
|
+
|
|
66
|
+
Add the following to your MCP client's config (e.g. `claude_desktop_config.json`):
|
|
67
|
+
|
|
68
|
+
```json
|
|
69
|
+
{
|
|
70
|
+
"mcpServers": {
|
|
71
|
+
"capmonster": {
|
|
72
|
+
"command": "uvx",
|
|
73
|
+
"args": ["capmonster-mcp"],
|
|
74
|
+
"env": {
|
|
75
|
+
"CM_API_KEY": "your_api_key_here"
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
The server only runs over stdio, so there are no HTTP headers to carry a per-request key —
|
|
83
|
+
`CM_API_KEY` is read once from the environment and shared by every tool call in the session.
|
|
84
|
+
|
|
85
|
+
Pair it with a browser-automation MCP server (e.g.
|
|
86
|
+
[`mcp-patchright-mainworld`](https://www.npmjs.com/package/mcp-patchright-mainworld)) so your
|
|
87
|
+
agent can both see the page and solve what's on it — see [`mcp.example.json`](mcp.example.json)
|
|
88
|
+
for a config with both servers wired up together.
|
|
89
|
+
|
|
90
|
+
## 🛠Available MCP Tools
|
|
91
|
+
|
|
92
|
+
Once connected, your LLM will have access to the following tools:
|
|
93
|
+
|
|
94
|
+
- `get_supported_tasks`: Lists captcha task types CapMonster supports, from the live OpenAPI spec.
|
|
95
|
+
- `get_task_parameters(task_type)`: Required/optional fields, variant notes, and the solution
|
|
96
|
+
schema for a task type.
|
|
97
|
+
- `get_docs(url, offset, limit, section)`: Fetches a CapMonster documentation page
|
|
98
|
+
(`docs.capmonster.cloud` / `api.capmonster.cloud` only), with section-jump and pagination.
|
|
99
|
+
- `create_task(task)`: Submits a captcha task and returns a `taskId`.
|
|
100
|
+
- `get_task_result(task_id)`: Polls a task once.
|
|
101
|
+
- `get_task_result_wait(task_id, timeout_seconds, poll_interval_seconds)`: Polls a task to
|
|
102
|
+
completion (preferred over driving the poll loop yourself).
|
|
103
|
+
- `get_actual_user_agent()`: Fetches a current Windows User-Agent to use as one consistent
|
|
104
|
+
fingerprint across the browser and the solve task.
|
|
105
|
+
- `get_balance()`: Checks your current CapMonster Cloud API balance.
|
|
106
|
+
|
|
107
|
+
## 📚 Official Documentation
|
|
108
|
+
|
|
109
|
+
- [CapMonster Cloud Main Documentation](https://docs.capmonster.cloud/)
|
|
110
|
+
- [Model Context Protocol (MCP) Docs](https://modelcontextprotocol.io/)
|
|
111
|
+
|
|
112
|
+
## 📄 License
|
|
113
|
+
[MIT](LICENSE)
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# CapMonster Cloud MCP Server (Model Context Protocol)
|
|
2
|
+
|
|
3
|
+
[](https://opensource.org/licenses/MIT)
|
|
4
|
+
[](https://modelcontextprotocol.io/)
|
|
5
|
+
|
|
6
|
+
An **Model Context Protocol (MCP)** server for CapMonster Cloud, available as a Python package
|
|
7
|
+
and as a TypeScript port ([`ts/`](ts)).
|
|
8
|
+
|
|
9
|
+
This server is the **solve brain**: it lists supported captcha types, serves CapMonster's live
|
|
10
|
+
docs, and creates/polls solve tasks against the CapMonster Cloud REST API. It has **no browser of
|
|
11
|
+
its own** — pair it with a browser-driving MCP (e.g.
|
|
12
|
+
[`mcp-patchright-mainworld`](https://www.npmjs.com/package/mcp-patchright-mainworld)) that does
|
|
13
|
+
the page work (navigation, interaction, reading the live DOM/network, and injecting the solved
|
|
14
|
+
token back into the page). See [`capmonster_agent/SKILL.md`](capmonster_agent/SKILL.md) for the
|
|
15
|
+
full step-by-step procedure for analyzing a captcha-protected page and solving it this way.
|
|
16
|
+
|
|
17
|
+
**[👉 Get your Free API Key and Start Bypassing CAPTCHAs](https://dash.capmonster.cloud/Account/SignUp?utm_source=github&utm_medium=referral&utm_campaign=mcp_repo_readme)**
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## âš¡ Supported CAPTCHAs
|
|
22
|
+
|
|
23
|
+
Your AI Agent will be able to automatically bypass, among others:
|
|
24
|
+
- **reCAPTCHA** (v2, v2 Enterprise, v3)
|
|
25
|
+
- **Cloudflare Turnstile** and Cloudflare Challenge (managed challenge / `cf_clearance`)
|
|
26
|
+
- **FunCaptcha** (Arkose)
|
|
27
|
+
- **GeeTest** (v3 and v4)
|
|
28
|
+
- **Enterprise Anti-Bot Systems:** AWS WAF, DataDome, Imperva, TSPD, Binance, Prosopo, Yidun,
|
|
29
|
+
TenDI, Hunt, Altcha, Basilisk, and more
|
|
30
|
+
- **Image-to-Text & Complex Image Tasks**
|
|
31
|
+
|
|
32
|
+
The authoritative, current list is served live from CapMonster's OpenAPI spec via the
|
|
33
|
+
`get_supported_tasks` tool — **hCaptcha is not currently supported**, despite appearing in some
|
|
34
|
+
of CapMonster's own marketing copy.
|
|
35
|
+
|
|
36
|
+
## 📦 Installation
|
|
37
|
+
|
|
38
|
+
Requires Python 3.11+ and a valid CapMonster API Key. Run it with `uvx` (no local clone needed):
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
uvx capmonster-mcp
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Prefer TypeScript/Node? See [`ts/README.md`](ts/README.md) for the npm-published port — same
|
|
45
|
+
tools, same behavior.
|
|
46
|
+
|
|
47
|
+
## 🔌 Using with an MCP client (e.g. Claude Desktop)
|
|
48
|
+
|
|
49
|
+
Add the following to your MCP client's config (e.g. `claude_desktop_config.json`):
|
|
50
|
+
|
|
51
|
+
```json
|
|
52
|
+
{
|
|
53
|
+
"mcpServers": {
|
|
54
|
+
"capmonster": {
|
|
55
|
+
"command": "uvx",
|
|
56
|
+
"args": ["capmonster-mcp"],
|
|
57
|
+
"env": {
|
|
58
|
+
"CM_API_KEY": "your_api_key_here"
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
The server only runs over stdio, so there are no HTTP headers to carry a per-request key —
|
|
66
|
+
`CM_API_KEY` is read once from the environment and shared by every tool call in the session.
|
|
67
|
+
|
|
68
|
+
Pair it with a browser-automation MCP server (e.g.
|
|
69
|
+
[`mcp-patchright-mainworld`](https://www.npmjs.com/package/mcp-patchright-mainworld)) so your
|
|
70
|
+
agent can both see the page and solve what's on it — see [`mcp.example.json`](mcp.example.json)
|
|
71
|
+
for a config with both servers wired up together.
|
|
72
|
+
|
|
73
|
+
## 🛠Available MCP Tools
|
|
74
|
+
|
|
75
|
+
Once connected, your LLM will have access to the following tools:
|
|
76
|
+
|
|
77
|
+
- `get_supported_tasks`: Lists captcha task types CapMonster supports, from the live OpenAPI spec.
|
|
78
|
+
- `get_task_parameters(task_type)`: Required/optional fields, variant notes, and the solution
|
|
79
|
+
schema for a task type.
|
|
80
|
+
- `get_docs(url, offset, limit, section)`: Fetches a CapMonster documentation page
|
|
81
|
+
(`docs.capmonster.cloud` / `api.capmonster.cloud` only), with section-jump and pagination.
|
|
82
|
+
- `create_task(task)`: Submits a captcha task and returns a `taskId`.
|
|
83
|
+
- `get_task_result(task_id)`: Polls a task once.
|
|
84
|
+
- `get_task_result_wait(task_id, timeout_seconds, poll_interval_seconds)`: Polls a task to
|
|
85
|
+
completion (preferred over driving the poll loop yourself).
|
|
86
|
+
- `get_actual_user_agent()`: Fetches a current Windows User-Agent to use as one consistent
|
|
87
|
+
fingerprint across the browser and the solve task.
|
|
88
|
+
- `get_balance()`: Checks your current CapMonster Cloud API balance.
|
|
89
|
+
|
|
90
|
+
## 📚 Official Documentation
|
|
91
|
+
|
|
92
|
+
- [CapMonster Cloud Main Documentation](https://docs.capmonster.cloud/)
|
|
93
|
+
- [Model Context Protocol (MCP) Docs](https://modelcontextprotocol.io/)
|
|
94
|
+
|
|
95
|
+
## 📄 License
|
|
96
|
+
[MIT](LICENSE)
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
I want to detect and solve a captcha using CapMonster Cloud. Set yourself up:
|
|
2
|
+
|
|
3
|
+
1. MCP SERVERS — if you support MCP servers, add BOTH of these to your config:
|
|
4
|
+
|
|
5
|
+
a) capmonster — the solve brain (CapMonster Cloud). Runs the published
|
|
6
|
+
`capmonster-mcp` PyPI package (no cloning needed):
|
|
7
|
+
{ "command": "uvx", "args": ["capmonster-mcp"], "env": { "CM_API_KEY": "..." } }
|
|
8
|
+
It exposes: get_supported_tasks, get_task_parameters, get_docs,
|
|
9
|
+
create_task, get_task_result, get_task_result_wait, get_actual_user_agent,
|
|
10
|
+
get_balance.
|
|
11
|
+
(get_task_result_wait polls a task to completion for you — prefer it over
|
|
12
|
+
looping get_task_result by hand.)
|
|
13
|
+
|
|
14
|
+
b) patchright — a stealth Playwright browser kept alive across tool calls,
|
|
15
|
+
that does all the page work: navigation, interaction, reading the live
|
|
16
|
+
DOM/network, and injecting the solution (capmonster-mcp has no browser of its
|
|
17
|
+
own). Also accepts a proxy (including authenticated user:pass proxies) via
|
|
18
|
+
its `browser_start(proxy={server, username, password})` tool call — no
|
|
19
|
+
config edit or restart needed. Runs the published `mcp-patchright-mainworld`
|
|
20
|
+
npm package via npx (needs Node.js 18+):
|
|
21
|
+
{ "command": "npx", "args": ["-y", "mcp-patchright-mainworld"] }
|
|
22
|
+
(auto-starts a session on first browser_navigate; call browser_start
|
|
23
|
+
explicitly only to set non-default options like proxy/userAgent/locale.
|
|
24
|
+
browser_evaluate / browser_run_code_unsafe run in an isolated stealth world
|
|
25
|
+
by default; pass world:"main" to reach the page's own window globals —
|
|
26
|
+
needed to fire a page-registered callback when injecting a solution.)
|
|
27
|
+
|
|
28
|
+
2. WORKFLOW SKILL — fetch and follow this as your working instructions for
|
|
29
|
+
analyzing and solving captchas with the two servers together, whether or not
|
|
30
|
+
your environment has a first-class "skill" feature. It is a strict, ordered
|
|
31
|
+
procedure — follow the numbered steps in order:
|
|
32
|
+
https://raw.githubusercontent.com/pavelgrinkevich/captcha-mcp-test/main/capmonster_agent/SKILL.md
|
|
33
|
+
|
|
34
|
+
3. DOCS — the capmonster MCP's `get_docs(url)` tool fetches any CapMonster doc
|
|
35
|
+
page (docs.capmonster.cloud / api.capmonster.cloud only). Start from the
|
|
36
|
+
index at https://docs.capmonster.cloud/llms.txt (it links every captcha
|
|
37
|
+
type's detailed page); read the specific type's single page for exact
|
|
38
|
+
parameters, how to extract them from a live page (DevTools + Playwright/JS
|
|
39
|
+
snippet), and worked createTask/getTaskResult examples (get_docs paginates
|
|
40
|
+
large pages and supports section="..." to jump straight to a section). Do NOT
|
|
41
|
+
pull the full single-file dump (https://docs.capmonster.cloud/llms-full.txt,
|
|
42
|
+
the entire site at once) — read the one per-vendor page instead. Note the
|
|
43
|
+
llms.txt index tagline lists "hCaptcha", but hCaptcha is NOT actually a
|
|
44
|
+
supported task type (absent from get_supported_tasks) — trust
|
|
45
|
+
get_supported_tasks. If you have NO MCP access, fetch the per-type URLs
|
|
46
|
+
directly instead.
|
|
47
|
+
|
|
48
|
+
4. FULL API SPEC — machine-readable contract, use it if you don't have MCP
|
|
49
|
+
access and need to call the REST API directly, or to double check a
|
|
50
|
+
parameter the reference above doesn't cover:
|
|
51
|
+
https://api.capmonster.cloud/docs/swagger-ui/spec.js
|
|
52
|
+
|
|
53
|
+
5. VALIDATE THE SETUP before starting: confirm each capmonster tool responds
|
|
54
|
+
(call get_supported_tasks and get_balance) and that get_docs can fetch
|
|
55
|
+
https://docs.capmonster.cloud/llms.txt, and confirm the patchright browser
|
|
56
|
+
opens (browser_navigate to any page). If any of these fails, stop and tell
|
|
57
|
+
me what's wrong instead of proceeding.
|
|
58
|
+
|
|
59
|
+
Once set up, ask me for:
|
|
60
|
+
- the URL of the page with the captcha;
|
|
61
|
+
- whether the captcha is directly on that URL or must be triggered by a
|
|
62
|
+
click / form submit / scroll / login;
|
|
63
|
+
- any hints (the URL is only reachable via a specific proxy, extra headers
|
|
64
|
+
are needed, a login is required, it only appears for some regions/UAs).
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
I want to detect and solve a captcha using CapMonster Cloud. Set yourself up:
|
|
2
|
+
|
|
3
|
+
1. MCP SERVERS — if you support MCP servers, add BOTH of these to your config:
|
|
4
|
+
|
|
5
|
+
a) capmonster — the solve brain (CapMonster Cloud). Runs the published
|
|
6
|
+
`captcha-mcp-test` npm package via npx (needs Node.js 18+, no cloning needed):
|
|
7
|
+
{ "command": "npx", "args": ["-y", "captcha-mcp-test"], "env": { "CM_API_KEY": "..." } }
|
|
8
|
+
It exposes: get_supported_tasks, get_task_parameters, get_docs,
|
|
9
|
+
create_task, get_task_result, get_task_result_wait, get_actual_user_agent,
|
|
10
|
+
get_balance.
|
|
11
|
+
(get_task_result_wait polls a task to completion for you — prefer it over
|
|
12
|
+
looping get_task_result by hand.)
|
|
13
|
+
|
|
14
|
+
b) patchright — a stealth Playwright browser kept alive across tool calls,
|
|
15
|
+
that does all the page work: navigation, interaction, reading the live
|
|
16
|
+
DOM/network, and injecting the solution (captcha-mcp-test has no browser of its
|
|
17
|
+
own). Also accepts a proxy (including authenticated user:pass proxies) via
|
|
18
|
+
its `browser_start(proxy={server, username, password})` tool call — no
|
|
19
|
+
config edit or restart needed. Runs the published `mcp-patchright-mainworld`
|
|
20
|
+
npm package via npx (needs Node.js 18+):
|
|
21
|
+
{ "command": "npx", "args": ["-y", "mcp-patchright-mainworld"] }
|
|
22
|
+
(auto-starts a session on first browser_navigate; call browser_start
|
|
23
|
+
explicitly only to set non-default options like proxy/userAgent/locale.
|
|
24
|
+
browser_evaluate / browser_run_code_unsafe run in an isolated stealth world
|
|
25
|
+
by default; pass world:"main" to reach the page's own window globals —
|
|
26
|
+
needed to fire a page-registered callback when injecting a solution.)
|
|
27
|
+
|
|
28
|
+
2. WORKFLOW SKILL — fetch and follow this as your working instructions for
|
|
29
|
+
analyzing and solving captchas with the two servers together, whether or not
|
|
30
|
+
your environment has a first-class "skill" feature. It is a strict, ordered
|
|
31
|
+
procedure — follow the numbered steps in order:
|
|
32
|
+
https://raw.githubusercontent.com/pavelgrinkevich/captcha-mcp-test/main/capmonster_agent/SKILL.md
|
|
33
|
+
|
|
34
|
+
3. DOCS — the capmonster MCP's `get_docs(url)` tool fetches any CapMonster doc
|
|
35
|
+
page (docs.capmonster.cloud / api.capmonster.cloud only). Start from the
|
|
36
|
+
index at https://docs.capmonster.cloud/llms.txt (it links every captcha
|
|
37
|
+
type's detailed page); read the specific type's single page for exact
|
|
38
|
+
parameters, how to extract them from a live page (DevTools + Playwright/JS
|
|
39
|
+
snippet), and worked createTask/getTaskResult examples (get_docs paginates
|
|
40
|
+
large pages and supports section="..." to jump straight to a section). Do NOT
|
|
41
|
+
pull the full single-file dump (https://docs.capmonster.cloud/llms-full.txt,
|
|
42
|
+
the entire site at once) — read the one per-vendor page instead. Note the
|
|
43
|
+
llms.txt index tagline lists "hCaptcha", but hCaptcha is NOT actually a
|
|
44
|
+
supported task type (absent from get_supported_tasks) — trust
|
|
45
|
+
get_supported_tasks. If you have NO MCP access, fetch the per-type URLs
|
|
46
|
+
directly instead.
|
|
47
|
+
|
|
48
|
+
4. FULL API SPEC — machine-readable contract, use it if you don't have MCP
|
|
49
|
+
access and need to call the REST API directly, or to double check a
|
|
50
|
+
parameter the reference above doesn't cover:
|
|
51
|
+
https://api.capmonster.cloud/docs/swagger-ui/spec.js
|
|
52
|
+
|
|
53
|
+
5. VALIDATE THE SETUP before starting: confirm each capmonster tool responds
|
|
54
|
+
(call get_supported_tasks and get_balance) and that get_docs can fetch
|
|
55
|
+
https://docs.capmonster.cloud/llms.txt, and confirm the patchright browser
|
|
56
|
+
opens (browser_navigate to any page). If any of these fails, stop and tell
|
|
57
|
+
me what's wrong instead of proceeding.
|
|
58
|
+
|
|
59
|
+
Once set up, ask me for:
|
|
60
|
+
- the URL of the page with the captcha;
|
|
61
|
+
- whether the captcha is directly on that URL or must be triggered by a
|
|
62
|
+
click / form submit / scroll / login;
|
|
63
|
+
- any hints (the URL is only reachable via a specific proxy, extra headers
|
|
64
|
+
are needed, a login is required, it only appears for some regions/UAs).
|