cameronrye/gopher-mcp

Bypass the cached copy of this URL and fetch it from the server again. Set it to true when the user wants the current state -- 'check again', 'did they post yet?', 'that looks out of date' -- or when a previous result came back with cached: true and a cache_age_seconds too large to answer the question honestly. A window fetched with offset also reports cached: true, having been rendered from the download the first window made rather than fetched again. cache_age_seconds says how old those bytes are, the same as for any other cached result, and the decision follows from the age alone. Refreshing part-way through a walk discards every window of that resource, not just the one asked for, so the windows already read are re-downloaded when they are next read -- prefer finishing the walk and re-reading after it. Leave it false for ordinary browsing and link-following: Gopher and Gemini are served mostly by small hobbyist hosts that the cache spares from repeat traffic. Either way the response returned is stored for later reads.

Gemini URLs to fetch, at most 50 per call. Results come back in the same order and of the same length as this list.

Hostname to report on, e.g. astrobotany.mozz.us . Omit to list every scope holding an identity -- which is in effect the list of capsules this user has an account or pseudonym on, so name the host you are actually asking about unless the user wants the whole store.

"create" mints a new identity for the URL scope and stores it; from then on every request in that scope carries it, so the capsule can link those visits to one another. It never replaces an existing in-scope certificate. "remove" destroys the certificate covering the scope, including its private key, which cannot be recovered.

Required for "remove" and rejected for "create": the SHA-256 fingerprint of the certificate being destroyed, as hex with or without colons and an optional 'sha256:' prefix. Call gemini_client_cert_list and copy the value it reports. That is an interlock, not bookkeeping: it stops an unrecoverable private key being deleted without naming which identity is being destroyed.

The gemini:// URL the identity applies to -- for "create", the URL that answered status 60, and to act on a stored identity, the url gemini_client_cert_list reports for it, passed back unchanged. The certificate covers this path and everything below it and nothing else, so gemini://host/app/page.gmi covers that one page while gemini://host/app/ covers the whole section; pass the directory form only when the user means the whole section, because a wider scope means more of their browsing is linkable. A URL with no path -- gemini://host/ -- is the widest of all: it mints one identity for the WHOLE capsule, so every request to it from then on is linkable to every other. Any query string is ignored.

Optional answer to a Gemini status-10/11 input prompt. It is percent-encoded and sent as the query string, so pass the raw answer (spaces, &, = and unicode are handled for you). Replaces any query already present in url.

Where to start reading, for a resource that came back truncated. Pass the next_offset of the previous result -- it counts menu items for a Gopher menu and characters for a page body -- to get the next window; leave it 0 (the default) to read from the beginning. A result with truncated: true and a next_offset is the signal that there is more: continue from it rather than presenting a partial page as the whole one, and stop when next_offset comes back null. Continuing is usually cheap -- the resource is downloaded once and the later windows are rendered from it -- with two exceptions: every window re-downloads when caching is off, and a GEMINI url carrying a query re-downloads always, because the answer to a status-10/11 prompt travels there and is never held. So read on because the content is needed, not by reflex.

Bypass the cached copy of this URL and fetch it from the server again. Set it to true when the user wants the current state -- 'check again', 'did they post yet?', 'that looks out of date' -- or when a previous result came back with cached: true and a cache_age_seconds too large to answer the question honestly. A window fetched with offset also reports cached: true, having been rendered from the download the first window made rather than fetched again. cache_age_seconds says how old those bytes are, the same as for any other cached result, and the decision follows from the age alone. Refreshing part-way through a walk discards every window of that resource, not just the one asked for, so the windows already read are re-downloaded when they are next read -- prefer finishing the walk and re-reading after it. Leave it false for ordinary browsing and link-following: Gopher and Gemini are served mostly by small hobbyist hosts that the cache spares from repeat traffic. Either way the response returned is stored for later reads.

A full gemini:// URL, e.g. gemini://geminiprotocol.net/ . On a status-10/11 input response, call again with the input argument set to the user's answer instead of hand-building a query string. Geminispace has no usable search engine: kennedy.gemi.dev and tlgs.one are worth browsing, but both disallow their /search paths in robots.txt, so a search URL there comes back BLOCKED_BY_ROBOTS.

