Metadata-Version: 2.4
Name: amv-mcp-hub
Version: 4.0.0
Summary: stdio MCP server for Python and Android Termux: host shell/Python execution, calculator, text, hash, UUID, regex and vector tools (standard library only).
Author: AMEVA Foundation
License: Apache-2.0
Project-URL: Homepage, https://uno-km.vercel.app/lib/mcp/
Project-URL: Repository, https://github.com/uno-km/amv-mcp-hub
Project-URL: Issues, https://github.com/uno-km/amv-mcp-hub/issues
Keywords: mcp,model-context-protocol,mcp-server,termux,android,stdio
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Operating System :: Android
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: wasm
Requires-Dist: wasmtime>=20; extra == "wasm"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# amv-mcp-hub (Python)

A [Model Context Protocol](https://modelcontextprotocol.io) server that runs over stdio. It is written in Python with the standard library only, so it works on desktop Python and in Android Termux. It is the Python counterpart of the npm package [`amv-mcp-hub`](https://www.npmjs.com/package/amv-mcp-hub). Both expose the same core tools, so either one can back the same MCP client setup.

```bash
pip install amv-mcp-hub
amv-mcp-hub --version
amv-mcp-hub --list-tools
```

## Use it from an MCP client

The server speaks newline-delimited JSON-RPC 2.0 on stdin/stdout and writes its logs to stderr. It opens no network port.

```json
{
  "mcpServers": {
    "amv-mcp-hub": { "command": "amv-mcp-hub" }
  }
}
```

If the console script is not on `PATH`, use `"command": "python", "args": ["-m", "amv_mcp_hub"]` instead.

## Tools

| Tool | What it does |
|---|---|
| `run_shell_command` | Runs a command in the host shell (`sh`, or PowerShell on Windows). It is killed after `AMV_HUB_SHELL_TIMEOUT_MS` (default 120000). |
| `python_exec` | Runs Python code in a subprocess of the same interpreter. The tool arguments are available as `__args__`. Timeout is 15 s. |
| `smart_exec` | Routes code by language: `python` goes to Python, `js` to `node` (if it is installed), `math` to the calculator. Anything else runs in the shell. |
| `calc` | Arithmetic with `+ - * / % ^` and parentheses. It is parsed with `ast`, not `eval`, and results are formatted like JavaScript. |
| `format_json`, `text_transform`, `base64_encode`, `hash_text` | JSON pretty-printing, text case and reversal, Base64 encoding and decoding, and hashlib digests. |
| `generate_uuid`, `timestamp_convert`, `regex_match` | UUID v4, the current time as UTC/ISO/Unix, and regular-expression matches (Python `re` syntax). |
| `vector_cosine_similarity`, `vector_top_k_search` | Cosine similarity, and top-k ranking of `{id, vector, text, metadata}` documents. |
| `wasm_exec` | Runs a WASI preview-1 module given as Base64. It is listed only when the optional `wasmtime` package is installed (`pip install "amv-mcp-hub[wasm]"`). wasmtime has no Android build. |

## Security

The execution tools run with the privileges of the server process and are not sandboxed. Any MCP client you connect can run commands as your user. Connect only clients you trust. The Python server has no HTTP or WebSocket interface.

## Protocol

- Protocol revisions: 2025-06-18, 2025-03-26 and 2024-11-05. The server echoes the client's revision when it supports it; otherwise it offers the newest one.
- Supported methods: `initialize`, `ping`, `tools/list`, `tools/call`, and notifications. JSON-RPC batches are also accepted.
- Errors: `-32700` parse error, `-32600` invalid request, `-32601` unknown method, `-32602` unknown tool or missing tool name, `-32603` tool crash.
- Tool calls run on a small thread pool, so a long command does not delay `ping` or other requests.

## License

Apache-2.0
