hf-mcp 0.1.0__tar.gz

hf_mcp-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include pyproject.toml
+include MANIFEST.in
+include config.example.yaml
+include export_manifest.toml
+recursive-include docs *.md
+recursive-include tests *.py
+recursive-include src/hf_mcp *.py
+global-exclude __pycache__ *.py[cod]

hf_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: hf-mcp
+Version: 0.1.0
+Summary: Standalone Hack Forums MCP launch surface
+Keywords: hackforums,mcp,model-context-protocol
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: mcp>=1.0.0
+
+# hf-mcp
+
+`hf-mcp` is a standalone MCP server package for the Hack Forums API v2.
+
+## Product target
+
+The product target is full documented Hack Forums API coverage. The registry and
+coverage matrix include:
+
+- core read helpers (`me`, `users`, `forums`, `threads`, `posts`)
+- extended read helpers (`bytes`, `contracts`, `disputes`, `bratings`)
+- later-lane documented read/write rows for `sigmarket`, `contract`, and
+  documented `admin/high-risk` helpers
+- documented write helpers (`threads.create`, `posts.reply`, `bytes.transfer`,
+  `bytes.deposit`, `bytes.withdraw`, `bytes.bump`)
+
+## Exposure model
+
+Profiles and overlays are an exposure control layer for a specific user or
+deployment. They do not redefine product scope. If a deployment disables a row,
+that row still remains in the documented product coverage matrix.
+
+## Launch surface
+
+- console entrypoint: `hf-mcp`
+- module entrypoint: `python -m hf_mcp`
+- `hf-mcp` aliases `hf-mcp serve` (stdio runtime launch)
+- `hf-mcp setup init` creates first-run local config and prints the next commands
+- `hf-mcp doctor` validates local config/secrets/token readiness without network I/O
+- `hf-mcp` ships the `mcp` runtime dependency required for the stdio launch path
+- `hf-mcp serve` runs one stdio server instance and exits when the stdio client disconnects
+- `hf-mcp serve` fails closed on invalid bootstrap state (config/secrets/token/runtime dependency)
+
+## First run
+
+```bash
+pip install hf-mcp
+hf-mcp setup init
+```
+
+Set secrets in your local environment (`.env` or shell):
+
+```bash
+export HF_MCP_CLIENT_ID=your_client_id
+export HF_MCP_CLIENT_SECRET=your_client_secret
+```
+
+Finish local bootstrap and readiness checks:
+
+```bash
+hf-mcp auth bootstrap
+hf-mcp doctor
+hf-mcp serve
+```
+
+## Source distribution boundary
+
+`MANIFEST.in` defines a package-local source distribution boundary rooted in
+`products/hf_mcp`. The source distribution includes package docs, tests, and
+runtime source from this product subtree only.
+
+## Documentation
+
+- `docs/configuration.md`
+- `docs/coverage_matrix.md`
+- `docs/security_model.md`
+- `docs/export_boundary.md`

hf_mcp-0.1.0/README.md

@@ -0,0 +1,67 @@
+# hf-mcp
+
+`hf-mcp` is a standalone MCP server package for the Hack Forums API v2.
+
+## Product target
+
+The product target is full documented Hack Forums API coverage. The registry and
+coverage matrix include:
+
+- core read helpers (`me`, `users`, `forums`, `threads`, `posts`)
+- extended read helpers (`bytes`, `contracts`, `disputes`, `bratings`)
+- later-lane documented read/write rows for `sigmarket`, `contract`, and
+  documented `admin/high-risk` helpers
+- documented write helpers (`threads.create`, `posts.reply`, `bytes.transfer`,
+  `bytes.deposit`, `bytes.withdraw`, `bytes.bump`)
+
+## Exposure model
+
+Profiles and overlays are an exposure control layer for a specific user or
+deployment. They do not redefine product scope. If a deployment disables a row,
+that row still remains in the documented product coverage matrix.
+
+## Launch surface
+
+- console entrypoint: `hf-mcp`
+- module entrypoint: `python -m hf_mcp`
+- `hf-mcp` aliases `hf-mcp serve` (stdio runtime launch)
+- `hf-mcp setup init` creates first-run local config and prints the next commands
+- `hf-mcp doctor` validates local config/secrets/token readiness without network I/O
+- `hf-mcp` ships the `mcp` runtime dependency required for the stdio launch path
+- `hf-mcp serve` runs one stdio server instance and exits when the stdio client disconnects
+- `hf-mcp serve` fails closed on invalid bootstrap state (config/secrets/token/runtime dependency)
+
+## First run
+
+```bash
+pip install hf-mcp
+hf-mcp setup init
+```
+
+Set secrets in your local environment (`.env` or shell):
+
+```bash
+export HF_MCP_CLIENT_ID=your_client_id
+export HF_MCP_CLIENT_SECRET=your_client_secret
+```
+
+Finish local bootstrap and readiness checks:
+
+```bash
+hf-mcp auth bootstrap
+hf-mcp doctor
+hf-mcp serve
+```
+
+## Source distribution boundary
+
+`MANIFEST.in` defines a package-local source distribution boundary rooted in
+`products/hf_mcp`. The source distribution includes package docs, tests, and
+runtime source from this product subtree only.
+
+## Documentation
+
+- `docs/configuration.md`
+- `docs/coverage_matrix.md`
+- `docs/security_model.md`
+- `docs/export_boundary.md`

