@every-app/mcp 0.0.1 → 0.0.3

package/README.md

@@ -1,10 +1,9 @@
-# @every-app/mcp
-
-MCP (Model Context Protocol) server for Every App coding agents. This server provides AI coding assistants with tools to explore example apps, search code patterns, and access documentation.
+# Every App MCP
+This server gives your coding agent access to example apps and Every App documentation which can be used for reference when building out your application. 
 
 ## Quick Start
 
-Just add the MCP server to your AI tool's configuration. The examples will be automatically downloaded on first run.
+This MCP server is compatible with any coding agent tool. Below are some example configs:
 
 ### Claude Code
 
@@ -44,41 +43,16 @@ Add to `opencode.json`:
 }
 ```
 
-That's it! The server will automatically clone the Every App examples to `~/.every-app-mcp/examples` on first run.
-
 ## Available Tools
 
 | Tool | Description |
 |------|-------------|
-| `every_app_mcp_list_examples` | List all available example apps with descriptions |
-| `every_app_mcp_list_directory` | Browse directory structure of example apps |
-| `every_app_mcp_read_file` | Read file contents with line numbers |
-| `every_app_mcp_search_code` | Search for patterns using regex |
-| `every_app_mcp_find_files` | Find files matching a glob pattern |
-| `every_app_mcp_fetch_docs` | Fetch Every App documentation pages |
+| `browse` | List available example apps, internal packages, and documentation |
+| `list_directory` | Browse directory structure of examples and docs |
+| `read_file` | Read file contents with line numbers |
+| `search_code` | Search for patterns using regex |
+| `find_files` | Find files matching a glob pattern |
 
-## Configuration (Optional)
-
-You can customize the examples location by setting environment variables:
-
-```json
-{
-  "mcpServers": {
-    "every-app": {
-      "command": "npx",
-      "args": ["-y", "@every-app/mcp"],
-      "env": {
-        "EVERY_APP_EXAMPLES_DIR": "/custom/path/to/examples"
-      }
-    }
-  }
-}
-```
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `EVERY_APP_EXAMPLES_DIR` | Path to examples | `~/.every-app-mcp/examples` |
-| `EVERY_APP_DOCS_DIR` | Path to local docs | Falls back to GitHub |
 
 ## Development
 
@@ -93,10 +67,7 @@ pnpm run build
 pnpm run types:check
 
 # Run locally
-node dist/index.js
+Swap command argument with this:
+`bun run ~/your_workspace/every-app/packages/mcp/src/index.ts`
 ```
 
-## Requirements
-
-- Node.js 18+
-- Git (for automatic example cloning)

package/dist/setup.d.ts

