diff --git a/astro.config.mjs b/astro.config.mjs index 6a47186..3f7b3b2 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -57,6 +57,7 @@ export default defineConfig({ label: 'How-To Guides', badge: { text: 'Solve', variant: 'note' }, items: [ + { label: 'Connect to Hosted Server', slug: 'how-to/hosted-mcp', badge: { text: 'New', variant: 'success' } }, { label: 'Extract Tables from Word', slug: 'how-to/extract-tables' }, { label: 'Analyze Excel Data', slug: 'how-to/analyze-excel' }, { label: 'Convert to Markdown', slug: 'how-to/convert-markdown' }, diff --git a/src/assets/red-swingline.svg b/src/assets/red-swingline.svg new file mode 100644 index 0000000..9a5d17c --- /dev/null +++ b/src/assets/red-swingline.svg @@ -0,0 +1,38 @@ + + + + + + + + + + + + + + + + + + + SWINGLINE + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/assets/swingline-hero.png b/src/assets/swingline-hero.png new file mode 100644 index 0000000..375b905 Binary files /dev/null and b/src/assets/swingline-hero.png differ diff --git a/src/content/docs/how-to/hosted-mcp.mdx b/src/content/docs/how-to/hosted-mcp.mdx new file mode 100644 index 0000000..3c16aa3 --- /dev/null +++ b/src/content/docs/how-to/hosted-mcp.mdx @@ -0,0 +1,178 @@ +--- +title: Connect to Hosted Server +description: Use mcwaddams without installing anything locally. +--- + +import { Aside, Code, Tabs, TabItem, Card, CardGrid } from '@astrojs/starlight/components'; + +# Connect to Hosted Server + +> *"I was told there would be no installation..."* + +Don't want to install anything? Connect to our hosted mcwaddams server via HTTP. + +## Quick Connect + + + + ```bash + claude mcp add mcwaddams-hosted --transport http "https://mcwaddams.supported.systems/mcp" + ``` + + + ```json + { + "mcpServers": { + "mcwaddams": { + "transport": { + "type": "streamable-http", + "url": "https://mcwaddams.supported.systems/mcp" + } + } + } + } + ``` + + + ```python + from mcp import ClientSession + from mcp.client.streamable_http import streamable_http_client + + async with streamable_http_client("https://mcwaddams.supported.systems/mcp") as (read, write): + async with ClientSession(read, write) as session: + await session.initialize() + tools = await session.list_tools() + print(f"Connected! {len(tools.tools)} tools available") + ``` + + + + + +## What's Available + +All 20+ mcwaddams tools are available via the hosted server: + + + + Extract text, images, metadata from Word, Excel, PowerPoint + + + Process `.doc`, `.xls`, `.ppt` files from the 90s + + + Index documents and fetch chapters/sheets on demand + + + Multiple extraction methods with automatic fallback + + + +## Hosted vs Local + +| Feature | Hosted | Local (uvx) | +|---------|--------|-------------| +| Installation | None | `uvx mcwaddams` | +| File Access | URL only | Local + URL | +| Speed | Network latency | Instant | +| Privacy | Files processed on server | Files stay local | +| Availability | Requires internet | Works offline | + + + +## Using with URLs + +The hosted server can process documents from URLs directly: + +```python +# Extract text from a public document +result = await session.call_tool("extract_text", { + "file_path": "https://example.com/report.docx" +}) +``` + +This is particularly useful for processing documents already hosted online. + +## Self-Hosting + +Want the convenience of HTTP without using our server? Self-host your own: + +### Docker Compose + +```yaml +services: + mcwaddams: + image: ghcr.io/ryanmalloy/mcwaddams:latest + environment: + - MCP_TRANSPORT=streamable-http + - MCP_HOST=0.0.0.0 + - MCP_PORT=8000 + ports: + - "8000:8000" +``` + +### With Caddy Reverse Proxy + +Clone the repo and use our docker-compose with caddy-docker-proxy labels: + +```bash +git clone https://github.com/ryanmalloy/mcwaddams.git +cd mcwaddams +cp .env.example .env +# Edit .env to set your hostname +make docker-up +``` + +Your server will be available at `https://your-domain.com/mcp` + +### Local Development + +Run HTTP mode locally without Docker: + +```bash +# Install +pip install mcwaddams + +# Run with HTTP transport +MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 python -m mcwaddams.server +``` + +Or with uv: + +```bash +MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uvx mcwaddams +``` + +## Troubleshooting + +### Connection Refused + +``` +Error: Connection refused +``` + +The server may be temporarily down. Try: +1. Check server status at https://status.supported.systems +2. Fall back to local installation: `uvx mcwaddams` + +### Timeout Errors + +Large documents may take longer to process. The hosted server has a 60-second timeout per request. + +For very large documents, consider: +- Using local installation +- Processing documents in chunks via pagination + +### SSL/TLS Errors + +Ensure you're using `https://` not `http://`. The hosted server requires TLS. + +--- + +
+*"So if you could just go ahead and connect... that would be great."* +
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 1f5b20c..d5f2f7b 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -5,7 +5,8 @@ template: splash hero: tagline: "I was told there would be document extraction." image: - file: ../../assets/stapler.svg + file: ../../assets/swingline-hero.png + alt: "Milton's Red Swingline Stapler" actions: - text: Get Started link: /installation/