Skip to content

README.md

Latest commit

 

History

History
158 lines (119 loc) · 3.78 KB

README.md

File metadata and controls

158 lines (119 loc) · 3.78 KB
Raw

Hypertxt Python

The official Python client, command-line interface, and MCP server for Hypertxt.

Use it to:

  • inspect account credits, projects, article templates, and articles;
  • retrieve, generate, export, review, archive, or publish articles;
  • query synchronized or live Google Search Console performance;
  • give MCP-compatible agents a deliberately scoped content-operations toolset.

Install

Install the CLI and MCP server into an isolated environment:

pipx install hypertxt

Or run the MCP server without a permanent install:

uvx --from hypertxt hypertxt-mcp

Python applications can install it with:

python -m pip install hypertxt

Authenticate

Create a named, revocable key in Hypertxt → Account → Automation. Keep it out of source control and chat transcripts:

export HYPERTXT_API_KEY="htx_replace_with_your_key"
hypertxt status
hypertxt projects

The client uses https://app.hypertxt.ai by default. Set HYPERTXT_API_URL only when testing against another Hypertxt deployment.

CLI examples

# Inspect
hypertxt status
hypertxt articles list --project-id 12 --status awaiting_review
hypertxt articles get 451

# Query GSC
hypertxt gsc query \
  --project-id 12 \
  --group-by query \
  --query-contains "mcp" \
  --start-date 2026-07-01 \
  --end-date 2026-07-25

# Generate after checking credits
hypertxt articles generate \
  --project-id 12 \
  --workflow-id 8 \
  --title "How editorial teams use MCP" \
  --keyword "MCP content workflow"

# Record editorial approval, then create a destination draft
hypertxt articles state 451 reviewed
hypertxt articles publish 451 --integration-id 9 --publish-status draft

Pass --json before the command for machine-readable output.

MCP

Start the stdio server:

hypertxt-mcp

Minimal MCP configuration:

{
  "mcpServers": {
    "hypertxt": {
      "command": "uvx",
      "args": ["--from", "hypertxt", "hypertxt-mcp"],
      "env": {
        "HYPERTXT_API_KEY": "${HYPERTXT_API_KEY}"
      }
    }
  }
}

The server exposes read tools separately from actions that spend credits, change editorial state, refresh GSC, or publish. Agents should inspect first and obtain approval before calling mutating tools.

Client-specific setup and downloadable prompts:

OpenClaw skill

Install the companion portable Hypertxt skill from its public repository:

openclaw skills install \
  git:simplebytes-com/hypertxt-openclaw@main \
  --as hypertxt

Configure the MCP server separately so the skill has tools to call. Start with the read-only tool filter in the OpenClaw guide, then enable generation, state changes, GSC refreshes, and publishing when you want the agent to perform those actions.

Python

from hypertxt import HypertxtClient

with HypertxtClient() as client:
    status = client.account_status()
    articles = client.list_articles(project_id=12, status="awaiting_review")

Development

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
ruff check src tests
mypy src
pytest -q
python -m build

Security

  • Use a different named key for every client or machine.
  • Never paste an htx_… key into an LLM conversation.
  • Prefer environment or secret configuration over command arguments.
  • Inspect the full article before changing state or publishing.
  • Make generation and live publishing explicit.