hf_mcp-0.1.0/config.example.yaml

@@ -0,0 +1,39 @@
+# hf-mcp capability exposure configuration
+#
+# Presets:
+# - reader: read-oriented exposure
+# - forum_operator: read + core content/bytes write exposure
+# - full_api: broadest shipped exposure preset (explicit opt-in)
+# - custom: start empty and explicitly opt in
+#
+# IMPORTANT:
+# Presets are exposure control for a user/deployment. They do not reduce product
+# scope. The product target remains full documented HF API coverage, including
+# later-lane contract, sigmarket, and admin/high-risk rows tracked in
+# docs/coverage_matrix.md.
+
+profile: reader
+
+# Optional explicit overlays for any profile.
+# These keep naming human-readable and fail closed on unknown values.
+# enabled_capabilities: []
+# enabled_parameter_families: []
+# disabled_capabilities: []
+# disabled_parameter_families: []
+
+# Optional runtime path override. Must be absolute and outside this repository.
+# token_path: /home/you/.config/hf_mcp/token.json
+
+# Capabilities currently exposed by profile = "full_api":
+# me.read, users.read, forums.read, threads.read, posts.read, bytes.read,
+# contracts.read, disputes.read, bratings.read, sigmarket.market.read,
+# sigmarket.order.read, threads.create, posts.reply, bytes.transfer,
+# bytes.deposit, bytes.withdraw, bytes.bump, contracts.write,
+# sigmarket.write, admin.high_risk.read, admin.high_risk.write
+
+# Parameter families currently exposed by profile = "full_api":
+# selectors.user, selectors.forum, selectors.thread, selectors.post,
+# selectors.bytes, selectors.contract, selectors.dispute, selectors.sigmarket,
+# filters.pagination, fields.me.basic, fields.me.advanced,
+# fields.users.profile, fields.posts.body, fields.bytes.amount,
+# writes.content, writes.bytes, confirm.live

hf_mcp-0.1.0/docs/configuration.md

@@ -0,0 +1,90 @@
+# Configuration
+
+`hf-mcp` uses a presets-first configuration model with fail-closed overlays.
+
+## Scope and exposure control
+
+The product scope is the full documented Hack Forums API surface captured in the
+coverage matrix. Configuration is an exposure control mechanism for the active
+user or deployment:
+
+- `enabled_capabilities` and `disabled_capabilities` decide which tool families
+  can register.
+- `enabled_parameter_families` and `disabled_parameter_families` decide which
+  schema inputs remain visible and accepted.
+
+This means a deployment can disable `sigmarket`, `contract`, or
+`admin/high-risk` rows without redefining the product target.
+
+## Profiles
+
+- `reader`: read-oriented exposure profile.
+- `forum_operator`: read + core forum/content/bytes write exposure.
+- `full_api`: broadest shipped exposure profile.
+- `custom`: starts empty; caller opts in explicitly.
+
+`reader` is the recommended first-run profile. Use `full_api` as an explicit
+opt-in when validating the full documented coverage surface.
+
+## First-run setup flow
+
+Run the terminal-native onboarding commands in this order:
+
+```bash
+pip install hf-mcp
+hf-mcp setup init
+```
+
+Then set local secrets (for example in `.env` or shell):
+
+```bash
+export HF_MCP_CLIENT_ID=your_client_id
+export HF_MCP_CLIENT_SECRET=your_client_secret
+```
+
+Complete auth/bootstrap and local readiness validation:
+
+```bash
+hf-mcp auth bootstrap
+hf-mcp doctor
+hf-mcp serve
+```
+
+## Runtime configuration responsibilities
+
+- YAML is the canonical runtime config input for non-secret policy:
+  `profile`, capability overlays, parameter-family overlays, and optional
+  `token_path`.
+- `.env` is for secrets and machine-local overrides only (for example
+  `HF_MCP_CLIENT_ID`, `HF_MCP_CLIENT_SECRET`, `HF_MCP_TOKEN_PATH`).
+- `.env` must not be used to choose non-secret runtime policy such as
+  `profile`, capability families, or parameter families.
+- `token_path` must resolve to an absolute path outside the tracked repository.
+
+## Overlays
+
+Overlays are additive/subtractive and always validated against known family
+names:
+
+- `enabled_capabilities`
+- `disabled_capabilities`
+- `enabled_parameter_families`
+- `disabled_parameter_families`
+
+Unknown names fail fast during config load.
+
+## Example
+
+```yaml
+profile: reader
+
+disabled_capabilities:
+  - sigmarket.market.read
+  - sigmarket.order.read
+
+disabled_parameter_families:
+  - fields.me.advanced
+```
+
+The example above is still the same product. It is a narrower exposure profile
+for one deployment.

