Metadata-Version: 2.4
Name: tcpping-mcp-server
Version: 0.1.4
Summary: A modern MCP server for TCP ping testing via pingloc.com
Author-email: chenxizhang <ares@xizhang.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/chenxizhang/devbox
Project-URL: Repository, https://github.com/chenxizhang/devbox
Project-URL: Issues, https://github.com/chenxizhang/devbox/issues
Project-URL: Source (Subdir), https://github.com/chenxizhang/devbox/tree/master/tcpping/mcp/stdio
Keywords: tcp,ping,latency,mcp,model context protocol,playwright
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: System :: Monitoring
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: playwright>=1.45.0
Requires-Dist: fastmcp>=0.1.0
Dynamic: license-file

## tcpping MCP Server (stdio)

Minimal TCP latency probe server for MCP clients (e.g. GitHub Copilot Agents) using Playwright + FastMCP.

> 0.1.4: Added resilient fallback parsing (summary pattern search + heuristic row scan) and debug artifacts when structure changes on pingloc.com.

### 1. Add to your MCP client config
Example (`mcp.json` / Copilot Agents user settings):
```jsonc
"tcpping-mcp-server": {
	"type": "stdio",
	"command": "uvx",
	"args": [
		"tcpping-mcp-server"
	]
}
```
`uvx` will fetch & run the published script (or local cache) by name. You can also swap for `python -m tcpping_mcp_stdio.modern_server` if installed in a venv.

### 2. Available tool
Tool name: `tcpping_run`

Parameters (all optional unless noted):
- target (str, required) – domain or URL (scheme optional)
- port (int, default 443)
- timeout (float, default 120)
- retries (int, default 1)
- headless (bool, default true)
- browser_channel (str, default "msedge")
- debug (bool, default false) – dump HTML/screenshot if no rows
- summary_only (bool, default false) – return compact summary

### 3. Example call (conceptual JSON-RPC)
```json
{
	"jsonrpc": "2.0",
	"id": "1",
	"method": "tools/call",
	"params": {
		"name": "tcpping_run",
		"arguments": { "target": "example.com", "summary_only": true }
	}
}
```

### 4. Local install (optional)
```bash
pip install tcpping-mcp-server
tcpping-mcp-server  # or: python -m tcpping_mcp_stdio.modern_server
```

### 5. Playwright browser dependency
First run will auto-download browsers when using `uvx` or after pip install. If needed manually:
```bash
playwright install chromium
```

### 6. Output
Returns a JSON string (you may need to parse once):
```
{
	"host": "example.com:443",
	"summary": { ... },
	"probes": [ ... ],
	"probe_count": 25,
	"timeouts": 0,
	"duration_sec": 12.34
}
```

### 7. Debugging
Set `debug=true` to dump HTML + screenshot into `tcpping/debug/` when no probe rows captured.

---
Concise goal: drop the snippet above into your MCP client config and start using `tcpping_run`.

### 8. Release / Publish (maintainers)
Workflow using `uv`:

1. Bump version in `pyproject.toml` and `src/tcpping_mcp_stdio/modern_server.py` (the `VERSION` constant). Use semver.
2. Clean previous builds (optional):
	```powershell
	Remove-Item dist -Recurse -Force -ErrorAction SilentlyContinue
	```
3. Build artifacts:
	```powershell
	uv build
	```
4. (Optional) TestPyPI dry run:
	```powershell
	$Env:TEST_PYPI_API_TOKEN = 'pypi-AgENdGVzdC4uLg=='  # your TestPyPI token
	uv publish --repository testpypi --token $Env:TEST_PYPI_API_TOKEN
	```
5. Publish to PyPI:
	```powershell
	$Env:PYPI_API_TOKEN = 'pypi-AgEN...'   # never commit this
	uv publish --token $Env:PYPI_API_TOKEN
	```
6. Verify installation:
	```powershell
	uvx tcpping-mcp-server --help
	```
7. Tag in git (optional but recommended):
	```powershell
	git tag v<version>
	git push origin v<version>
	```

If `uv publish` reports missing token, ensure the environment variable name matches the one you pass after `--token`.
