PortHub
PortHub is a local-first tool for storing and retrieving Markdown context by hierarchical keys via CLI and MCP.
MVP Scope
- Local filesystem storage only (default:
~/.porthub; configurable viaPORTHUB_HOMEor--root). - CLI workflows plus an MCP stdio server.
- Five commands:
set,get,search,list,server. - Exact match for
get. - Case-insensitive substring match for
search(with optional key-only/content-only modes).
Install
Install the CLI tool:
uv tool install -U porthub
Or run directly without installation:
uvx porthub --help
For local development in this repository:
uv sync
You can run commands either through uv:
uv run porthub --help
Or through the installed script:
porthub --help
Usage
Set Markdown content from an inline string:
porthub set python/typer "# Typer\nCLI framework for Python"
Set Markdown content from a file:
porthub set python/typer --file ./notes/typer.md
Set Markdown content from stdin:
cat ./notes/typer.md | porthub set python/typer --stdin
Get content by exact key:
porthub get python/typer
Search by key or content (case-insensitive):
porthub search typer
Search by key only:
porthub search typer --key-only
Search by content only:
porthub search typer --content-only
Limit search results:
porthub search typer --limit 10
List all keys:
porthub list
Use a custom storage root for any command:
porthub --help
porthub list --root ./tmp-porthub
porthub get python/typer --root ./tmp-porthub
Or set a default storage root via environment variable:
export PORTHUB_HOME=./tmp-porthub
porthub list
MCP Server
Start MCP server over stdio:
uv run porthub server
uvx porthub server
Use custom storage root:
uv run porthub server --root ./tmp-porthub
Default MCP tools (namespaced):
porthub_get(key)porthub_set(key, value)porthub_search(query, mode=\"all\"|\"key\"|\"content\", limit=None)porthub_list()
Tool responses are structured JSON objects with:
ok(trueorfalse)error(nullor{code, message})- tool payload fields such as
key,content,matches,keys
Example MCP client configuration (same pattern as uvx + args):
{
"mcpServers": {
"porthub": {
"command": "uvx",
"args": ["porthub", "server"]
}
}
}
With custom storage root:
{
"mcpServers": {
"porthub": {
"command": "uvx",
"args": ["porthub", "server", "--root", "./tmp-porthub"]
}
}
}
Skills
This repository includes a local skill for package-documentation retrieval workflows:
- Install (method 1):
npx skills add narumiruna/porthub
- Install (method 2):
npx ctx7 skills install narumiruna/porthub
- Skill source:
skills/porthub/SKILL.md
Key Rules
A key is valid only when all rules pass:
- It is not empty after trimming spaces.
- It does not start or end with
/. - It does not contain
//. - It does not contain
... - It does not end with
.md.
Error Behavior
- Validation failures return non-zero exit code.
getreturns non-zero when a key is not found.searchreturns empty output with exit code0when no match exists.searchreturns non-zero when--key-onlyand--content-onlyare both provided.searchreturns non-zero when--limitis not greater than0.setreturns non-zero unless exactly one content source is provided:- positional
value --file--stdin
- positional
Metadata
Release files for porthub 0.0.6
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 |
|---|---|---|---|---|
| porthub-0.0.6.tar.gz | 5.9 kB | Without provenance | Details for porthub-0.0.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| porthub-0.0.6-py3-none-any.whl | Python 3 | none | any | Details for porthub-0.0.6-py3-none-any.whl |
Total release size: 13.2 kB
Release files / porthub-0.0.6.tar.gz
| Download URL | porthub-0.0.6.tar.gz |
|---|---|
| Size | 5.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ff51280c8b70fa2f80a5b8cc54796a22cdb76ab44a1ccae9dbfa30acb3a9e7d0
|
|
BLAKE2b-256 checksum How to use checksums |
e481d1201de248ef9e1628e10bf54f1b0b578f356915a9342c3308c2c5534dd2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.11 {"installer":{"name":"uv","version":"0.10.11","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / porthub-0.0.6-py3-none-any.whl
| Download URL | porthub-0.0.6-py3-none-any.whl |
|---|---|
| Size | 7.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3cc6c7d224d6a349b413038d8091522fcf184a04c7e91a5e90b64b63a4b38b7b
|
|
BLAKE2b-256 checksum How to use checksums |
d841005b29b9a09417eb5f7b0d560bdf054c3043b9db50c8fe8d00c04e12ae81
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.11 {"installer":{"name":"uv","version":"0.10.11","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for porthub 0.0.6
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A 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.