hf_mcp-0.1.0/docs/coverage_matrix.md

@@ -0,0 +1,38 @@
+# Coverage Matrix
+
+This matrix tracks the public product target for `hf-mcp`: full documented HF
+API coverage. Deployment policy can hide rows, but rows remain in-scope product
+coverage.
+
+## Registry-backed rows
+
+| Coverage family | Operation | Helper path | Product scope status | Exposure note |
+|---|---|---|---|---|
+| `me.read` | read | `me` | in scope | can be disabled by capability policy |
+| `users.read` | read | `users` | in scope | can be disabled by capability policy |
+| `forums.read` | read | `forums` | in scope | can be disabled by capability policy |
+| `threads.read` | read | `threads` | in scope | can be disabled by capability policy |
+| `posts.read` | read | `posts` | in scope | can be disabled by capability policy |
+| `bytes.read` | read | `bytes` | in scope | can be disabled by capability policy |
+| `contracts.read` | read | `contracts` | in scope (later-lane row retained) | deployment exposure control may keep disabled |
+| `disputes.read` | read | `disputes` | in scope | can be disabled by capability policy |
+| `bratings.read` | read | `bratings` | in scope | can be disabled by capability policy |
+| `sigmarket.market.read` | read | `sigmarket/market` | in scope (later-lane row retained) | deployment exposure control may keep disabled |
+| `sigmarket.order.read` | read | `sigmarket/order` | in scope (later-lane row retained) | deployment exposure control may keep disabled |
+| `admin.high_risk.read` | read | `admin/high-risk/read` | in scope (documented admin/high-risk row retained) | deployment exposure control may keep disabled |
+| `threads.create` | write | `threads` | in scope | `confirm_live` guard required |
+| `posts.reply` | write | `posts` | in scope | `confirm_live` guard required |
+| `bytes.transfer` | write | `bytes` | in scope | `confirm_live` guard required |
+| `bytes.deposit` | write | `bytes/deposit` | in scope | `confirm_live` guard required |
+| `bytes.withdraw` | write | `bytes/withdraw` | in scope | `confirm_live` guard required |
+| `bytes.bump` | write | `bytes/bump` | in scope | `confirm_live` guard required |
+| `contracts.write` | write | `contracts` | in scope (later-lane contract row retained) | deployment exposure control may keep disabled until helper proof is named |
+| `sigmarket.write` | write | `sigmarket` | in scope (later-lane sigmarket row retained) | deployment exposure control may keep disabled until helper proof is named |
+| `admin.high_risk.write` | write | `admin/high-risk/write` | in scope (documented admin/high-risk row retained) | deployment exposure control may keep disabled until helper proof is named |
+
+## Interpretation
+
+- A disabled row is still part of product scope.
+- A later-lane row is still part of product scope.
+- If documented HF API coverage expands, this matrix must add named rows rather
+  than replacing specifics with vague future language.

hf_mcp-0.1.0/docs/export_boundary.md

@@ -0,0 +1,28 @@
+# Export Boundary
+
+`hf-mcp` is published from a product subtree. Export is allowlist-based.
+
+## Authoritative manifest
+
+`export_manifest.toml` is the machine-readable allowlist for exported files.
+Allowed entries are scoped to `products/hf_mcp/` only.
+
+## Included public surfaces
+
+- package metadata and launch docs (`pyproject.toml`, `README.md`)
+- example configuration (`config.example.yaml`)
+- public documentation (`docs/**`)
+- package source (`src/hf_mcp/**`)
+- package tests (`tests/**`)
+
+## Boundary guarantees
+
+- Root-level repository assets are outside the export boundary.
+- Internal orchestration/planning assets are outside the export boundary.
+- Release packaging should fail if any allowlist entry leaves the
+  `products/hf_mcp/` subtree.
+- Runtime policy is YAML-first: non-secret policy belongs in `config.yaml`.
+- `.env` is reserved for secrets and machine-local overrides; it must not define
+  profile/capability/parameter policy.
+- Token-store location must be an absolute path outside the tracked repository
+  tree.

