Val Town Code SearchReturn to Val Town

104- For AI-generated images, use: `https://maxm-imggenurl.web.val.run/the-description-of-your-image`
105- **Storage:** DO NOT use the Deno KV module for storage
106- **Browser APIs:** DO NOT use the `alert()`, `prompt()`, or `confirm()` methods
107- **Weather Data:** Use open-meteo for weather data (doesn't require API keys) unless otherwise specified
108- **View Source:** Add a view source link with `import.meta.url.replace("esm.town", "val.town")` and include `target="_top"` attribute
109- **Error Debugging:** Add `<script src="https://esm.town/v/std/catch"></script>` to HTML to capture client-side errors
110- **Error Handling:** Only use try...catch when there's a clear local resolution; avoid catches that merely log or return 500s - let errors bubble up with full context
111- **Environment Variables:** Use `Deno.env.get('keyname')` and minimize their use - prefer APIs without keys
112- **Imports:** Use JSR.io, NPM and ESM imports in that order to ensure the latest and stable versions are available to use from official providers.
113- **Storage Strategy:** Only use backend storage if explicitly required; prefer simple static client-side sites
194
195### Backend (Hono) Best Practices
196- Hono is the recommended API framework (similar to Express, Flask, or Sinatra)
197- Main entry point should be `backend/index.ts`
198- **Static asset serving:** Use the utility functions to read and serve project files:
215  });
216  ```
217- Create RESTful API routes for CRUD operations
218- Be careful with error handling as Hono tends to swallow errors
219- Consider re-throwing errors to see full stack traces:
232- Use React 18.2.0 consistently in all imports and the `@jsxImportSource` pragma
233- Follow the React component pattern from the example project
234- Handle API calls properly with proper error catching
235
236### Database Patterns
263   - For files in the project, use `readFile` helpers
264
2655. **API Design:**
266   - `fetch` handler is the entry point for HTTP vals
267   - Run the Hono app with `export default app.fetch // This is the entry point for HTTP vals`

16build
17taskNotes
18valTownApi.json
19valtownAPIv2.json
20val-town-mcp-server
21.claude

7- Generate code in TypeScript or TSX
8- Add appropriate TypeScript types and interfaces for all data structures
9- Prefer official SDKs or libraries than writing API calls directly
10- **Never bake in secrets into the code** - always use environment variables
11- Include comments explaining complex logic (avoid commenting obvious operations)
16### 1. HTTP Trigger
17
18- Create web APIs and endpoints
19- Handle HTTP requests and responses
20- Example structure:
164However, it's *extremely important* to note that `parseProject` and other Standard Library utilities ONLY RUN ON THE SERVER.
165If you need access to this data on the client, run it in the server and pass it to the client by splicing it into the HTML page
166or by making an API request for it.
167
168## Val Town Platform Specifics
172- **AI Image:** To inline generate an AI image use: `<img src="https://maxm-imggenurl.web.val.run/the-description-of-your-image" />`
173- **Storage:** DO NOT use the Deno KV module for storage
174- **Browser APIs:** DO NOT use the `alert()`, `prompt()`, or `confirm()` methods
175- **Weather Data:** Use open-meteo for weather data (doesn't require API keys) unless otherwise specified
176- **View Source:** Add a view source link by importing & using `import.meta.url.replace("ems.sh", "val.town)"` (or passing this data to the client) and include `target="_top"` attribute
177- **Error Debugging:** Add `<script src="https://esm.town/v/std/catch"></script>` to HTML to capture client-side errors
178- **Error Handling:** Only use try...catch when there's a clear local resolution; Avoid catches that merely log or return 500s. Let errors bubble up with full context
179- **Environment Variables:** Use `Deno.env.get('keyname')` when you need to, but generally prefer APIs that don't require keys
180- **Imports:** Use `https://esm.sh` for npm and Deno dependencies to ensure compatibility on server and browser
181- **Storage Strategy:** Only use backend storage if explicitly required; prefer simple static client-side sites
215### Backend (Hono) Best Practices
216
217- Hono is the recommended API framework
218- Main entry point should be `backend/index.ts`
219- **Static asset serving:** Use the utility functions to read and serve project files:
239  });
240  ```
241- Create RESTful API routes for CRUD operations
242- Always include this snippet at the top-level Hono app to re-throwing errors to see full stack traces:
243  ```ts
276   - For files in the project, use `readFile` helpers
277
2785. **API Design:**
279   - `fetch` handler is the entry point for HTTP vals
280   - Run the Hono app with `export default app.fetch // This is the entry point for HTTP vals`

