feat(pkgsite): adapt v1 API and redis rate limiting (#28)

Author: garrettladley

README.md

@@ -1,7 +1,7 @@
 # pkgsite-mcp
 
 MCP tools for looking up current Go module and package information from the
-official `pkg.go.dev/v1beta` API.
+official `pkg.go.dev/v1` API.
 
 Use it when you want a coding agent to answer Go dependency questions with
 structured pkg.go.dev data instead of guessing from model memory, scraping HTML,
@@ -146,7 +146,7 @@ Health endpoint:
 http://localhost:8080/health
 ```
 
-Start optional Redis for local caching and rate limiting:
+Start Redis for local caching and distributed rate limiting:
 
 ```sh
 just up
@@ -179,7 +179,7 @@ http://localhost:8080/mcp
 ## Configuration
 
 ```text
-PKGSITE_BASE_URL=https://pkg.go.dev/v1beta
+PKGSITE_BASE_URL=https://pkg.go.dev/v1
 KV_REDIS_URL=redis://localhost:9736/0
 KV_REDIS_POOL_SIZE=4
 KV_REDIS_MIN_IDLE_CONNS=2
@@ -205,8 +205,9 @@ O11Y_ENABLE_LOGS=true
 O11Y_ENABLE_METRICS=true
 ```
 
-Redis is optional. Without `KV_REDIS_URL`, requests go directly to pkg.go.dev and
-IP rate limiting is disabled. When Redis is configured, it backs both pkg.go.dev
-response caching and fixed-window IP rate limiting for `/mcp`.
+Redis backs response caching, the distributed outbound pkg.go.dev 45-QPS limiter,
+and fixed-window IP rate limiting for `/mcp`. Without `KV_REDIS_URL`, caching and
+both Redis-backed limiters are disabled; requests use direct upstream access
+without a process-local fallback limiter.
 
 Sentry is optional. Without `SENTRY_DSN`, observability calls stay no-op.

fly.toml

@@ -8,7 +8,7 @@ primary_region = 'iad'
 [build]
 
 [env]
-  PKGSITE_BASE_URL = 'https://pkg.go.dev/v1beta'
+  PKGSITE_BASE_URL = 'https://pkg.go.dev/v1'
   PKGSITE_CACHE_DISABLED = 'false'
 
 [http_service]

internal/config/config.go

@@ -104,7 +104,7 @@ func read(getenv func(string) string) (Config, error) {
 			EnableMetrics:    p.boolean("O11Y_ENABLE_METRICS", true),
 		},
 		Pkgsite: Pkgsite{
-			BaseURL:       p.str("PKGSITE_BASE_URL", "https://pkg.go.dev/v1beta"),
+			BaseURL:       p.str("PKGSITE_BASE_URL", "https://pkg.go.dev/v1"),
 			HTTPTimeout:   p.duration("PKGSITE_HTTP_TIMEOUT", 10*time.Second),
 			CacheDisabled: p.boolean("PKGSITE_CACHE_DISABLED", false),
 		},

internal/config/config_test.go

@@ -21,7 +21,7 @@ func TestReadDefaults(t *testing.T) {
 	if got.Observability.FlushTimeout != 2*time.Second {
 		t.Fatalf("FlushTimeout = %s, want 2s", got.Observability.FlushTimeout)
 	}
-	if got.Pkgsite.BaseURL != "https://pkg.go.dev/v1beta" {
+	if got.Pkgsite.BaseURL != "https://pkg.go.dev/v1" {
 		t.Fatalf("BaseURL = %q, want default", got.Pkgsite.BaseURL)
 	}
 	if got.Pkgsite.HTTPTimeout != 10*time.Second {

internal/mcpserver/skills/docs/operations.md

@@ -5,3 +5,14 @@ Use `pkgsite_module` for module metadata, `pkgsite_versions` for available versi
 Use `pkgsite_package` for package documentation metadata and `pkgsite_symbols` for exported API facts. `pkgsite_symbols` is usually the highest-signal tool for coding agents.
 
 Use `pkgsite_vulns` before making security-sensitive recommendations. Use `pkgsite_imported_by` sparingly because the result set can be large.
+
+List operations accept an upstream `filter` written as a Go expression that returns a boolean. The supported subset is:
+
+- values `true`, `false`, and `nil`;
+- `==` and `!=` on any value;
+- `+`, `-`, `*`, `/`, and `%` on integers;
+- `+` on strings;
+- `<`, `<=`, `>`, and `>=` on strings and integers; and
+- parenthesized expressions.
+
+The functions `contains(s, sub)`, `hasPrefix(s, pre)`, `hasSuffix(s, suf)`, and `matches(s, re)` are also available. `matches` takes a regular expression; a bare regular expression is not a valid filter. Each route exposes its JSON fields as variables, so examples include `name == "main"` for packages, `kind == "Type"` for symbols, and `hasPrefix(version, "v2.")` for versions. Pass the expression as plain text; the client percent-encodes query parameters.

internal/mcpserver/skills/docs/overview.md

@@ -1,6 +1,6 @@
 # pkgsite-mcp overview
 
-Use pkgsite-mcp when you need current structured facts from `pkg.go.dev/v1beta` about Go modules, packages, versions, exported symbols, imported-by relationships, or vulnerabilities.
+Use pkgsite-mcp when you need current structured facts from `pkg.go.dev/v1` about Go modules, packages, versions, exported symbols, imported-by relationships, or vulnerabilities.
 
 The source of truth is pkg.go.dev. This server is read-only and does not clone repositories, scrape HTML, or infer facts from training data.
 

internal/mcpserver/skills/docs/pagination.md

@@ -4,4 +4,6 @@ There are two pagination layers.
 
 Upstream pkg.go.dev pagination uses `limit` and `token`. When a response includes `upstreamNextPageToken`, pass it as `token` to fetch the next upstream page.
 
+Keep the rest of the upstream request unchanged when following a token; only add or replace `token`. A non-empty `upstreamNextPageToken` means another page exists even when the current page has no items.
+
 Local display pagination uses `start_at` and `max_tokens`. When metadata includes `next_start_at`, repeat the same tool call with that `start_at` to see the next local batch from the current upstream response.

internal/mcpserver/skills/docs/precision.md

@@ -2,6 +2,8 @@
 
 Package paths can be ambiguous across modules. If a package lookup returns candidates or an ambiguity message, repeat the call with `module_path`.
 
+Error responses preserve the upstream `message`, `fixes`, and `candidates` fields. Prefer the suggested containing module from `candidates` or `fixes` instead of guessing which module owns an ambiguous package path.
+
 Use version-pinned calls when answering compatibility questions. Empty `version` means latest and can change.
 
 Do not treat absence of a field as proof unless the raw upstream response makes that absence clear.

internal/mcpserver/tools/docs/pkgsite_imported_by.md

@@ -1 +1,3 @@
 List packages that import a package. Defaults to a conservative upstream limit because results can be large.
+
+`filter` must be a Go expression that returns a boolean. It supports `true`, `false`, and `nil`; `==` and `!=` on any value; `+`, `-`, `*`, `/`, and `%` on integers; `+` on strings; `<`, `<=`, `>`, and `>=` on strings and integers; and parenthesized expressions. The functions `contains(s, sub)`, `hasPrefix(s, pre)`, `hasSuffix(s, suf)`, and `matches(s, re)` are available. `matches` takes a regular expression; a bare regular expression is not a valid filter. The route's JSON fields are available as variables; for imported-by results, use `path` to filter paths. Pass the expression as plain text; the client percent-encodes query parameters.

internal/mcpserver/tools/docs/pkgsite_packages.md

@@ -1 +1,3 @@
 List packages contained in a module version from pkg.go.dev.
+
+`filter` must be a Go expression that returns a boolean. It supports `true`, `false`, and `nil`; `==` and `!=` on any value; `+`, `-`, `*`, `/`, and `%` on integers; `+` on strings; `<`, `<=`, `>`, and `>=` on strings and integers; and parenthesized expressions. The functions `contains(s, sub)`, `hasPrefix(s, pre)`, `hasSuffix(s, suf)`, and `matches(s, re)` are available. `matches` takes a regular expression; a bare regular expression is not a valid filter. JSON fields from each package are available as variables. Example: `name == "main"`. Pass the expression as plain text; the client percent-encodes query parameters.