hf_mcp-0.1.0/docs/security_model.md

@@ -0,0 +1,25 @@
+# Security Model
+
+`hf-mcp` is a networked MCP server for live HF API calls, so every enabled tool
+should be treated as open-world input/output.
+
+## Core controls
+
+- Capability policy is fail-closed. Unknown capability or parameter-family names
+  fail config load.
+- Parameter-family pruning keeps schema exposure aligned with runtime validation.
+- Documented write helpers require explicit `confirm_live = true`.
+- Capability and parameter families can restrict user exposure for high-risk
+  rows such as `contract`, `sigmarket`, and `admin/high-risk` helpers.
+
+## Secret handling
+
+- Keep OAuth client credentials and access tokens in private runtime storage.
+- Do not commit credentials into config files, docs, or tests.
+- Rotate credentials if they are ever exposed.
+
+## Operational guidance
+
+- Start from read-oriented exposure when validating a new deployment.
+- Enable write families deliberately and verify each path with test coverage.
+- Keep audit logs outside the tracked package tree.

hf_mcp-0.1.0/export_manifest.toml

@@ -0,0 +1,12 @@
+manifest_version = 1
+package_root = "products/hf_mcp"
+
+allowlist = [
+  "products/hf_mcp/README.md",
+  "products/hf_mcp/pyproject.toml",
+  "products/hf_mcp/config.example.yaml",
+  "products/hf_mcp/export_manifest.toml",
+  "products/hf_mcp/docs/**",
+  "products/hf_mcp/src/hf_mcp/**",
+  "products/hf_mcp/tests/**",
+]