26  * DO NOT use the alert(), prompt(), or confirm() methods.
27
28  * If the user's app needs weather data, use open-meteo unless otherwise specified because it doesn't require any API keys.
29
30  * Tastefully add a view source link back to the user's val if there's a natural spot for it. Generate the val source url via `import.meta.url.replace("esm.town", "val.town")`. This link element should include a target="_top" attribute.
38    Val Town's client-side catch script automatically catches client-side errors to aid in debugging.
39
40  * Don't use any environment variables unless strictly necessary. For example use APIs that don't require a key.
41    If you need environment variables use `Deno.env.get('keyname')`
42

12
13Projects can include multiple file types:
14   - `http`: HTTP handler files for web APIs and sites
15   - `script`: Importable module files
16   - `cron`: Scheduled job files that run at intervals
36* For AI-generated images, use: https://maxm-imggenurl.web.val.run/[description]
37* DO NOT use Deno KV module, alert(), prompt(), or confirm() methods
38* For weather data, use open-meteo (no API key required)
39* Add a view source link with import.meta.url.replace("esm.town", "val.town")
40* For client-side code, include <script src="https://esm.town/v/std/catch"></script>
101│   │   └── queries.ts
102│   └── routes/
103│       ├── api.ts
104│       └── static.ts
105│   └── index.ts
116## Val Town Access Methods
117
118As an assistant, you'll help users work with Val Town through an integrated approach using both MCP tools and the vt CLI together. The MCP server automatically checks if the vt CLI is installed and accessible, using it when available or falling back to API calls when needed.
119
120### MCP Tools with CLI Integration