@@ -4,7 +4,7 @@
 export declare function getExamplesDirectory(): string;
 /**
  * Clone or update the examples repository
- * Uses sparse checkout to only get apps/ and templates/ directories
+ * Uses a shallow clone for speed
  */
 export declare function ensureExamplesExist(): Promise<{
     success: boolean;

package/dist/setup.js

@@ -6,7 +6,6 @@ import { execSync, execFileSync } from "node:child_process";
 const DEFAULT_EXAMPLES_DIR = path.join(os.homedir(), ".every-app-mcp", "examples");
 // Repository info
 const REPO_URL = "https://github.com/every-app/every-app.git";
-const SPARSE_PATHS = ["apps", "templates"];
 /**
  * Get the examples directory, using environment variable or default location
  */
@@ -27,42 +26,48 @@ function hasGit() {
 }
 /**
  * Clone or update the examples repository
- * Uses sparse checkout to only get apps/ and templates/ directories
+ * Uses a shallow clone for speed
  */
 export async function ensureExamplesExist() {
     const examplesDir = getExamplesDirectory();
-    // Check if examples already exist and have content
+    // Check if examples already exist
     if (fs.existsSync(examplesDir)) {
-        const hasApps = fs.existsSync(path.join(examplesDir, "apps"));
-        const hasTemplates = fs.existsSync(path.join(examplesDir, "templates"));
-        if (hasApps || hasTemplates) {
-            // Try to update if it's a git repo
-            if (fs.existsSync(path.join(examplesDir, ".git"))) {
-                try {
-                    execFileSync("git", ["pull", "--quiet"], {
-                        cwd: examplesDir,
-                        stdio: "ignore",
-                        timeout: 30000,
-                    });
-                    return {
-                        success: true,
-                        dir: examplesDir,
-                        message: "Examples updated successfully",
-                    };
-                }
-                catch {
-                    // Pull failed, but we have existing examples so continue
-                    return {
-                        success: true,
-                        dir: examplesDir,
-                        message: "Using existing examples (update failed)",
-                    };
-                }
+        // Try to update if it's a git repo
+        if (fs.existsSync(path.join(examplesDir, ".git"))) {
+            try {
+                execFileSync("git", ["fetch", "--depth=1", "origin", "main"], {
+                    cwd: examplesDir,
+                    stdio: "ignore",
+                    timeout: 30000,
+                });
+                execFileSync("git", ["reset", "--hard", "origin/main"], {
+                    cwd: examplesDir,
+                    stdio: "ignore",
+                    timeout: 30000,
+                });
+                return {
+                    success: true,
+                    dir: examplesDir,
+                    message: "Examples updated successfully",
+                };
+            }
+            catch {
+                return {
+                    success: false,
+                    dir: examplesDir,
+                    message: "Failed to update examples repository",
+                };
             }
+        }
+        // Existing directory isn't a git repo; remove and re-clone
+        try {
+            fs.rmSync(examplesDir, { recursive: true, force: true });
+        }
+        catch {
             return {
-                success: true,
+                success: false,
                 dir: examplesDir,
-                message: "Using existing examples",
+                message: "Existing examples directory is not a git repo",
             };
         }
     }
@@ -81,13 +86,7 @@ export async function ensureExamplesExist() {
     }
     try {
         console.error("Cloning Every App examples (this may take a moment)...");
-        // Use sparse checkout to only get apps/ and templates/
-        execFileSync("git", ["clone", "--filter=blob:none", "--sparse", REPO_URL, examplesDir], { stdio: "ignore", timeout: 120000 });
-        execFileSync("git", ["sparse-checkout", "set", ...SPARSE_PATHS], {
-            cwd: examplesDir,
-            stdio: "ignore",
-            timeout: 30000,
-        });
+        execFileSync("git", ["clone", "--depth=1", REPO_URL, examplesDir], { stdio: "ignore", timeout: 120000 });
         return {
             success: true,
             dir: examplesDir,

package/dist/tools/fetch-docs.js

@@ -2,57 +2,78 @@ import { z } from "zod";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { errorResponse, textResponse } from "../utils.js";
-const AVAILABLE_DOCS = `Available pages include:
-- introduction
-- tech-stack/overview
-- tech-stack/tanstack-start
-- tech-stack/drizzle
-- tech-stack/cloudflare
-- embedded-sdk/overview
-- embedded-sdk/client
-- embedded-sdk/server
-- build-an-app/start-from-template
-- build-an-app/development-workflow
-- build-an-app/deployment
-- coding-agent/setup`;
+import { getExamplesDirectory } from "../setup.js";
+/**
+ * Get the docs directory path
+ */
+function getDocsDirectory() {
+    return path.join(getExamplesDirectory(), "landing-page/src/content/docs/docs");
+}
+/**
+ * Recursively find all .mdx files in a directory and return their paths relative to the base
+ */
+function findMdxFiles(dir, basePath = "") {
+    const results = [];
+    if (!fs.existsSync(dir)) {
+        return results;
+    }
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        const relativePath = basePath ? `${basePath}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            results.push(...findMdxFiles(fullPath, relativePath));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".mdx")) {
+            // Remove .mdx extension for the page path
+            results.push(relativePath.replace(/\.mdx$/, ""));
+        }
+    }
+    return results;
+}
 export function registerFetchDocsTool(server) {
-    server.tool("every_app_mcp_fetch_docs", "Fetch content from the Every App documentation. Use this to understand concepts, APIs, and best practices.", {
+    server.tool("fetch_docs", "Browse and read Every App documentation. Call without a page to see available docs, or with a page path to read it.", {
         page: z
             .string()
-            .describe('Documentation page path (e.g., "introduction", "tech-stack/drizzle", "embedded-sdk/client")'),
+            .optional()
+            .describe('Documentation page path (e.g., "introduction", "walkthrough/ai-chat"). Leave empty to list available pages.'),
     }, async ({ page }) => {
+        const docsDir = getDocsDirectory();
+        // If no page specified, list available docs
+        if (!page) {
+            const docPages = findMdxFiles(docsDir);
+            if (docPages.length === 0) {
+                return textResponse(`Documentation not found locally. The docs may not have been cloned yet.
+
+Try restarting the MCP server to trigger a fresh clone, or check that git is available.`);
+            }
+            const docsList = docPages.sort().map((p) => `- ${p}`).join("\n");
+            return textResponse(`# Available Documentation Pages
+
+${docsList}
+
+---
+Call this tool with a page path to read its content.`);
+        }
         // Validate page contains only safe characters (alphanumeric, hyphens, slashes)
         if (!/^[a-zA-Z0-9\-\/]+$/.test(page)) {
-            return errorResponse(`Invalid page path: ${page}\n\n${AVAILABLE_DOCS}`);
+            return errorResponse(`Invalid page path: ${page}. Page paths can only contain letters, numbers, hyphens, and slashes.`);
         }
-        // Try to read from local docs directory first
-        const docsDir = process.env.EVERY_APP_DOCS_DIR;
-        if (docsDir) {
-            // Try to read from local docs directory
-            const localPath = path.join(docsDir, `${page}.mdx`);
-            if (fs.existsSync(localPath)) {
-                const content = fs.readFileSync(localPath, "utf-8");
-                return textResponse(`# ${page}\n\n${content}`);
-            }
-            // Try without .mdx extension (might be a directory index)
-            const indexPath = path.join(docsDir, page, "index.mdx");
-            if (fs.existsSync(indexPath)) {
-                const content = fs.readFileSync(indexPath, "utf-8");
-                return textResponse(`# ${page}\n\n${content}`);
-            }
-        }
-        // Fallback to fetching from GitHub raw content
-        const rawUrl = `https://raw.githubusercontent.com/every-app/every-app/main/landing-page/src/content/docs/docs/${page}.mdx`;
-        try {
-            const response = await fetch(rawUrl);
-            if (!response.ok) {
-                return errorResponse(`Documentation page not found: ${page}\n\n${AVAILABLE_DOCS}`);
-            }
-            const content = await response.text();
+        // Try to read from local docs directory
+        const localPath = path.join(docsDir, `${page}.mdx`);
+        if (fs.existsSync(localPath)) {
+            const content = fs.readFileSync(localPath, "utf-8");
             return textResponse(`# ${page}\n\n${content}`);
         }
-        catch (error) {
-            return errorResponse(`Error fetching docs: ${error instanceof Error ? error.message : "Unknown error"}`);
+        // Try without .mdx extension (might be a directory index)
+        const indexPath = path.join(docsDir, page, "index.mdx");
+        if (fs.existsSync(indexPath)) {
+            const content = fs.readFileSync(indexPath, "utf-8");
+            return textResponse(`# ${page}\n\n${content}`);
         }
+        // Page not found
+        return errorResponse(`Documentation page not found: ${page}
+
+Call this tool without a page argument to see available pages.`);
     });
 }

package/dist/tools/find-files.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import * as fs from "node:fs";
 import { findFiles, getExamplesDir, errorResponse, textResponse, validatePathWithinBase, } from "../utils.js";
 export function registerFindFilesTool(server) {
-    server.tool("every_app_mcp_find_files", "Find files matching a glob pattern in the Every App examples.", {
+    server.tool("find_files", "Find files matching a glob pattern in the Every App examples.", {
         pattern: z
             .string()
             .describe('Glob pattern to match (e.g., "**/*.tsx", "**/schema.ts")'),

package/dist/tools/index.js

@@ -2,13 +2,11 @@ import { registerListDirectoryTool } from "./list-directory.js";
 import { registerReadFileTool } from "./read-file.js";
 import { registerSearchCodeTool } from "./search-code.js";
 import { registerFindFilesTool } from "./find-files.js";
-import { registerFetchDocsTool } from "./fetch-docs.js";
-import { registerListExamplesTool } from "./list-examples.js";
+import { registerBrowseTool } from "./list-examples.js";
 export function registerAllTools(server) {
     registerListDirectoryTool(server);
     registerReadFileTool(server);
     registerSearchCodeTool(server);
     registerFindFilesTool(server);
-    registerFetchDocsTool(server);
-    registerListExamplesTool(server);
+    registerBrowseTool(server);
 }

package/dist/tools/list-directory.js

@@ -3,7 +3,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { IGNORE_PATTERNS, getExamplesDir, errorResponse, textResponse, validatePathWithinBase, } from "../utils.js";
 export function registerListDirectoryTool(server) {
-    server.tool("every_app_mcp_list_directory", "List files and directories in the Every App examples. Use this to explore the structure of example apps.", {
+    server.tool("list_directory", "List files and directories in the Every App examples. Use this to explore the structure of example apps.", {
         path: z
             .string()
             .optional()

package/dist/tools/list-examples.d.ts

@@ -1,2 +1,2 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare function registerListExamplesTool(server: McpServer): void;
+export declare function registerBrowseTool(server: McpServer): void;

package/dist/tools/list-examples.js

@@ -1,13 +1,17 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { textResponse } from "../utils.js";
+import { getExamplesDirectory } from "../setup.js";
 const EXAMPLE_APPS = [
     {
         name: "apps/todo-app",
         description: "Simple todo application demonstrating basic CRUD operations, routing, and embedded app patterns",
         goodFor: [
+            "Embedded provider usage",
             "Basic data relationships",
-            "Complex Drag & Drop",
+            "Complex Drag & Drop and fractional indexing for ordering",
+            "Keybindings and keyboard based navigation",
             "Route setup",
-            "Embedded provider usage",
         ],
     },
     {
@@ -16,24 +20,131 @@ const EXAMPLE_APPS = [
         goodFor: [
             "Complex TanstackDB Optimistic Updates",
             "Simple Drag & Drop",
-            "Complex data relationships",
+            "Slide animations for mobile navigation",
+            "Complex data relationships and drizzle schema",
             "Form handling",
             "Advanced queries",
         ],
     },
     {
-        name: "apps/every-chef",
-        description: "Cooking assistant with LLM integration",
+        name: "apps/chef",
+        description: "AI-powered cooking assistant with image analysis and recipe management",
+        goodFor: [
+            "Authenticated image upload and access (R2 storage with auth-gated retrieval)",
+            "AI Chat with image upload, mobile camera access, and optimistic UI updates",
+            "Streaming AI responses with database persistence",
+            "Human-in-loop AI tools (AI suggests, user approves)",
+            "Multi-part messages (text, images, tool invocations)",
+            "Drawer based mobile navigation instead of TabBar due to wanting to show list of chats nicely. Helpful for any UI which needs dynamic navigation instead of 4 or 5 TabBar items.",
+        ],
+    },
+];
+const INTERNAL_PACKAGES = [
+    {
+        name: "apps/every-app-gateway",
+        description: "The Every App Gateway - central authentication hub that manages user accounts and hosts embedded apps",
+        goodFor: [
+            "Understanding how authentication flows work",
+            "How embedded apps are loaded and displayed",
+            "JWT token generation and validation",
+            "User session management",
+            "How the Gateway communicates with embedded apps via postMessage",
+        ],
+    },
+    {
+        name: "packages/sdk",
+        description: "The @every-app/sdk package - client and server utilities for building Every Apps",
         goodFor: [
-            "LLM integration patterns",
-            "AI-powered features",
-            "Streaming responses",
+            "EmbeddedAppProvider implementation",
+            "Session management and authentication helpers",
+            "Server-side request authentication",
+            "Understanding how apps communicate with the Gateway",
+        ],
+    },
+    {
+        name: "packages/cli",
+        description: "The @every-app/cli package - command-line tool for creating and deploying Every Apps",
+        goodFor: [
+            "How app creation works (templates, scaffolding)",
+            "Deployment flow to Cloudflare",
+            "Gateway deployment and configuration",
+            "Database migrations and secret management",
+        ],
+    },
+    {
+        name: "packages/mcp",
+        description: "The @every-app/mcp package - MCP server that provides access to examples and documentation",
+        goodFor: [
+            "How this MCP server is built",
+            "Example of building MCP tools",
+            "Sparse git checkout patterns",
         ],
     },
 ];
-export function registerListExamplesTool(server) {
-    server.tool("every_app_mcp_list_examples", "List available Every App example applications and what they demonstrate.", {}, async () => {
-        const output = EXAMPLE_APPS.map((ex) => `## ${ex.name}\n${ex.description}\n\n**Good for learning:**\n${ex.goodFor.map((g) => `- ${g}`).join("\n")}`).join("\n\n---\n\n");
-        return textResponse(`# Available Every App Examples\n\n${output}\n\n---\n\nUse \`every_app_mcp_list_directory\` to explore the structure of any example, and \`every_app_mcp_read_file\` to view implementation details.`);
+/**
+ * Recursively find all .mdx files in a directory and return their paths relative to the base
+ */
+function findMdxFiles(dir, basePath = "") {
+    const results = [];
+    if (!fs.existsSync(dir)) {
+        return results;
+    }
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        const relativePath = basePath ? `${basePath}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            results.push(...findMdxFiles(fullPath, relativePath));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".mdx")) {
+            // Remove .mdx extension for display
+            results.push(relativePath.replace(/\.mdx$/, ""));
+        }
+    }
+    return results;
+}
+/**
+ * Get the docs directory path
+ */
+function getDocsDirectory() {
+    return path.join(getExamplesDirectory(), "landing-page/src/content/docs/docs");
+}
+function formatEntries(entries) {
+    return entries
+        .map((entry) => `## ${entry.name}\n${entry.description}\n\n**Good for learning:**\n${entry.goodFor.map((g) => `- ${g}`).join("\n")}`)
+        .join("\n\n---\n\n");
+}
+export function registerBrowseTool(server) {
+    server.tool("browse", "Browse available Every App resources: example apps, internal packages, and documentation. Start here to discover what's available.", {}, async () => {
+        const examplesOutput = formatEntries(EXAMPLE_APPS);
+        const internalsOutput = formatEntries(INTERNAL_PACKAGES);
+        // Dynamically discover docs
+        const docsDir = getDocsDirectory();
+        const docPages = findMdxFiles(docsDir).sort();
+        const docsOutput = docPages.length > 0
+            ? `Use \`read_file\` with path \`landing-page/src/content/docs/docs/<page>.mdx\` to read any of these:\n\n${docPages.map((p) => `- ${p}`).join("\n")}`
+            : "Documentation not available. Try reconnecting the MCP server to trigger a fresh clone.";
+        return textResponse(`# Every App Resources
+
+**Note:** Code examples are from the latest version on GitHub. The user may be on an older version of the SDK, CLI, or Gateway. If something doesn't match what they're seeing, check their package versions.
+
+---
+
+# Documentation
+${docsOutput}
+
+---
+
+# Example Applications
+Complete example apps you can learn from. Use \`list_directory\` and \`read_file\` to explore:
+
+${examplesOutput}
+
+---
+
+# Internal Packages
+Core Every App packages - useful for understanding how Every App works:
+
+${internalsOutput}`);
     });
 }

package/dist/tools/read-file.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import * as fs from "node:fs";
 import { getExamplesDir, errorResponse, textResponse, validatePathWithinBase } from "../utils.js";
 export function registerReadFileTool(server) {
-    server.tool("every_app_mcp_read_file", "Read the contents of a file from the Every App examples. Use this to see how patterns are implemented.", {
+    server.tool("read_file", "Read the contents of a file from the Every App examples. Use this to see how patterns are implemented.", {
         path: z
             .string()
             .describe('Path relative to the Every App examples root (e.g., "apps/todo-app/src/routes/index.tsx")'),

package/dist/tools/search-code.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import * as fs from "node:fs";
 import { searchFiles, getExamplesDir, errorResponse, textResponse, validatePathWithinBase, } from "../utils.js";
 export function registerSearchCodeTool(server) {
-    server.tool("every_app_mcp_search_code", "Search for patterns in the Every App examples using regex. Use this to find implementations of specific patterns.", {
+    server.tool("search_code", "Search for patterns in the Every App examples using regex. Use this to find implementations of specific patterns.", {
         pattern: z.string().describe("Regular expression pattern to search for"),
         path: z
             .string()

package/dist/utils.js

@@ -54,14 +54,32 @@ export function errorResponse(text) {
 }
 // Validate that a resolved path stays within the base directory (prevents path traversal)
 export function validatePathWithinBase(baseDir, inputPath) {
-    const resolvedBase = path.resolve(baseDir);
-    const resolvedPath = path.resolve(baseDir, inputPath);
+    let resolvedBase;
+    try {
+        resolvedBase = fs.realpathSync(baseDir);
+    }
+    catch {
+        return { valid: false, error: "Base directory not accessible" };
+    }
+    const resolvedPath = path.resolve(resolvedBase, inputPath);
     if (!resolvedPath.startsWith(resolvedBase + path.sep) && resolvedPath !== resolvedBase) {
         return {
             valid: false,
             error: "Path traversal detected - access denied",
         };
     }
+    if (fs.existsSync(resolvedPath)) {
+        let realPath;
+        try {
+            realPath = fs.realpathSync(resolvedPath);
+        }
+        catch {
+            return { valid: false, error: "Path not accessible" };
+        }
+        if (!realPath.startsWith(resolvedBase + path.sep) && realPath !== resolvedBase) {
+            return { valid: false, error: "Path resolves outside base directory" };
+        }
+    }
     return { valid: true, resolvedPath };
 }
 // Helper to create success response

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@every-app/mcp",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "MCP server for Every App coding agents",
   "type": "module",
   "bin": {