hf_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hf-mcp"
+version = "0.1.0"
+description = "Standalone Hack Forums MCP launch surface"
+keywords = ["hackforums", "mcp", "model-context-protocol"]
+classifiers = [
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Topic :: Internet",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["PyYAML>=6.0", "mcp>=1.0.0"]
+
+[project.scripts]
+hf-mcp = "hf_mcp.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

hf_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hf_mcp-0.1.0/src/hf_mcp/__init__.py

@@ -0,0 +1,4 @@
+"""Public package root for the standalone hf-mcp launch surface."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

hf_mcp-0.1.0/src/hf_mcp/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hf_mcp-0.1.0/src/hf_mcp/annotations.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from .metadata import build_tool_meta
+from .registry import ToolSpec
+
+
+def build_annotations(spec: ToolSpec) -> dict[str, object]:
+    is_read = spec.operation == "read"
+    return {
+        "readOnlyHint": is_read,
+        "destructiveHint": not is_read,
+        "idempotentHint": is_read,
+        "openWorldHint": True,
+        "_meta": build_tool_meta(spec),
+    }
+
+
+__all__ = ["build_annotations"]

hf_mcp-0.1.0/src/hf_mcp/auth.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Mapping
+
+from .config import HFMCPSettings
+from .token_store import TokenBundle
+
+DEFAULT_AUTHORIZE_ENDPOINT = "https://hackforums.net/api/v2/authorize"
+
+
+def authorize_via_loopback(settings: HFMCPSettings, open_browser: bool = True) -> TokenBundle:
+    client_id = _required_setting(settings, "HF_MCP_CLIENT_ID")
+    client_secret = _required_setting(settings, "HF_MCP_CLIENT_SECRET")
+
+    redirect_uri = settings.runtime_env.get("HF_MCP_REDIRECT_URI", "http://127.0.0.1:8765/callback")
+    authorize_url = settings.runtime_env.get("HF_MCP_AUTHORIZE_URL", DEFAULT_AUTHORIZE_ENDPOINT)
+    token_url = settings.runtime_env.get("HF_MCP_TOKEN_URL", DEFAULT_AUTHORIZE_ENDPOINT)
+
+    timeout_raw = settings.runtime_env.get("HF_MCP_AUTH_TIMEOUT_SECONDS", "180")
+    try:
+        timeout_seconds = int(timeout_raw)
+    except (TypeError, ValueError) as exc:
+        raise ValueError("HF_MCP_AUTH_TIMEOUT_SECONDS must be an integer number of seconds.") from exc
+
+    state = secrets.token_urlsafe(24)
+    browser_url = _build_authorize_url(
+        authorize_url=authorize_url,
+        client_id=client_id,
+        redirect_uri=redirect_uri,
+        state=state,
+    )
+
+    if open_browser:
+        webbrowser.open(browser_url)
+
+    callback_params = _await_loopback_callback(redirect_uri=redirect_uri, timeout_seconds=timeout_seconds)
+    callback_state = callback_params.get("state")
+    if callback_state != state:
+        raise ValueError("OAuth callback state mismatch. Aborting token exchange.")
+
+    code = callback_params.get("code")
+    if code is None or not code.strip():
+        raise ValueError("OAuth callback is missing authorization code.")
+
+    token_payload = _exchange_code_for_token(
+        token_url=token_url,
+        client_id=client_id,
+        client_secret=client_secret,
+        code=code,
+        redirect_uri=redirect_uri,
+    )
+    return TokenBundle.from_payload(token_payload)
+
+
+def _build_authorize_url(
+    authorize_url: str,
+    client_id: str,
+    redirect_uri: str,
+    state: str,
+) -> str:
+    params = urllib.parse.urlencode(
+        {
+            "client_id": client_id,
+            "response_type": "code",
+            "redirect_uri": redirect_uri,
+            "state": state,
+        }
+    )
+    separator = "&" if "?" in authorize_url else "?"
+    return f"{authorize_url}{separator}{params}"
+
+
+def _await_loopback_callback(redirect_uri: str, timeout_seconds: int) -> Mapping[str, str]:
+    parsed_uri = urllib.parse.urlparse(redirect_uri)
+    host = parsed_uri.hostname
+    port = parsed_uri.port
+    callback_path = parsed_uri.path or "/callback"
+
+    if host not in {"127.0.0.1", "localhost"}:
+        raise ValueError("Redirect URI must use localhost or 127.0.0.1 loopback host.")
+    if port is None:
+        raise ValueError("Redirect URI must include an explicit loopback port.")
+
+    callback_state: dict[str, str] = {}
+
+    class _CallbackHandler(BaseHTTPRequestHandler):
+        def do_GET(self) -> None:  # noqa: N802 (standard library method name)
+            parsed_request = urllib.parse.urlparse(self.path)
+            if parsed_request.path != callback_path:
+                self.send_response(404)
+                self.end_headers()
+                return
+
+            parsed_query = urllib.parse.parse_qs(parsed_request.query, keep_blank_values=True)
+            for key in ("code", "state", "error"):
+                values = parsed_query.get(key)
+                if values:
+                    callback_state[key] = values[0]
+
+            self.send_response(200)
+            self.send_header("Content-Type", "text/plain; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(b"You can close this tab and return to the terminal.")
+
+        def log_message(self, format: str, *args: object) -> None:  # noqa: A003
+            del format, args
+            return
+
+    server = HTTPServer((host, port), _CallbackHandler)
+    server.timeout = 0.25
+
+    deadline = time.monotonic() + timeout_seconds
+    while time.monotonic() < deadline and "code" not in callback_state and "error" not in callback_state:
+        server.handle_request()
+
+    server.server_close()
+
+    if "error" in callback_state:
+        raise ValueError(f"OAuth provider returned error: {callback_state['error']}")
+    if "code" not in callback_state:
+        raise TimeoutError("Timed out waiting for OAuth loopback callback.")
+    return callback_state
+
+
+def _exchange_code_for_token(
+    token_url: str,
+    client_id: str,
+    client_secret: str,
+    code: str,
+    redirect_uri: str,
+) -> dict[str, object]:
+    encoded_payload = urllib.parse.urlencode(
+        {
+            "client_id": client_id,
+            "client_secret": client_secret,
+            "code": code,
+            "grant_type": "authorization_code",
+            "redirect_uri": redirect_uri,
+        }
+    ).encode("utf-8")
+
+    request = urllib.request.Request(
+        token_url,
+        data=encoded_payload,
+        method="POST",
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+    )
+
+    try:
+        with urllib.request.urlopen(request, timeout=15) as response:
+            response_body = response.read().decode("utf-8")
+    except urllib.error.HTTPError as error:
+        error_body = error.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"Token exchange failed: HTTP {error.code}. {error_body}") from error
+
+    parsed = json.loads(response_body)
+    if not isinstance(parsed, dict):
+        raise ValueError("Token exchange returned non-object JSON payload.")
+    return parsed
+
+
+def _required_setting(settings: HFMCPSettings, name: str) -> str:
+    value = settings.runtime_env.get(name) or os.environ.get(name)
+    if value is None or not value.strip():
+        raise ValueError(f"Missing required environment variable: {name}")
+    return value.strip()
+
+
+__all__ = ["authorize_via_loopback"]