tcpping-mcp-server 0.1.5
A modern MCP server for TCP ping testing via pingloc.com
Requires Python: >=3.9
Keywords: tcp, ping, latency, mcp, model context protocol, playwright

## 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`.