hf-mcp
hf-mcp is a standalone MCP server package for the Hack Forums API v2.
Current release line: 0.6.1.
The PyPI publisher workflow runs only on an explicit manual dispatch. Export
boundary checks also resolve files from a standalone hf-mcp product checkout.
Version 0.6.1 keeps offline source builds aligned with the declared backend requirements and includes the linked MyCode reference in installed skill data.
Version 0.6.0 adds purpose-specific descriptions to the registered MCP tools, using the canonical tool registry while preserving names, schemas, and access policy. The descriptions identify local effects such as formatting preflight and draft management, and distinguish live write requests from local work.
Version 0.4.6 combines complete Draft 2020-12 input-schema publication and validation before SDK argument parsing with pinned development tooling and offline child-process checks. Local schema references resolve only within the supplied schema. Invalid values such as numeric strings, booleans used as integers, and unknown fields are rejected; omitted optional values keep their existing defaults.
Version 0.4.4 pinned the development, test, and build tools and added isolated
source checks for the export boundary. Version 0.4.2 publishes and enforces the
complete Draft 2020-12 input schema while preserving original JSON types; it
declared jsonschema>=4.20.0 and referencing>=0.30.0 as direct runtime
dependencies. The 0.4.1 release tightened the published schemas for Bytes
deposits and withdrawals and kept hf.doctor as a local catalog fact without
exposing a callable diagnostic tool. The 0.4.0 release recorded canonical tool
facts and derived locality metadata and behavior hints from the registry.
Install
pip install hf-mcp
Entrypoints
hf-mcp(aliaseshf-mcp serve)python -m hf_mcphf-mcp setup inithf-mcp auth bootstraphf-mcp doctorhf-mcp serve
Desktop MCP clients
Desktop client wiring is first-class and documented in
docs/client_integration.md, including:
- direct command launch (
hf-mcp serve) - module launch (
python -m hf_mcp serve) - virtualenv/conda launch forms
- native Windows Python launch
- Windows desktop client to WSL bridge examples (including Claude Desktop style)
ChatGPT through a private tunnel
For the current ChatGPT Plugins custom MCP flow and an outbound-only OpenAI
Secure MCP Tunnel, see docs/chatgpt_tunnel.md. The
ChatGPT connection uses full_api by default to expose all 24 currently
supported tools. A four-tool read-only profile is documented as an optional
restriction. Keep ChatGPT's config separate from other agents' settings; local
readiness and end-to-end ChatGPT acceptance are different checks.
Default local paths
- config:
~/.config/hf_mcp/config.yaml - token store:
~/.config/hf_mcp/token.json
Path overrides:
HF_MCP_CONFIGfor config pathHF_MCP_ENV_FILEfor explicit.envpathHF_MCP_TOKEN_PATHfor token path (unless YAMLtoken_pathis set)
Full precedence and policy split are documented in docs/configuration.md.
Read output defaults
Read tools default to human-readable content while keeping canonical JSON for scripts.
- default mode:
readable - per-call override:
output_mode(readable,structured,raw) - additive raw payload toggle:
include_raw_payload
Compatibility contract for read tools:
structuredContentalways carries normalized/canonical JSON for automation.output_mode="readable"is the human surface; for thread reads it includes the formatted thread body plus useful thread and first-post fields.output_mode="structured"keeps script-friendlystructuredContentwith terse text.- raw payload remains available as an additive JSON resource when
output_mode="raw"orinclude_raw_payload=true.
See docs/configuration.md for read_output_defaults config and
docs/examples.md for concrete request/response examples.
Compounding flow discovery
Use forums.index (alias forums_index) for root discovery when you do not yet
have IDs. This tool is backed by maintained package catalog data and can drift
from live Hack Forums state between package updates.
Concrete exploration path:
forums.index->forums.read->threads.read->posts.readforums.readstill requiresfid; it is not root discovery._hf_flowis the machine-readable flow envelope key._hf_flow.next_actionsis the communication layer that lets one tool result feed the next tool call without an agent guessing selectors._hf_flowcurrently ships onforums.index, core reads, supported extended reads (bytes.read,contracts.read,disputes.read,bratings.read,sigmarket.market.read, andsigmarket.order.read), local draft/preflight tools, and successful results from existing guarded write helpers after confirmed or stubbed execution.
Automation usage
For automated clients, call read tools with output_mode="structured" when you only
need normalized fields, or output_mode="raw" / include_raw_payload=true when
you also need the exact upstream HF API payload as an additive MCP resource.
Example:
{
"tool": "posts.read",
"arguments": {
"tid": 6324346,
"per_page": 1,
"include_post_body": true,
"output_mode": "raw",
"include_raw_payload": true
}
}
Expected protocol shape:
{
"content": [
{"type": "text", "text": "posts.read returned 1 row(s)."},
{"type": "resource", "resource": {"uri": "hf-mcp://raw/posts.read", "mimeType": "application/json"}}
],
"structuredContent": {
"posts": [
{
"pid": "62946370",
"tid": "6324346",
"subject": "The HF API MCP server",
"message": "[size=xx-large][align=center][css=68]HF MCP Is Live..."
}
]
}
}
Quick start
pip install hf-mcp
hf-mcp setup init
hf-mcp auth bootstrap
hf-mcp doctor
hf-mcp serve
Before auth bootstrap, create your own Hack Forums API developer app in the HF
user control panel. You can use the hosted callback
https://cortalabs.github.io/hf_mcp/oauth_callback.html for
HF_MCP_EXTERNAL_REDIRECT_URI, or host docs/oauth_callback.html yourself and
use that HTTPS URL instead.
Module launch equivalent:
python -m hf_mcp serve
Development checks
Install the pinned development tools with python -m pip install -e ".[dev]".
The source test lane uses temporary HF config, token, and draft paths. Pytest
blocks outbound IPv4 and IPv6 sockets while allowing Unix-domain IPC for local
asyncio stdio tests. This parent-process guard does not propagate to child
processes. Child probes must use the isolated_child_context fixture, which
supplies allowlisted synthetic state and installs a deny-all network guard
before the child imports the package. From the product checkout, run the
targeted source and quality checks with:
python -m pytest tests/test_export_boundary.py tests/test_entrypoints.py tests/test_onboarding_cli.py -q
python -m pytest tests/test_export_boundary.py -k hermetic -q --randomly-seed=1729 -n 2
python -m ruff check src/hf_mcp/__init__.py tests/conftest.py tests/test_export_boundary.py --select E4,E7,E9,F,I
python -m ruff format --check tests/conftest.py
python -m mypy src/hf_mcp/__init__.py
The version reported by a source checkout comes from its local pyproject.toml;
installed builds use distribution metadata and report 0.0.0+unknown only when
that metadata is unavailable. These are development checks and do not publish a
distribution.
Safety and release posture
- Read paths and guarded writes are documented publicly, with fail-closed behavior for concrete writes via
confirm_live=true. - Concrete write helpers currently exposed are
threads.create,posts.reply, and Bytes write helpers (bytes.transfer,bytes.deposit,bytes.withdraw,bytes.bump) with repaired argument contracts. scheduled_aton draft artifacts is metadata for operator workflow only;hf-mcpdoes not ship a scheduler/queue that auto-executes future writes.- HF API quote/entity canonicalization on live writes is treated as expected security/sanitization behavior, not a bypass target.
- Manual live validation in this wave is intentionally narrower: replies only on
TID 6083735plus at most onethreads.createinFID 375; no Bytes live writes. contracts.writeis not exposed in this release because operator-approved sandbox proof is unavailable.- Signature Market write operations and admin-only high-risk write operations are unsupported and unexposed.
- PM counters (
unreadpms,totalpms) are available throughme.readwhen Advanced Info fields are enabled; direct PM content operations are unsupported. - Detailed release-boundary and limitation truth is owned by
docs/export_boundary.md.
Docs map
Metadata
Release files for hf-mcp 0.6.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hf_mcp-0.6.1.tar.gz | 175.8 kB | With provenance | Details for hf_mcp-0.6.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hf_mcp-0.6.1-py3-none-any.whl | Python 3 | none | any | Details for hf_mcp-0.6.1-py3-none-any.whl |
Total release size: 285.3 kB
Release files / hf_mcp-0.6.1.tar.gz
| Download URL | hf_mcp-0.6.1.tar.gz |
|---|---|
| Size | 175.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f101ebbd41779a8d8c871658cebe952d2520c68f539a046ebae2d38911e90ba4
|
|
BLAKE2b-256 checksum How to use checksums |
14969eca5c9040ec3730f976e2190d6d7d95f3b6503e007cf85298a398875c13
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logRelease files / hf_mcp-0.6.1-py3-none-any.whl
| Download URL | hf_mcp-0.6.1-py3-none-any.whl |
|---|---|
| Size | 109.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9a251d443a0dd617d1e980c1b0f948dbb7089fa879c03a8e0e481c3d95c2c490
|
|
BLAKE2b-256 checksum How to use checksums |
f448122579b4b79288fa9c8cb830e605ce4ba3e7d295b1213cf3f32b3cebc447
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logSecurity for hf-mcp 0.6.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for hf_mcp-0.6.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.