From a9becb81f0540f9caeb78b090eec2ebfe1dfbca2 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:23:06 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 15 ++ README.md | 3 + commands/read.md | 37 ++++ commands/recommend.md | 42 ++++ commands/search.md | 41 ++++ plugin.lock.json | 57 +++++ skills/aws-knowledge-tool/SKILL.md | 336 +++++++++++++++++++++++++++++ 7 files changed, 531 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/read.md create mode 100644 commands/recommend.md create mode 100644 commands/search.md create mode 100644 plugin.lock.json create mode 100644 skills/aws-knowledge-tool/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..8cdb8fe --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "aws-knowledge-tool", + "description": "CLI tool for querying AWS Knowledge MCP Server - search, read, and discover AWS documentation", + "version": "0.1.0", + "author": { + "name": "Dennis Vriend", + "email": "dvriend@ilionx.com" + }, + "skills": [ + "./skills" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..be61e75 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# aws-knowledge-tool + +CLI tool for querying AWS Knowledge MCP Server - search, read, and discover AWS documentation diff --git a/commands/read.md b/commands/read.md new file mode 100644 index 0000000..9fe296a --- /dev/null +++ b/commands/read.md @@ -0,0 +1,37 @@ +--- +description: Read AWS documentation page as markdown +argument-hint: url +--- + +Read AWS documentation from URL and convert to markdown format. + +## Usage + +```bash +aws-knowledge-tool read "URL" [--start-index N] [--max-length M] [--json] +``` + +## Arguments + +- `URL`: AWS documentation URL (required) +- `--start-index N` / `-s N`: Starting character index +- `--max-length M` / `-m M`: Maximum characters to fetch +- `--json`: Output JSON format +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +## Examples + +```bash +# Read full document +aws-knowledge-tool read "https://docs.aws.amazon.com/lambda/latest/dg/welcome.html" + +# Read with pagination +aws-knowledge-tool read "https://docs.aws.amazon.com/..." --start-index 5000 --max-length 2000 + +# Pipeline from search +aws-knowledge-tool search "Lambda" --json | jq -r '.[0].url' | aws-knowledge-tool read --stdin +``` + +## Output + +Returns markdown-formatted documentation content from docs.aws.amazon.com or aws.amazon.com domains. diff --git a/commands/recommend.md b/commands/recommend.md new file mode 100644 index 0000000..d5e56d7 --- /dev/null +++ b/commands/recommend.md @@ -0,0 +1,42 @@ +--- +description: Get related AWS documentation recommendations +argument-hint: url +--- + +Discover related documentation through four recommendation types. + +## Usage + +```bash +aws-knowledge-tool recommend "URL" [--type TYPE] [--limit N] [--offset M] [--json] +``` + +## Arguments + +- `URL`: AWS documentation URL (required) +- `--type TYPE` / `-t TYPE`: Filter by type + - `highly_rated`: Popular pages within same service + - `new`: Recently added pages (find new features) + - `similar`: Pages covering similar topics + - `journey`: Pages commonly viewed next +- `--limit N` / `-l N`: Max results per category (default: 5) +- `--offset M` / `-o M`: Skip first M per category (default: 0) +- `--json`: Output JSON format +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +## Examples + +```bash +# Get all recommendations +aws-knowledge-tool recommend "https://docs.aws.amazon.com/lambda/latest/dg/welcome.html" + +# Filter by type to find new features +aws-knowledge-tool recommend "https://docs.aws.amazon.com/..." --type new + +# JSON output for processing +aws-knowledge-tool recommend "https://docs.aws.amazon.com/..." --json --limit 3 +``` + +## Output + +Returns dict with recommendation categories and their pages (title, url, context). diff --git a/commands/search.md b/commands/search.md new file mode 100644 index 0000000..97ef2ba --- /dev/null +++ b/commands/search.md @@ -0,0 +1,41 @@ +--- +description: Search AWS documentation with full-text search +argument-hint: query +--- + +Search AWS documentation for QUERY and return results with pagination. + +## Usage + +```bash +aws-knowledge-tool search "QUERY" [--limit N] [--offset M] [--json] +``` + +## Arguments + +- `QUERY`: Search query (required) +- `--limit N` / `-l N`: Max results (default: 10) +- `--offset M` / `-o M`: Skip first M results (default: 0) +- `--json`: Output JSON format +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +## Examples + +```bash +# Basic search +aws-knowledge-tool search "Lambda function URLs" + +# With limit and JSON output +aws-knowledge-tool search "S3 versioning" --limit 5 --json + +# Paginated search +aws-knowledge-tool search "DynamoDB" --limit 10 --offset 20 +``` + +## Output + +Returns list of search results with: +- `title`: Page title +- `url`: Documentation URL +- `context`: Summary snippet +- `rank_order`: Relevance ranking diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..879d136 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,57 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:dnvriend/aws-knowledge-tool:plugins/aws-knowledge-tool", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "fcbe8b69e5d47e0d3fe0161b9a33ae064d2d9c3c", + "treeHash": "2a361eef9478330dd19a86a35d7513a002d7a26bcfe8a48c7bb1f585fa907f5c", + "generatedAt": "2025-11-28T10:16:34.297759Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "aws-knowledge-tool", + "description": "CLI tool for querying AWS Knowledge MCP Server - search, read, and discover AWS documentation", + "version": "0.1.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "b91490cde708b753671338b6b710e62af00581a3f299de4de70877a5f177f665" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "5ecfd45bea821f3236f76432c098f71165c528e5c29ebc0d56189832c700e571" + }, + { + "path": "commands/search.md", + "sha256": "fb27f3c0caad2e3969c8372ece2678a91a074cf477240dd547669431e0ecbaab" + }, + { + "path": "commands/recommend.md", + "sha256": "690e485641ee90bcf1b04509d0b9a03aa3c805618384828e57a631f582efa0df" + }, + { + "path": "commands/read.md", + "sha256": "ac7d96dbf4323008579eab0f364a98de882c305ae39cb146b0c0a90129577d68" + }, + { + "path": "skills/aws-knowledge-tool/SKILL.md", + "sha256": "4e855e59fea6b69fbd581e87f24522358c9b1b557d37e178b3596b8c42fb475e" + } + ], + "dirSha256": "2a361eef9478330dd19a86a35d7513a002d7a26bcfe8a48c7bb1f585fa907f5c" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/aws-knowledge-tool/SKILL.md b/skills/aws-knowledge-tool/SKILL.md new file mode 100644 index 0000000..acf0839 --- /dev/null +++ b/skills/aws-knowledge-tool/SKILL.md @@ -0,0 +1,336 @@ +--- +name: skill-aws-knowledge-tool +description: CLI tool for querying AWS Knowledge MCP Server +--- + +# When to use +- When you need to search AWS documentation programmatically +- When you need to read and convert AWS docs to markdown +- When you need to discover related AWS documentation + +# AWS Knowledge Tool Skill + +## Purpose + +This skill provides access to the `aws-knowledge-tool` CLI - a command-line interface for querying the AWS Knowledge MCP Server. Use it to search, read, and discover AWS documentation programmatically. + +## When to Use This Skill + +**Use this skill when:** +- You need to search AWS documentation with full-text search +- You need to read AWS documentation pages as markdown +- You need to discover related documentation recommendations +- You need structured/JSON output for processing + +**Do NOT use this skill for:** +- Writing new AWS documentation (read-only) +- Deploying AWS resources (documentation only) +- AWS CLI operations (use AWS CLI instead) + +## CLI Tool: aws-knowledge-tool + +The `aws-knowledge-tool` is a CLI tool for querying the AWS Knowledge MCP Server to search, read, and discover AWS documentation. + +### Installation + +```bash +# Clone and install +git clone https://github.com/dnvriend/aws-knowledge-tool.git +cd aws-knowledge-tool +uv tool install . +``` + +### Prerequisites + +- Python 3.14+ +- [uv](https://github.com/astral-sh/uv) package manager + +### Quick Start + +```bash +# Search AWS documentation +aws-knowledge-tool search "Lambda function URLs" + +# Read documentation page +aws-knowledge-tool read "https://docs.aws.amazon.com/lambda/latest/dg/welcome.html" + +# Get recommendations +aws-knowledge-tool recommend "https://docs.aws.amazon.com/lambda/latest/dg/welcome.html" +``` + +## Progressive Disclosure + +
+📖 Core Commands (Click to expand) + +### search - Search AWS Documentation + +Search across AWS documentation, blogs, solutions library, architecture center, and prescriptive guidance. + +**Usage:** +```bash +aws-knowledge-tool search QUERY [OPTIONS] +``` + +**Arguments:** +- `QUERY`: Search query text (required) +- `--limit N` / `-l N`: Maximum results (default: 10) +- `--offset M` / `-o M`: Skip first M results for pagination (default: 0) +- `--json`: Output JSON format for processing +- `--stdin`: Read query from stdin (for pipelines) +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +**Examples:** +```bash +# Basic search +aws-knowledge-tool search "S3 versioning" + +# With pagination +aws-knowledge-tool search "Lambda" --limit 10 --offset 20 + +# JSON output +aws-knowledge-tool search "DynamoDB" --json + +# Pipeline usage +echo "CloudFormation" | aws-knowledge-tool search --stdin --json +``` + +**Output:** +Returns list of results with: `title`, `url`, `context`, `rank_order` + +--- + +### read - Read AWS Documentation + +Fetch and convert AWS documentation pages to markdown format. + +**Usage:** +```bash +aws-knowledge-tool read URL [OPTIONS] +``` + +**Arguments:** +- `URL`: AWS documentation URL (required) +- `--start-index N` / `-s N`: Starting character index for pagination +- `--max-length M` / `-m M`: Maximum characters to fetch +- `--json`: Output JSON format +- `--stdin`: Read URL from stdin +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +**Examples:** +```bash +# Read full document +aws-knowledge-tool read "https://docs.aws.amazon.com/lambda/latest/dg/welcome.html" + +# With pagination (large docs) +aws-knowledge-tool read "https://docs.aws.amazon.com/..." \ + --start-index 5000 --max-length 2000 + +# Pipeline from search +aws-knowledge-tool search "Lambda" --json | \ + jq -r '.[0].url' | \ + aws-knowledge-tool read --stdin +``` + +**Output:** +Returns markdown-formatted documentation content. + +**Supported domains:** +- `docs.aws.amazon.com` +- `aws.amazon.com` + +--- + +### recommend - Get Documentation Recommendations + +Discover related documentation through four recommendation types. + +**Usage:** +```bash +aws-knowledge-tool recommend URL [OPTIONS] +``` + +**Arguments:** +- `URL`: AWS documentation URL (required) +- `--type TYPE` / `-t TYPE`: Filter by recommendation type + - `highly_rated`: Popular pages within same AWS service + - `new`: Recently added pages (useful for finding new features) + - `similar`: Pages covering similar topics + - `journey`: Pages commonly viewed next by other users +- `--limit N` / `-l N`: Max results per category (default: 5) +- `--offset M` / `-o M`: Skip first M per category (default: 0) +- `--json`: Output JSON format +- `--stdin`: Read URL from stdin +- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE) + +**Examples:** +```bash +# Get all recommendations +aws-knowledge-tool recommend "https://docs.aws.amazon.com/lambda/latest/dg/welcome.html" + +# Filter by type (find new features) +aws-knowledge-tool recommend "https://docs.aws.amazon.com/..." --type new + +# JSON output with limit +aws-knowledge-tool recommend "https://docs.aws.amazon.com/..." --json --limit 3 + +# Pipeline usage +aws-knowledge-tool search "Lambda" --json | \ + jq -r '.[0].url' | \ + aws-knowledge-tool recommend --stdin --type similar +``` + +**Output:** +Returns dict with recommendation categories and their pages (title, url, context). + +
+ +
+⚙️ Advanced Features (Click to expand) + +### Multi-Level Verbosity Logging + +Control logging detail with progressive verbosity levels. All logs output to stderr. + +**Logging Levels:** + +| Flag | Level | Output | Use Case | +|------|-------|--------|----------| +| (none) | WARNING | Errors and warnings only | Production, quiet mode | +| `-v` | INFO | + High-level operations | Normal debugging | +| `-vv` | DEBUG | + Detailed info, full tracebacks | Development, troubleshooting | +| `-vvv` | TRACE | + Library internals | Deep debugging | + +**Examples:** +```bash +# INFO level - see operations +aws-knowledge-tool search "Lambda" -v + +# DEBUG level - see detailed info +aws-knowledge-tool search "Lambda" -vv + +# TRACE level - see all internals +aws-knowledge-tool search "Lambda" -vvv +``` + +--- + +### Shell Completion + +Native shell completion for bash, zsh, and fish. + +**Installation:** +```bash +# Bash (add to ~/.bashrc) +eval "$(aws-knowledge-tool completion bash)" + +# Zsh (add to ~/.zshrc) +eval "$(aws-knowledge-tool completion zsh)" + +# Fish (save to completions) +aws-knowledge-tool completion fish > ~/.config/fish/completions/aws-knowledge-tool.fish +``` + +--- + +### Pipeline Composition + +Compose commands with Unix pipes for powerful workflows. + +**Examples:** +```bash +# Search → Extract URL → Read +aws-knowledge-tool search "Lambda" --json | \ + jq -r '.[0].url' | \ + aws-knowledge-tool read --stdin + +# Search → Extract URL → Get similar docs +aws-knowledge-tool search "S3" --json | \ + jq -r '.[0].url' | \ + aws-knowledge-tool recommend --stdin --type similar + +# Save search results to file +aws-knowledge-tool search "DynamoDB" --json > results.json + +# Read and save as markdown +aws-knowledge-tool read "https://docs.aws.amazon.com/..." > lambda-docs.md +``` + +
+ +
+🔧 Troubleshooting (Click to expand) + +### Common Issues + +**Issue: Command not found** +```bash +# Verify installation +aws-knowledge-tool --version + +# Reinstall if needed +cd aws-knowledge-tool +uv tool install . --reinstall +``` + +**Issue: No results from search** +- Check your search query is specific enough +- Try broader search terms +- Use `--json` to see full response + +**Issue: URL validation error** +- Ensure URL is from `docs.aws.amazon.com` or `aws.amazon.com` +- Check URL is accessible in browser first + +**Issue: Connection timeout** +- Check internet connection +- AWS Knowledge MCP Server may be temporarily unavailable +- Try again with verbose flag: `-vv` + +### Getting Help + +```bash +# Show help +aws-knowledge-tool --help + +# Command-specific help +aws-knowledge-tool search --help +aws-knowledge-tool read --help +aws-knowledge-tool recommend --help +``` + +
+ +## Exit Codes + +- `0`: Success +- `1`: Client error (invalid arguments, validation failed) +- `2`: Server error (API error, network issue) +- `3`: Network error (connection failed, timeout) + +## Output Formats + +**Default (Markdown):** +- Human-readable formatted output +- Search: ranked list with titles, URLs, context +- Read: markdown content +- Recommend: grouped by category with titles, URLs + +**JSON (`--json` flag):** +- Machine-readable structured data +- Perfect for pipelines and processing +- Consistent structure across commands + +## Best Practices + +1. **Use JSON for pipelines**: Enable `--json` when piping to other tools +2. **Pagination for large results**: Use `--limit` and `--offset` for controlled fetching +3. **Progressive verbosity**: Start with `-v`, increase to `-vv`/`-vvv` only if needed +4. **Save frequent searches**: Cache JSON results to avoid repeated API calls +5. **Compose commands**: Leverage Unix pipes for powerful workflows + +## Resources + +- **GitHub**: https://github.com/dnvriend/aws-knowledge-tool +- **AWS Knowledge MCP Server**: https://knowledge-mcp.global.api.aws +- **MCP Specification**: https://modelcontextprotocol.io