chore: create /docs dir with a Deco mcp + astro project (#867)

* init docs from mcp template

* config on CI

* ignore docs server lint

* ignore docs on check to skip typegen big file

* remove .vscode

Author: viktormarinho

.github/workflows/deploy-docs.yaml

@@ -0,0 +1,27 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Deploy
+        run: bun run docs:deploy
+        env:
+          DECO_DEPLOY_TOKEN: ${{ secrets.DECO_DEPLOY_TOKEN }}

docs/.cursor/rules/main.mdc

@@ -0,0 +1,260 @@
+---
+alwaysApply: true
+---
+# Astro MCP Template Development Guide
+
+## Project Overview
+
+This is a **Deco MCP (Model Context Protocol) server** template with an **Astro documentation site**. It provides a full-stack development environment where:
+- The `/server` folder contains the MCP server (Cloudflare Workers + Deco runtime)
+- The `/view` folder contains the Astro documentation site (Starlight theme)
+- The server serves both MCP endpoints AND the built documentation assets
+
+## Project Structure
+
+```
+astro-docs-view/
+├── package.json          # Root workspace with dev/gen/deploy scripts
+├── server/               # MCP Server (Cloudflare Workers + Deco)
+│   ├── main.ts          # Main server entry point
+│   ├── deco.gen.ts      # Generated types for integrations
+│   ├── wrangler.toml    # Cloudflare Workers config
+│   └── package.json     # Server dependencies
+└── view/                # Astro Documentation Site (Starlight theme + Tailwind CSS)
+    ├── src/
+    │   ├── content/docs/  # Documentation content (MDX/Markdown)
+    │   ├── assets/        # Static assets
+    │   ├── styles/        # Tailwind CSS styles and theming
+    │   └── content.config.ts  # Content configuration
+    ├── astro.config.mjs   # Astro configuration with Starlight
+    └── package.json       # Frontend dependencies
+```
+
+## Development Workflow
+
+### Root Commands (npm workspace)
+- `npm run dev` - **Primary development command**
+  - Starts Astro dev server in watch mode
+  - Starts MCP server on port 8787
+  - Server serves both API endpoints + documentation assets
+  - Hot reload for both frontend and backend
+  
+- `npm run gen` - **Type generation**
+  - Generates TypeScript types for deco integrations
+  - Creates `server/deco.gen.ts` with typed RPC interfaces
+  - Run this after adding new integrations in deco.chat
+
+- `npm run gen:self` - **Self-type generation for your own tools**
+  - Generates TypeScript types for your own server's tools and workflows
+  - Requires the server to be running (`npm run dev`)
+  - Copy the development URL from server logs (e.g., "https://localhost-48d64e92.deco.host")
+  - Add /mcp to the path. So, for the URL https://localhost-48d64e92.deco.host you should set DECO_SELF_URL as https://localhost-48d64e92.deco.host/mcp.
+  - Run: `DECO_SELF_URL=<your-dev-url> npm run gen:self`
+  - Creates typed RPC interfaces for your own tools/workflows
+  - Run this after adding new tools or workflows to your server
+
+- `npm run deploy` - **Production deployment**
+  - Builds Astro site for production
+  - Deploys to Cloudflare Workers
+  - Makes app available at public URL
+
+### Server Architecture (`/server`)
+
+**Key Files:**
+- `main.ts` - Main server with tools, workflows, and asset serving
+- `deco.gen.ts` - Generated types for integrations (auto-generated)
+- `wrangler.toml` - Cloudflare Workers config with asset binding
+
+**Server Pattern:**
+```typescript
+// server/main.ts structure
+import { withRuntime } from "@deco/workers-runtime";
+
+// 1. Define tools (functions the MCP can call)
+const createMyTool = (env: Env) => createTool({
+  id: "MY_TOOL",
+  description: "Tool description",
+  inputSchema: z.object({ /* input schema */ }),
+  outputSchema: z.object({ /* output schema */ }),
+  execute: async ({ context }) => {
+    // Tool logic here
+    return { /* result */ };
+  },
+});
+
+// 2. Define workflows (multi-step processes)
+const createMyWorkflow = (env: Env) => {
+  const step = createStepFromTool(createMyTool(env));
+  return createWorkflow({
+    id: "MY_WORKFLOW",
+    inputSchema: z.object({ /* input */ }),
+    outputSchema: z.object({ /* output */ }),
+  }).then(step).commit();
+};
+
+// 3. Setup runtime with fallback to serve documentation
+const { Workflow, ...runtime } = withRuntime<Env>({
+  workflows: [createMyWorkflow],
+  tools: [createMyTool],
+  fetch: fallbackToView("/"), // Serves documentation assets
+});
+
+export { Workflow };
+export default runtime;
+```
+
+### Astro Documentation Architecture (`/view`)
+
+**Key Files:**
+- `astro.config.mjs` - Astro configuration with Starlight theme
+- `src/content/docs/` - Documentation content in MDX/Markdown
+- `src/assets/` - Static assets (images, etc.)
+- `src/styles/global.css` - Tailwind CSS configuration and theming
+- `src/content.config.ts` - Content configuration
+
+**Starlight Configuration:**
+```javascript
+// view/astro.config.mjs
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      title: 'My Documentation',
+      social: [
+        { icon: 'github', label: 'GitHub', href: 'https://github.com/your-repo' }
+      ],
+      sidebar: [
+        {
+          label: 'Guides',
+          items: [
+            { label: 'Getting Started', slug: 'guides/getting-started' },
+          ],
+        },
+        {
+          label: 'Reference',
+          autogenerate: { directory: 'reference' },
+        },
+      ],
+    }),
+  ],
+});
+```
+
+**Content Structure:**
+```mdx
+// view/src/content/docs/guides/getting-started.md
+---
+title: Getting Started
+description: Learn how to get started with our platform
+---
+
+# Getting Started
+
+Welcome to our documentation! This guide will help you get started.
+
+## Prerequisites
+
+- Node.js >=18.0.0
+- Basic knowledge of TypeScript
+
+## Installation
+
+```bash
+npm install my-package
+```
+```
+
+## Development Best Practices
+
+### When Adding New Tools:
+1. Add tool definition in `server/main.ts`
+2. Include in `withRuntime` tools array
+3. Run `npm run gen` to update external integration types
+4. Start server with `npm run dev` and copy the development URL from logs
+5. Run `DECO_SELF_URL=<your-dev-url> npm run gen:self` to generate self-types
+
+### When Adding New Workflows:
+1. Create workflow in `server/main.ts`
+2. Include in `withRuntime` workflows array
+3. Run `npm run gen` to update external integration types
+4. Start server with `npm run dev` and copy the development URL from logs
+5. Run `DECO_SELF_URL=<your-dev-url> npm run gen:self` to generate self-types
+
+### When Adding New Documentation:
+1. Create MDX files in `view/src/content/docs/`
+2. Use frontmatter for metadata (title, description, etc.)
+3. Update sidebar configuration in `astro.config.mjs`
+4. Use Starlight components for enhanced documentation features
+
+### When Customizing the Theme:
+1. Edit `view/astro.config.mjs` for basic configuration
+2. Edit `view/src/styles/global.css` for Tailwind CSS theming (fonts, colors, etc.)
+3. Use Starlight's built-in components for consistent design
+4. Leverage Astro's component system for custom functionality
+5. Use Tailwind CSS classes directly in MDX content
+6. Use Starlight's CSS custom properties for theming
+
+## Environment Setup
+
+### Prerequisites:
+- Node.js >=18.0.0
+- npm >=8.0.0
+- Deno >=2.0.0
+- Deco CLI installed: `deno install -Ar -g -n deco jsr:@deco/cli`
+
+### Initial Setup:
+1. `deco login` - Authenticate with deco.chat
+2. `npm install` - Install all dependencies
+3. `npm run configure` - Configure the app with the desired name and select its workspace
+4. `npm run dev` - Start development
+
+## Integration with Deco Platform
+
+### Adding External Integrations:
+1. Go to deco.chat dashboard
+2. Add integrations (APIs, databases, etc.)
+3. Run `npm run gen` to get typed interfaces
+4. Use typed clients in your tools/workflows
+
+### Deployment:
+- `npm run deploy` deploys to Cloudflare Workers
+- App becomes available at public URL
+- Can be used as MCP server by AI agents
+
+## Common Patterns
+
+### Error Handling:
+```typescript
+// In tools
+execute: async ({ context }) => {
+  const result = await someAsyncOperation(context);
+  if (!result.ok) {
+    throw new Error("...")
+  }
+  return result;
+}
+```
+
+### Documentation Best Practices:
+- Use clear, descriptive titles and descriptions
+- Structure content with proper headings (H1, H2, H3)
+- Include code examples with syntax highlighting
+- Use Starlight components for enhanced features
+- Apply Tailwind CSS classes for custom styling in MDX content
+- Keep documentation up-to-date with code changes
+
+### Content Organization:
+- Group related content in directories
+- Use consistent naming conventions
+- Leverage Starlight's auto-generated sidebar
+- Include search-friendly keywords in frontmatter
+
+## Debugging Tips
+
+- Server logs appear in terminal during `npm run dev`
+- Astro dev server runs on port 4000 by default
+- Use browser dev tools for frontend debugging
+- Check Astro and Starlight documentation for troubleshooting
+
+This template provides a complete full-stack development environment for building MCP servers with beautiful documentation sites. Focus on adding your business logic in tools and workflows while leveraging Astro, Starlight, and Tailwind CSS for professional documentation.

docs/.gitignore

@@ -0,0 +1,21 @@
+
+# Environment files
+.env
+.dev.vars
+
+# Build files
+view-build/
+
+# Node modules
+node_modules
+
+node_modules/
+
+.DS_Store
+dist
+dist-ssr
+*.local
+count.txt
+.env
+.nitro
+.tanstack

docs/.npmrc

@@ -0,0 +1 @@
+@jsr:registry=https://npm.jsr.io