2import {z} from "npm:zod"
3import {Config} from "../lib/types.ts"
4import {callValTownApi} from "../lib/api.ts"
5import {getErrorMessage} from "../lib/errorUtils.ts"
6
15    async ({statement}: {statement: string}) => {
16      try {
17        const data = await callValTownApi(config, "/v1/sqlite/execute", {
18          method: "POST",
19          body: JSON.stringify({statement}),
46    }) => {
47      try {
48        const data = await callValTownApi(config, "/v1/sqlite/batch", {
49          method: "POST",
50          body: JSON.stringify({statements, mode}),
73    async ({statement}: {statement: string}) => {
74      try {
75        const data = await callValTownApi(config, "/v1/sqlite/query", {
76          method: "POST",
77          body: JSON.stringify({statement}),
104    }) => {
105      try {
106        const data = await callValTownApi(config, "/v1/sqlite/exec", {
107          method: "POST",
108          body: JSON.stringify({statements, mode}),

1import {McpServer} from "npm:@modelcontextprotocol/sdk/server/mcp.js"
2import {Config} from "../lib/types.ts"
3import {callValTownApi} from "../lib/api.ts"
4import {getErrorMessage} from "../lib/errorUtils.ts"
5import {getCliAvailability, runVtCommand, parseCliJsonOutput} from "../lib/vtCli.ts"
37          }
38          
39          console.error(`CLI error when getting val, falling back to API: ${result.error}`);
40          // Fall back to API on error
41        } catch (error) {
42          console.error("CLI error, falling back to API:", getErrorMessage(error));
43          // Fall back to API on error
44        }
45      }
46
47      // API implementation (original code)
48      try {
49        const data = await callValTownApi(
50          config,
51          `/v2/alias/vals/${encodeURIComponent(username)}/${encodeURIComponent(valName)}`
75    async ({query, limit, offset}) => {
76      try {
77        const data = await callValTownApi(
78          config,
79          `/v1/search/vals?query=${encodeURIComponent(query)}&limit=${limit}&offset=${offset}`
135          }
136          
137          console.error(`CLI error when creating val, falling back to API: ${result.error}`);
138          // Fall back to API on error
139        } catch (error) {
140          console.error("CLI error, falling back to API:", getErrorMessage(error));
141          // Fall back to API on error
142        }
143      }
144
145      // API implementation (original code)
146      try {
147        const requestBody = {
151        }
152
153        const data = await callValTownApi(
154          config,
155          `/v2/vals`,
192          
193          // Use prepareValWorkspace first (would need to implement special workspace setup)
194          // For now, we'll use the API implementation instead of complex workspace management
195          
196          // This could be implemented with temporary directory setup if needed, 
197          // but for now we'll use the API for deletion as it's simpler
198          console.log("Deletion via CLI requires workspace setup, using API instead");
199        } catch (error) {
200          console.error("CLI error, falling back to API:", getErrorMessage(error));
201          // Fall back to API on error
202        }
203      }
204
205      // API implementation (original code)
206      try {
207        await callValTownApi(
208          config,
209          `/v2/vals/${valId}`,
262          }
263          
264          console.error(`CLI error when listing vals, falling back to API: ${result.error}`);
265          // Fall back to API on error
266        } catch (error) {
267          console.error("CLI error, falling back to API:", getErrorMessage(error));
268          // Fall back to API on error
269        }
270      }
271
272      // API implementation (original code)
273      try {
274        const data = await callValTownApi(
275          config,
276          `/v2/me/vals?limit=${limit}&offset=${offset}`

1import {McpServer} from "npm:@modelcontextprotocol/sdk/server/mcp.js"
2import {Config} from "../lib/types.ts"
3import {callValTownApi} from "../lib/api.ts"
4import {getErrorMessage} from "../lib/errorUtils.ts"
5import {getCliAvailability, runVtCommand, parseCliJsonOutput, prepareValWorkspace, cleanupTempDirectory} from "../lib/vtCli.ts"
48          }
49          
50          console.error(`CLI error when listing branches, falling back to API: ${workspace.error || "Unknown error"}`);
51          // Fall back to API on error
52        } catch (error) {
53          console.error("CLI error, falling back to API:", getErrorMessage(error));
54          // Fall back to API on error
55        }
56      }
57
58      // API implementation (original code)
59      try {
60        const data = await callValTownApi(
61          config,
62          `/v2/vals/${valId}/branches?limit=${limit}&offset=${offset}`
85    async ({valId, branchId}) => {
86      try {
87        const data = await callValTownApi(
88          config,
89          `/v2/vals/${valId}/branches/${branchId}`
132                console.error(`Failed to checkout source branch: ${checkoutResult.error}`);
133                await cleanupTempDirectory(workspace.workspacePath);
134                // Fall back to API
135                console.error("CLI error when checking out source branch, falling back to API");
136                throw new Error("Failed to checkout source branch");
137              }
155          }
156          
157          console.error(`CLI error when creating branch, falling back to API: ${workspace.error || "Unknown error"}`);
158          // Fall back to API on error
159        } catch (error) {
160          console.error("CLI error, falling back to API:", getErrorMessage(error));
161          // Fall back to API on error
162        }
163      }
164
165      // API implementation (original code)
166      try {
167        const requestBody = {
170        }
171
172        const data = await callValTownApi(
173          config,
174          `/v2/vals/${valId}/branches`,
227          }
228          
229          console.error(`CLI error when deleting branch, falling back to API: ${workspace.error || "Unknown error"}`);
230          // Fall back to API on error
231        } catch (error) {
232          console.error("CLI error, falling back to API:", getErrorMessage(error));
233          // Fall back to API on error
234        }
235      }
236
237      // API implementation (original code)
238      try {
239        await callValTownApi(
240          config,
241          `/v2/vals/${valId}/branches/${branchId}`,

1import {McpServer} from "npm:@modelcontextprotocol/sdk/server/mcp.js"
2import {Config} from "../lib/types.ts"
3import {callValTownApi} from "../lib/api.ts"
4import {getErrorMessage} from "../lib/errorUtils.ts"
5import {getCliAvailability, runVtCommand, parseCliJsonOutput, prepareValWorkspace, cleanupTempDirectory} from "../lib/vtCli.ts"
122                console.error(`Failed to checkout branch: ${checkoutResult.error}`)
123                await cleanupTempDirectory(workspace.workspacePath!)
124                // Fall back to API
125                console.error("CLI error when checking out branch, falling back to API")
126                throw new Error("Failed to checkout branch")
127              }
147          }
148
149          console.error(`CLI error when listing files, falling back to API: ${workspace.error || "Unknown error"}`)
150          // Fall back to API on error
151        } catch (error) {
152          console.error("CLI error, falling back to API:", getErrorMessage(error))
153          // Fall back to API on error
154        }
155      }
156
157      // API implementation (original code)
158      try {
159        let queryParams = `?path=${encodeURIComponent(path)}&recursive=${recursive}&limit=${limit}&offset=${offset}`
162        }
163
164        const data = await callValTownApi(
165          config,
166          `/v2/vals/${valId}/files${queryParams}`
197
198        const response = await fetch(
199          `${config.apiBase}/v2/vals/${valId}/files/content${queryParams}`,
200          {
201            headers: {
202              'Authorization': `Bearer ${config.apiToken}`,
203            },
204          }
207        if (!response.ok) {
208          const errorText = await response.text()
209          throw new Error(`API error (${response.status}): ${errorText}`)
210        }
211
295            }
296          } else {
297            console.error(`CLI error when creating ${type}, falling back to API: ${result.error}`)
298            // Fall back to API
299          }
300        } catch (error) {
301          console.error("CLI error, falling back to API:", getErrorMessage(error))
302          // Fall back to API on error
303        }
304      }
305
306      // API implementation (original code)
307      try {
308        let queryParams = `?path=${encodeURIComponent(filePath)}`
316        }
317
318        const data = await callValTownApi(
319          config,
320          `/v2/vals/${valId}/files${queryParams}`,
384            }
385          } else {
386            console.error(`CLI error when updating file, falling back to API: ${result.error}`)
387            // Fall back to API
388          }
389        } catch (error) {
390          console.error("CLI error, falling back to API:", getErrorMessage(error))
391          // Fall back to API on error
392        }
393      }
394
395      // API implementation (original code)
396      try {
397        let queryParams = `?path=${encodeURIComponent(filePath)}`
400        }
401
402        const data = await callValTownApi(
403          config,
404          `/v2/vals/${valId}/files${queryParams}`,
488            }
489          } else {
490            console.error(`CLI error when deleting path, falling back to API: ${result.error}`)
491            // Fall back to API
492          }
493        } catch (error) {
494          console.error("CLI error, falling back to API:", getErrorMessage(error))
495          // Fall back to API on error
496        }
497      }
498
499      // API implementation (original code)
500      try {
501        let queryParams = `?path=${encodeURIComponent(filePath)}&recursive=${recursive}`
504        }
505
506        await callValTownApi(
507          config,
508          `/v2/vals/${valId}/files${queryParams}`,

2import {z} from "npm:zod"
3import {Config} from "../lib/types.ts"
4import {callValTownApi} from "../lib/api.ts"
5import {getErrorMessage} from "../lib/errorUtils.ts"
6
16      try {
17        const queryParams = prefix ? `?prefix=${encodeURIComponent(prefix)}` : ""
18        const data = await callValTownApi(config, `/v1/blob${queryParams}`)
19
20        return {
41      try {
42        // For blobs, we need to handle binary data differently
43        const url = `${config.apiBase}/v1/blob/${encodeURIComponent(key)}`
44        const response = await fetch(url, {
45          headers: {
46            "Authorization": `Bearer ${config.apiToken}`,
47          },
48        })
50        if (!response.ok) {
51          const errorText = await response.text()
52          throw new Error(`API request failed: ${response.status} ${response.statusText}\n${errorText}`)
53        }
54
109        }
110
111        const url = `${config.apiBase}/v1/blob/${encodeURIComponent(key)}`
112        const response = await fetch(url, {
113          method: "POST",
114          headers: {
115            "Authorization": `Bearer ${config.apiToken}`,
116            "Content-Type": contentType,
117          },
121        if (!response.ok) {
122          const errorText = await response.text()
123          throw new Error(`API request failed: ${response.status} ${response.statusText}\n${errorText}`)
124        }
125
146    async ({key}: {key: string}) => {
147      try {
148        await callValTownApi(config, `/v1/blob/${encodeURIComponent(key)}`, {
149          method: "DELETE",
150        })