Val Town Code SearchReturn to Val Town

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

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}),

2import {z} from "npm:zod"
3import {Config} from "../lib/types.ts"
4import {callValTownApi} from "../lib/api.ts"
5import {getCliAvailability, runVtCommand} from "../lib/vtCli.ts"
6
16    async ({limit, offset}: {limit: number; offset: number}) => {
17      try {
18        const data = await callValTownApi(
19          config,
20          `/v1/me/projects?limit=${limit}&offset=${offset}`
44    async ({projectId}: {projectId: string}) => {
45      try {
46        const data = await callValTownApi(config, `/v1/projects/${projectId}`)
47
48        return {
84            }
85          }
86          // If CLI fails, fall back to API
87        } catch (error) {
88          console.error("CLI error:", error)
89          // Continue to API fallback
90        }
91      }
92
93      // Fallback to original API implementation
94      try {
95        const data = await callValTownApi(
96          config,
97          `/v1/alias/projects/${encodeURIComponent(username)}/${encodeURIComponent(projectName)}`
162        }
163
164        const data = await callValTownApi(config, "/v1/projects", {
165          method: "POST",
166          body: JSON.stringify(payload),
190    async ({projectId}: {projectId: string}) => {
191      try {
192        await callValTownApi(config, `/v1/projects/${projectId}`, {
193          method: "DELETE",
194        })

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`

46app.post("/mcp", async (c) => {
47  try {
48    // Extract API token from headers
49    const apiToken = c.req.header("X-Val-Town-Token") ||
50      c.req.header("Authorization")?.replace("Bearer ", "")
51
52    if (!apiToken) {
53      return c.json({
54        jsonrpc: "2.0",
55        error: {code: -32000, message: "Missing API token in X-Val-Town-Token header or Authorization header"},
56        id: null
57      }, 401)
60    // Load remote configuration
61    const config = await loadConfig(true)
62    config.apiToken = apiToken
63
64    console.log({apiToken})
65    // Convert Hono request to Node.js-style req/res
66    const {req, res} = toReqRes(c.req.raw)

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}`,

1# Val Town API token - get from https://www.val.town/settings
2VAL_TOWN_API_TOKEN=your_api_token_here
3

6    // For remote: expect token in request headers, use local prompt file
7    return {
8      apiToken: null, // Will be set from headers
9      apiBase: "https://api.val.town",
10      cli: {
11        preferCli: false,
22  dotenvConfig({ export: true });
23
24  const API_TOKEN = Deno.env.get("VAL_TOWN_API_TOKEN");
25  if (!API_TOKEN) {
26    console.error("Error: VAL_TOWN_API_TOKEN environment variable is required");
27    Deno.exit(1);
28  }
46    : undefined;
47  return {
48    apiToken: API_TOKEN,
49    apiBase: "https://api.val.town",
50    cli: {
51      preferCli: PREFER_CLI,

20- Feature branches: `feature/description`, bug fixes: `fix/description`
21- Validate all user inputs and follow least privilege principle
22- Never commit API tokens or secrets
23- Each tool should have a clear purpose with descriptive parameters

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}`,