MCP (Model Context Protocol) server for RAGStack knowledge bases. Enables AI assistants to search, chat, upload documents/media, and scrape your knowledge base. Get your GraphQL endpoint and API key from the RAGStack dashboard: Settings → API Key Edit ~/Library/Application Support/Claude/claudedesktopconfig.json (Mac) or %APPDATA%\Claude\claudedesktopconfig.json (Windows): Edit ~/.aws/amazonq/mcp.
Add this skill
npx mdskills install HatmanStack/ragstack-lambdaComprehensive MCP server with extensive RAG capabilities, clear tool descriptions, and excellent setup docs
1# RAGStack MCP Server23<!-- mcp-name: io.github.HatmanStack/ragstack -->45MCP (Model Context Protocol) server for RAGStack knowledge bases. Enables AI assistants to search, chat, upload documents/media, and scrape your knowledge base.67## Installation89```bash10# Using uvx (recommended - no install needed)11uvx ragstack-mcp1213# Or install globally14pip install ragstack-mcp15```1617## Configuration1819Get your GraphQL endpoint and API key from the RAGStack dashboard:20**Settings → API Key**2122### Claude Desktop2324Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):2526```json27{28 "mcpServers": {29 "ragstack-kb": {30 "command": "uvx",31 "args": ["ragstack-mcp"],32 "env": {33 "RAGSTACK_GRAPHQL_ENDPOINT": "https://xxx.appsync-api.us-east-1.amazonaws.com/graphql",34 "RAGSTACK_API_KEY": "da2-xxxxxxxxxxxx"35 }36 }37 }38}39```4041### Amazon Q CLI4243Edit `~/.aws/amazonq/mcp.json`:4445```json46{47 "mcpServers": {48 "ragstack-kb": {49 "command": "uvx",50 "args": ["ragstack-mcp"],51 "env": {52 "RAGSTACK_GRAPHQL_ENDPOINT": "https://xxx.appsync-api.us-east-1.amazonaws.com/graphql",53 "RAGSTACK_API_KEY": "da2-xxxxxxxxxxxx"54 }55 }56 }57}58```5960### Cursor6162Open **Settings → MCP Servers → Add Server**, or edit `.cursor/mcp.json`:6364```json65{66 "ragstack-kb": {67 "command": "uvx",68 "args": ["ragstack-mcp"],69 "env": {70 "RAGSTACK_GRAPHQL_ENDPOINT": "https://xxx.appsync-api.us-east-1.amazonaws.com/graphql",71 "RAGSTACK_API_KEY": "da2-xxxxxxxxxxxx"72 }73 }74}75```7677### VS Code + Cline7879Edit `.vscode/cline_mcp_settings.json`:8081```json82{83 "mcpServers": {84 "ragstack-kb": {85 "command": "uvx",86 "args": ["ragstack-mcp"],87 "env": {88 "RAGSTACK_GRAPHQL_ENDPOINT": "https://xxx.appsync-api.us-east-1.amazonaws.com/graphql",89 "RAGSTACK_API_KEY": "da2-xxxxxxxxxxxx"90 }91 }92 }93}94```9596### VS Code + Continue9798Edit `~/.continue/config.json`, add to `mcpServers` array:99100```json101{102 "mcpServers": [103 {104 "name": "ragstack-kb",105 "command": "uvx",106 "args": ["ragstack-mcp"],107 "env": {108 "RAGSTACK_GRAPHQL_ENDPOINT": "https://xxx.appsync-api.us-east-1.amazonaws.com/graphql",109 "RAGSTACK_API_KEY": "da2-xxxxxxxxxxxx"110 }111 }112 ]113}114```115116## Available Tools117118### search_knowledge_base119120Search for relevant documents in the knowledge base.121122| Parameter | Type | Required | Default | Description |123|-----------|------|----------|---------|-------------|124| `query` | string | Yes | - | The search query |125| `max_results` | int | No | 5 | Maximum results to return |126127### chat_with_knowledge_base128129Ask questions and get AI-generated answers with source citations.130131| Parameter | Type | Required | Default | Description |132|-----------|------|----------|---------|-------------|133| `query` | string | Yes | - | Your question |134| `conversation_id` | string | No | null | ID to maintain conversation context |135136### start_scrape_job137138Scrape a website into the knowledge base.139140| Parameter | Type | Required | Default | Description |141|-----------|------|----------|---------|-------------|142| `url` | string | Yes | - | Starting URL to scrape |143| `max_pages` | int | No | 50 | Maximum pages to scrape |144| `max_depth` | int | No | 3 | How deep to follow links (0 = start page only) |145| `scope` | string | No | "HOSTNAME" | `SUBPAGES`, `HOSTNAME`, or `DOMAIN` |146| `include_patterns` | list[str] | No | null | Only scrape URLs matching these glob patterns |147| `exclude_patterns` | list[str] | No | null | Skip URLs matching these glob patterns |148| `scrape_mode` | string | No | "AUTO" | `AUTO`, `FAST` (HTTP only), or `FULL` (browser) |149| `cookies` | string | No | null | Cookie string for authenticated sites |150| `force_rescrape` | bool | No | false | Re-scrape even if content unchanged |151152**Scope values:**153- `SUBPAGES` - Only URLs under the starting path154- `HOSTNAME` - All pages on the same subdomain155- `DOMAIN` - All subdomains of the domain156157**Scrape mode values:**158- `AUTO` - Try fast mode, fall back to full for SPAs159- `FAST` - HTTP only, faster but may miss JavaScript content160- `FULL` - Uses headless browser, handles all JavaScript161162### get_scrape_job_status163164Check the status of a scrape job.165166| Parameter | Type | Required | Description |167|-----------|------|----------|-------------|168| `job_id` | string | Yes | The scrape job ID |169170### list_scrape_jobs171172List recent scrape jobs.173174| Parameter | Type | Required | Default | Description |175|-----------|------|----------|---------|-------------|176| `limit` | int | No | 10 | Maximum jobs to return |177178### upload_document_url179180Get a presigned URL to upload a document or media file.181182| Parameter | Type | Required | Description |183|-----------|------|----------|-------------|184| `filename` | string | Yes | Name of the file (e.g., 'report.pdf', 'meeting.mp4') |185186**Supported formats:**187- Documents: PDF, DOCX, XLSX, HTML, TXT, CSV, JSON, XML, EML, EPUB, Markdown188- Images: JPG, PNG, GIF, WebP, AVIF, BMP, TIFF189- Video: MP4, WebM190- Audio: MP3, WAV, M4A, OGG, FLAC191192Video/audio files are transcribed using AWS Transcribe and segmented for search.193194### upload_image_url195196Get a presigned URL to upload an image (step 1 of image upload workflow).197198| Parameter | Type | Required | Description |199|-----------|------|----------|-------------|200| `filename` | string | Yes | Name of the image file (e.g., 'photo.jpg') |201202Supported formats: JPEG, PNG, GIF, WebP, AVIF, BMP, TIFF203204### generate_image_caption205206Generate an AI caption for an uploaded image using a vision model (step 2, optional).207208| Parameter | Type | Required | Description |209|-----------|------|----------|-------------|210| `s3_uri` | string | Yes | S3 URI returned by upload_image_url |211212### submit_image213214Finalize an image upload and trigger indexing (step 3).215216| Parameter | Type | Required | Default | Description |217|-----------|------|----------|---------|-------------|218| `image_id` | string | Yes | - | Image ID from upload_image_url |219| `caption` | string | No | null | Primary caption |220| `user_caption` | string | No | null | User-provided caption |221| `ai_caption` | string | No | null | AI-generated caption |222223---224225## Configuration Tools (Read-Only)226227### get_configuration228229Get all current RAGStack configuration settings organized by category.230231Returns settings for:232- **Chat:** Models, quotas, system prompt, document access233- **Metadata Extraction:** Enabled, model, mode (auto/manual), max keys234- **Query-Time Filtering:** Filter generation, multi-slice retrieval settings235- **Public Access:** Which endpoints allow unauthenticated access236- **Document Processing:** OCR backend, image caption prompt237- **Media Processing:** Transcribe language, speaker diarization, segment duration238- **Budget:** Alert thresholds239240**Note:** Read-only. To modify settings, use the admin dashboard (Cognito auth required).241242---243244## Metadata Analysis Tools245246These tools help understand and optimize metadata extraction and filtering.247248### get_metadata_stats249250Get statistics about metadata keys extracted from documents.251252Returns key names, data types, occurrence counts, sample values, and status.253254### get_filter_examples255256Get AI-generated filter examples for metadata-based search queries.257258Returns filter patterns with name, description, use case, and JSON filter syntax.259260**Filter syntax reference:**261- Basic operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$exists`262- Logical operators: `$and`, `$or`263- Example: `{"topic": {"$eq": "genealogy"}}`264265### get_key_library266267Get the complete metadata key library with all discovered keys.268269Returns all keys available for filtering with data types and sample values.270271### check_key_similarity272273Check if a proposed metadata key is similar to existing keys.274275| Parameter | Type | Required | Default | Description |276|-----------|------|----------|---------|-------------|277| `key_name` | string | Yes | - | Proposed key name to check |278| `threshold` | float | No | 0.8 | Similarity threshold (0.0-1.0) |279280Use this before adding documents with new keys to avoid duplicates.281282### analyze_metadata283284Trigger metadata analysis to discover keys and generate filter examples.285286**Note:** This is a long-running operation (1-2 minutes). It samples up to 1000 vectors and uses LLM analysis.287288Run this after ingesting new documents or when filter generation isn't working as expected.289290---291292## Usage Examples293294Once configured, just ask your AI assistant naturally:295296**Search & Chat:**297- "Search my knowledge base for authentication best practices"298- "What does our documentation say about API rate limits?"299- "What was discussed in the team meeting about deadlines?" (searches video/audio transcripts)300301**Web Scraping:**302- "Scrape the React docs at react.dev/reference"303- "Check the status of my scrape job"304305**Document, Image & Media Upload:**306- "Upload a new document called quarterly-report.pdf"307- "Upload this image and generate a caption for it"308- "Upload the meeting recording meeting-2024-01.mp4"309310**Metadata Analysis:**311- "What metadata keys are available for filtering?"312- "Analyze the metadata in my knowledge base"313- "Show me the filter examples"314- "Check if 'author' is similar to any existing keys"315316**Configuration:**317- "What are my current RAGStack settings?"318- "What model is being used for chat?"319- "Is multi-slice retrieval enabled?"320- "What are my quota limits?"321- "What language is configured for transcription?"322323## Environment Variables324325| Variable | Required | Description |326|----------|----------|-------------|327| `RAGSTACK_GRAPHQL_ENDPOINT` | Yes | Your RAGStack GraphQL API URL |328| `RAGSTACK_API_KEY` | Yes | Your RAGStack API key |329330## Development331332```bash333# Clone and install334cd src/ragstack-mcp335uv sync336337# Run locally338uv run ragstack-mcp339340# Build package341uv build342343# Publish to PyPI344uv publish345```346347## License348349MIT350
Full transparency — inspect the skill content before installing.