Hostname to report on, e.g. geminiprotocol.net . Omit to list every pinned host -- which is in effect the list of capsules this user has visited, so name the host you are actually asking about unless the user wants the whole store.

"remove" drops the pin, so the next fetch trusts and re-pins whichever certificate the host presents -- the recovery for a reissue the user has confirmed is expected. "pin" replaces the pin with fingerprint outright, for when the user already has the new fingerprint from the operator or another trusted channel.

SHA-256 certificate fingerprint as hex, with or without colons and an optional 'sha256:' prefix. For "remove" this must equal the fingerprint currently pinned for the host -- call gemini_trust_list and copy the value it reports. That is an interlock, not bookkeeping: it stops a pin being dropped without naming what is being dropped. For "pin" it is the NEW fingerprint to trust, which must come from the user or the capsule operator, never from the server being pinned.

The one hostname to act on. There is no wildcard and no 'all hosts': every pin has to be changed deliberately, by name.

Port of the pinned entry. Gemini's default is 1965.

Bypass the cached copy of this URL and fetch it from the server again. Set it to true when the user wants the current state -- 'check again', 'did they post yet?', 'that looks out of date' -- or when a previous result came back with cached: true and a cache_age_seconds too large to answer the question honestly. A window fetched with offset also reports cached: true, having been rendered from the download the first window made rather than fetched again. cache_age_seconds says how old those bytes are, the same as for any other cached result, and the decision follows from the age alone. Refreshing part-way through a walk discards every window of that resource, not just the one asked for, so the windows already read are re-downloaded when they are next read -- prefer finishing the walk and re-reading after it. Leave it false for ordinary browsing and link-following: Gopher and Gemini are served mostly by small hobbyist hosts that the cache spares from repeat traffic. Either way the response returned is stored for later reads.

Gopher URLs to fetch, at most 50 per call. Results come back in the same order and of the same length as this list. There is no search argument here: put a type-7 query in the URL itself, or call gopher_fetch, which percent-encodes the terms for you.

Where to start reading, for a resource that came back truncated. Pass the next_offset of the previous result -- it counts menu items for a Gopher menu and characters for a page body -- to get the next window; leave it 0 (the default) to read from the beginning. A result with truncated: true and a next_offset is the signal that there is more: continue from it rather than presenting a partial page as the whole one, and stop when next_offset comes back null. Continuing is usually cheap -- the resource is downloaded once and the later windows are rendered from it -- with two exceptions: every window re-downloads when caching is off, and a GEMINI url carrying a query re-downloads always, because the answer to a status-10/11 prompt travels there and is never held. So read on because the content is needed, not by reflex.

Bypass the cached copy of this URL and fetch it from the server again. Set it to true when the user wants the current state -- 'check again', 'did they post yet?', 'that looks out of date' -- or when a previous result came back with cached: true and a cache_age_seconds too large to answer the question honestly. A window fetched with offset also reports cached: true, having been rendered from the download the first window made rather than fetched again. cache_age_seconds says how old those bytes are, the same as for any other cached result, and the decision follows from the age alone. Refreshing part-way through a walk discards every window of that resource, not just the one asked for, so the windows already read are re-downloaded when they are next read -- prefer finishing the walk and re-reading after it. Leave it false for ordinary browsing and link-following: Gopher and Gemini are served mostly by small hobbyist hosts that the cache spares from repeat traffic. Either way the response returned is stored for later reads.

Terms for a type-7 (Index-Search) selector, e.g. Veronica-2. They are percent-encoded and sent as the query string, so pass the user's words raw: a query holding #, +, & or non-ASCII is truncated or mangled when written into the URL by hand, and the server then answers a search that was never asked. Replaces any query already present in url. Leave it unset for every other item type -- RFC 1436 gives only type 7 a query field, so a search sent elsewhere is dropped.

A full gopher:// URL. The first path character is the item type (1=menu, 0=text file, 7=search). Follow next_url from menu items to navigate. To query a type-7 search server, give the URL of the search selector itself -- gopher://gopher.floodgap.com/7/v2/vs -- and pass the terms in search, never as extra path segments. A query string written into the URL (gopher://gopher.floodgap.com/7/v2/vs?python) still works, but search is what handles #, + and non-ASCII correctly. Example: gopher://gopher.floodgap.com/1/