Metadata-Version: 2.4
Name: post-truegrit-mcp
Version: 0.1.1
Summary: Postiz MCP client with an opt-in local egress connector
Project-URL: Homepage, https://github.com/mengbingrock/post-truegrit-mcp
Project-URL: Repository, https://github.com/mengbingrock/post-truegrit-mcp
Author: Postiz
License: AGPL-3.0-only
License-File: LICENSE
Requires-Python: >=3.9
Requires-Dist: httpx<1,>=0.27
Requires-Dist: keyring<27,>=25
Requires-Dist: websockets<16,>=14
Description-Content-Type: text/markdown

# post-truegrit-mcp

`post-truegrit-mcp` installs a `postiz-mcp` command that combines the remote
Postiz MCP endpoint with an opt-in local
egress connector. The MCP tools and scheduling logic stay on the Postiz
server. Only allow-listed HTTPS connections can leave through the local
machine, and only while a short-lived lease is active.

## Install and configure

```bash
python3 -m pip install post-truegrit-mcp
postiz-mcp configure \
  --url https://post.truegrit.dev/post/mcp \
  --device-name my-mac
```

The command securely prompts for the API key, which is stored in the
operating-system keyring. The non-secret server URL and stable device ID are
stored in `~/.config/postiz-mcp/config.json`.
Set `POSTIZ_API_KEY` instead on systems without a usable keyring.

## Install from a development checkout

```bash
git clone https://github.com/mengbingrock/post-truegrit-mcp.git
cd post-truegrit-mcp
python3 -m venv .venv-postiz-mcp
.venv-postiz-mcp/bin/python -m pip install --upgrade pip
.venv-postiz-mcp/bin/python -m pip install -e .
.venv-postiz-mcp/bin/postiz-mcp configure \
  --url https://post.truegrit.dev/post/mcp \
  --device-name my-mac
```

Editable installation means later changes from `git pull` are immediately
used by the installed `postiz-mcp` command. Windows users can replace
`.venv-postiz-mcp/bin/` with `.venv-postiz-mcp\\Scripts\\`.

Add the local bridge to Codex:

```toml
[mcp_servers.postiz]
command = "postiz-mcp"
args = ["serve"]
```

Or add it to Claude Code:

```bash
claude mcp add postiz -- postiz-mcp serve
```

The `serve` process transparently forwards MCP JSON-RPC over stdio and keeps
an outbound secure WebSocket connected for local egress. It never opens a
listening port on the user's machine.

Multiple MCP clients can safely use the same configured device. A local
process lock elects one connector owner; additional `serve` processes continue
forwarding MCP calls without replacing the owner or interrupting an active
egress lease. If the owner exits, a waiting process automatically takes over.

## On-demand egress

With the MCP client running, an agent can call `egressProxyStartTool`,
`egressProxyTestTool`, and `egressProxyStopTool`. The same controls are
available from a shell:

```bash
postiz-mcp proxy status
postiz-mcp proxy start --ttl-minutes 30
postiz-mcp proxy test
postiz-mcp proxy stop
```

The server currently permits only HTTPS port 443 to ChineseInLA domains and
the IP-check host used by the test command. Leases expire automatically after
5–60 minutes. Stopping the local process immediately closes all streams.
