# aws-knowledge-plus

A Kiro Power for the AWS knowledge sources the [official AWS Knowledge MCP Server](https://aws.amazon.com/about-aws/whats-new/2025/10/aws-knowledge-mcp-server-generally-available/) does not index.

## Why this exists

The official server is free, unauthenticated, maintained by AWS, and already covers AWS documentation, AWS blogs, What's New, Well-Architected, and re:Post Knowledge Center articles. Rebuilding any of that would mean scraping undocumented endpoints for content already available through a supported interface.

So this power covers only what the official server rejects. Its `read_documentation` allow-list is the authoritative boundary:

| Source | Official server | This power |
| --- | --- | --- |
| `docs.aws.amazon.com` (incl. Well-Architected) | Covered | — |
| `aws.amazon.com/blogs`, What's New | Covered | — |
| `repost.aws/knowledge-center` | Covered | — |
| `repost.aws/questions` (community Q&A) | **Not covered** | Full search + full thread read |
| `kiro.dev` (docs, blog, changelog) | **Not covered** | Full index search + clean markdown read |
| `builder.aws.com` (Builder Center, incl. **AWS Builders' Library**) | **Not covered** | Finds articles across the published archive; no article bodies |

`aws.amazon.com/builders-library/` redirects to Builder Center, and the official server refuses the redirect target, so the Builders' Library is unreachable through it. That redirect is the single clearest example of why this power exists.

The boundary above is not a fixed list: it is whatever the official server's own allow-list happens to be, which AWS changes over time. Its `read_documentation` error message names the current allow-list verbatim, so treat that as the live source of truth and this table as a snapshot. If AWS starts indexing one of these three, the corresponding source here becomes redundant and should be dropped rather than kept for its own sake.

## Prerequisites

- [`uv`](https://docs.astral.sh/uv/getting-started/installation/) on `PATH` (provides `uvx`). The power needs no Python of its own; `uv` fetches an interpreter.
- The official AWS Knowledge MCP Server, for everything in the "Covered" rows above. This power deliberately does **not** declare it, so that clients which already have it do not open a second connection to the same endpoint and load a duplicate set of tools. If you do not have it yet, add this to `~/.kiro/settings/mcp.json`:

  ```json
  {
    "mcpServers": {
      "aws-knowledge": {
        "url": "https://knowledge-mcp.global.api.aws/mcp"
      }
    }
  }
  ```

## Install

**From GitHub (recommended for teams)**

1. Kiro → Powers panel → **Add Custom Power** → **Import power from GitHub**
2. Paste this repository's URL

**From a local clone**

1. `git clone https://github.com/hey-iam-ryan/kiro-power-aws-knowledge-plus`
2. Kiro → Powers panel → **Add Custom Power** → **Import power from a folder**
3. Select the cloned directory

**Without the Powers panel** — add the server straight to `~/.kiro/settings/mcp.json`:

```json
{
  "mcpServers": {
    "aws-knowledge-plus": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/hey-iam-ryan/kiro-power-aws-knowledge-plus@v0.2.1",
        "aws-knowledge-plus-mcp"
      ],
      "autoApprove": ["search_aws_knowledge", "read_aws_content", "list_sources"]
    }
  }
}
```

The first launch resolves the dependency tree and takes a few seconds; later launches are cached by `uv`.

The server is keyed `sources` in the power's own `mcp.json` but `aws-knowledge-plus` in the snippet above, and that difference is deliberate. Kiro registers a power's servers as `power-<powerName>-<serverName>`, so keying it `aws-knowledge-plus` inside a power of the same name would resolve to `power-aws-knowledge-plus-aws-knowledge-plus`. The prefix already carries the power name. Nothing namespaces a server you add to `mcp.json` yourself, so there the full name is the useful one.

## Using this power in a team

**This power is read-only for everyone except the maintainer.** On a public
GitHub repository, only accounts explicitly added as collaborators can push, and
none are. Cloning, installing and forking do not grant any ability to change what
your teammates install.

**Installs are pinned to a release tag, not to `main`.** `mcp.json` points at
`@v0.2.1`, so every teammate runs the same reviewed code even while `main` moves
on. Nobody is silently upgraded.

Need a change? Open an issue or a pull request. The maintainer reviews it, merges
it, and cuts a new tag; teammates pick it up when the pin is updated.

Shipping a new version, for the maintainer. The pin has to be bumped **before**
tagging, otherwise the tag ships the previous version's pin and teammates
installing it get the older code:

```bash
uv run python smoke_test.py                    # must pass: it hits the live sources

# 1. bump the version and the pin together
#    - pyproject.toml   version = "0.3.0"
#    - plugin.json      "version": "0.3.0"
#    - mcp.json         ...@v0.3.0
#    - README.md        every @v0.2.1 occurrence
git commit -am "Release v0.3.0"
git push origin main

# 2. only now tag the commit that carries the correct pin
git tag -a v0.3.0 -m "v0.3.0"
git push origin v0.3.0
```

Release tags are protected against deletion and force-moves, so a published tag
cannot be repointed. A mistake in a release is corrected by shipping the next
version, not by rewriting the last one.

## Tools

| Tool | Purpose |
| --- | --- |
| `search_aws_knowledge(query, sources?, limit?)` | Search all sources in parallel. `sources` accepts `repost`, `kiro`, `builder`. A slow or broken source degrades to an `errors` entry instead of failing the call. |
| `read_aws_content(url, start_index?, max_length?)` | Read a page as markdown, dispatched by host, with explicit truncation markers for resuming. |
| `list_sources()` | What is covered, what is not, and why. |

Search snippets are intentionally short: they exist to help pick what to read, not to answer from.

### What the reads look like

- **re:Post** — rebuilt from the thread's schema.org `QAPage` data, so you get the question plus every answer with authors, dates, vote counts, and the accepted-answer marker. No HTML scraping, and code blocks survive intact.
- **kiro.dev docs** — fetched from the published markdown twin (`/docs/steering` reads `/docs/steering.md`), so there is no site chrome to strip.
- **Builder Center** — title, plus a summary when the site's feed published one, and an explicit note that the body was not retrieved. Discovery walks the site's sitemaps, whose location is read from `robots.txt` rather than assumed, so the whole published archive is searchable rather than just what a feed happens to expose.

## Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `AWS_KNOWLEDGE_PLUS_ENABLE_BUILDER` | `1` | Set `0` to drop Builder Center from federated search. |
| `AWS_KNOWLEDGE_PLUS_BUILDER_MIN_SCORE` | `0.34` | Relevance floor for Builder Center. Slug matching is noisier than matching real titles, so raise it to cut community noise or lower it to surface more. |
| `AWS_KNOWLEDGE_PLUS_CACHE_TTL` | `900` | Response cache TTL, seconds. |
| `AWS_KNOWLEDGE_PLUS_TIMEOUT` | `20` | Per-request timeout, seconds. |
| `AWS_KNOWLEDGE_PLUS_USER_AGENT` | Chrome-like UA | re:Post challenges non-browser agents. Override with care. |

## Known limitations

- **Builder Center gives you the article, not its text.** Bodies render client-side; the page's only `ld+json` block is a generic `WebSite` record, `<head>` carries site-wide boilerplate, and unauthenticated paths on the site's backend answer 403. Search finds the right article and hands over the URL. Titles come from the site's feed for recent posts and are otherwise derived from the URL slug, which the result discloses in `meta.title_source`. Topic hubs under `/learn/` contain no readable text at all.
- **re:Post search depth.** The site honours `pageSize` but not `page`, so results come from a single larger page rather than deep pagination.
- **Undocumented endpoints.** re:Post's search response is read from the `__NEXT_DATA__` payload its own page embeds. That is not a published API and can change. The adapter tolerates both payload shapes it currently emits and returns an empty result rather than crashing if neither is found, but a redesign of the site would need a fix here.

## Development

```bash
uv sync
uv run python smoke_test.py     # live checks against all three sources
uv run aws-knowledge-plus-mcp   # start on stdio
```

`smoke_test.py` hits the real sites, so it doubles as a canary: if a source changes its markup or payload, it fails there first.

## Security

Outbound requests are restricted to an allow-list built from each adapter's declared host and path prefixes. Redirects are followed one hop at a time and every hop is re-validated, so a redirect cannot walk the fetcher onto an unlisted host. Only `https` is accepted. Requests carry no credentials, and every source is public.

## License

Apache-2.0