Val Town Code SearchReturn to Val Town

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

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`

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 ({username}: {username: string}) => {
16      try {
17        const data = await callValTownApi(config, `/v1/alias/${encodeURIComponent(username)}`)
18
19        return {
37    async () => {
38      try {
39        const data = await callValTownApi(config, "/v1/me")
40
41        return {

1
2export interface Config {
3    apiToken: string | null
4    apiBase: string
5    cli?: {
6        preferCli: boolean

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)