docs: update CLAUDE.md with ValTown context and fix repository URLs (#2)

* feat: add remote HTTP transport for ValTown deployment

- Modify registerTools() to accept excludeCli parameter
- Update config.ts for remote mode with header-based authentication
- Create index.ts HTTP entry point with streamable transport
- Remove backend directory and setup ValTown project structure
- Add .vtignore to exclude local files from deployment
- Update Config type to support null apiToken for remote mode

* feat: complete remote HTTP MCP server implementation

- Implement HTTP transport with JSON-RPC protocol handling
- Add missing CLI utility functions as placeholders for remote mode
- Fix transport interface and MCP server integration
- Support initialize, tools/list, tools/call, prompts/list, prompts/get methods
- Add proper CORS headers and error handling
- Complete all planned phases for ValTown deployment

* fix: update CLI function calls to match interface signatures

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* feat: migrate from deno.json import map to direct npm imports

- Remove import map from deno.json to support ValTown deployment
- Update all TypeScript files to use direct npm imports (npm:zod, npm:@modelcontextprotocol/sdk)
- Maintains compatibility with both CLI and ValTown environments
- All tools now use direct imports instead of import map resolution

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* feat: add GET endpoint for MCP server info

- Add GET / endpoint that returns server information
- Include server name, version, description, and available endpoints
- Update CORS to allow GET requests
- Show 'Configuration endpoint coming soon' message

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: use native Response for GET endpoint

- Replace c.json() with new Response() for better ValTown compatibility
- Manually set Content-Type and CORS headers
- Fix 'Return value from serve handler must be a response' error

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: export app.fetch for ValTown compatibility

- Change from 'export default app' to 'export default app.fetch'
- Fixes 'Return value from serve handler must be a response' error
- GET endpoint now working correctly and returning server info JSON

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* feat: complete import map migration and HTTP endpoint

- Remove unused parameter warning in index.http.ts
- Add debug logging for request methods
- Update .vtignore to include prompts directory for deployment
- Complete migration from deno.json import map to direct npm imports
- All builds passing and HTTP endpoint working correctly

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: move catch-all handler after specific routes

- Move app.all('/*') handler to end of file
- Ensures GET and POST handlers are matched before catch-all
- Fixes HTTP 405 error for MCP POST requests

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: remove catch-all route causing 405 errors for POST requests

The catch-all app.all("/*") route was intercepting POST requests before
they could reach the specific POST handler, causing HTTP 405 errors.
Removed the unnecessary catch-all as Hono automatically returns 404 for
undefined routes and CORS middleware handles OPTIONS.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: update CLAUDE.md with ValTown context and fix repository URLs

- Add proper CLAUDE.md header for Claude Code guidance
- Include ValTown platform explanation for developers
- Document dual deployment architecture (local vs remote)
- Fix placeholder repository URLs in README.md and index.http.ts
- Add remote server hosting information
- Update CHANGELOG.md with documentation improvements

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: address security vulnerabilities in HTTP MCP server

- Remove API token logging to prevent credential exposure
- Add proper JSON parsing error handling with standard JSON-RPC error codes
- Sanitize error responses to prevent information leakage
- Update changelog with security fixes

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: PrashamTrivedi

.vt/state.json

@@ -0,0 +1,13 @@
+{
+    "val": {
+        "id": "60348fda-486c-11f0-bdd2-76b3cceeab13"
+    },
+    "branch": {
+        "id": "6034f72c-486c-11f0-bdd2-76b3cceeab13",
+        "version": 54
+    },
+    "lastRun": {
+        "pid": 72741,
+        "time": "2025-06-14T12:44:10.103Z"
+    }
+}

.vtignore

@@ -0,0 +1,22 @@
+.git
+.vscode
+.cursorrules
+.DS_Store
+node_modules
+vendor
+taskNotes/
+README.md
+deno.lock
+CHANGELOG.md
+LICENSE
+mcp-documentation.md
+mcp.txt
+.github
+docs
+build
+taskNotes
+valTownApi.json
+valtownAPIv2.json
+val-town-mcp-server
+.claude
+mod.ts

CHANGELOG.md

@@ -4,13 +4,30 @@
 
 ### Added
 
+- Added remote HTTP transport for ValTown deployment
+- Added GET endpoint for MCP server info
+- Added online connection method to README with hosted ValTown server
+  configuration
 - Added changelog documentation and guidelines
 - Added prompt files for Townie and OpenTownie templates with guidelines
 - Included prompt files in build tasks for all platforms
+- Added comprehensive CLAUDE.md with ValTown platform context and architecture overview
 
 ### Changed
 
-- Updated README with improved documentation for first-time visitors
+- Upgraded to V2 APIs with enhanced prompt system and branch management tools
+- Migrated from deno.json import map to direct npm imports
+- Updated README with improved documentation for first-time visitors and online
+  connection method
+- Updated CLI function calls to match interface signatures
+- Updated Config interface and fixed Deno.run API usage
+
+### Fixed
+
+- Fixed placeholder repository URLs in README.md and index.http.ts documentation links
+- Fixed security vulnerability: removed API token logging in HTTP requests
+- Fixed missing JSON parse error handling in HTTP MCP endpoint
+- Fixed information leakage in HTTP error responses
 
 ## [v0.2]
 

CLAUDE.md

@@ -1,12 +1,43 @@
-# ValTown MCP Server Guidelines
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## About ValTown
+
+ValTown is a serverless platform for running TypeScript/JavaScript code in the cloud. Key concepts for developers:
+
+- **Vals**: Code snippets that can be HTTP endpoints, scheduled functions, or scripts
+- **HTTP Vals**: Functions that handle HTTP requests (similar to serverless functions)
+- **Interval Vals**: Functions that run on a schedule (like cron jobs)
+- **Script Vals**: One-time or manually triggered functions
+- **Email Vals**: Functions that handle incoming emails
+- **API Integration**: Full REST API for programmatic access to create/update/delete vals
+- **Remote Execution**: Code runs in ValTown's sandboxed environment with built-in npm package support
+
+## Architecture Overview
+
+This is a Model Context Protocol (MCP) server that provides AI assistants with access to ValTown's platform. The codebase supports two deployment modes:
+
+1. **Local Binary Mode** (`mod.ts`): Runs as a local MCP server using stdio transport
+2. **Remote HTTP Mode** (`index.http.ts`): Deployed on ValTown itself as an HTTP endpoint, accessible via streamable HTTP transport
+
+The server is hosted remotely on ValTown at: `https://prashamtrivedi-valtown-mcp-server.val.run/mcp`
+
+Key files:
+- `mod.ts`: Local stdio MCP server entry point
+- `index.http.ts`: Remote HTTP MCP server entry point (deployed on ValTown)
+- `registerTools.ts`: Tool registration with CLI exclusion support for remote deployment
+- `config.ts`: Configuration loading with remote/local mode support
 
 ## Commands
-- Run server: `deno task start`
+
+- Run server locally: `deno task start`
 - Development mode: `deno task dev`
 - Build binaries: `deno task build`
 - Platform-specific builds: `deno task build:linux`, `deno task build:windows`, `deno task build:macos`
 
 ## Style Guidelines
+
 - Use TypeScript strict mode with explicit typing for function parameters/returns
 - 2-space indentation, semicolons at line ends
 - Use camelCase for variables/functions, PascalCase for types/interfaces, UPPER_SNAKE_CASE for constants
@@ -16,6 +47,7 @@
 - Return consistent error responses with isError flag
 
 ## Conventions
+
 - Follow [Conventional Commits](https://www.conventionalcommits.org/) format
 - Feature branches: `feature/description`, bug fixes: `fix/description`
 - Validate all user inputs and follow least privilege principle

README.md

@@ -14,7 +14,7 @@ allows AI assistants to execute code in the ValTown environment.
 ### Option 1: Use pre-built binaries
 
 Download the appropriate binary for your platform from the
-[latest release](https://github.com/YOUR_USERNAME/valtown-mcp-server/releases/latest):
+[latest release](https://github.com/PrashamTrivedi/valtown-mcp-server/releases/latest):
 
 - Linux: `valtown-mcp-linux`
 - Windows: `valtown-mcp-windows.exe`
@@ -51,6 +51,30 @@ You can obtain a ValTown API token from your
 
 ## Usage with MCP Clients
 
+### Online Connection (Hosted on ValTown)
+
+The easiest way to use this MCP server is to connect to the hosted version running on ValTown:
+
+```json
+{
+  "mcpServers": {
+    "valtown": {
+      "type": "streamable-http",
+      "url": "https://prashamtrivedi-valtown-mcp-server.val.run/mcp",
+      "headers": {
+        "x-val-town-token": "YOUR_VAL_TOWN_TOKEN_HERE"
+      }
+    }
+  }
+}
+```
+
+Replace `YOUR_VAL_TOWN_TOKEN_HERE` with your actual ValTown API token.
+
+### Local Installation
+
+If you prefer to run the server locally, you can use the following methods:
+
 ### Claude Desktop
 
 #### Windows Configuration

config.ts

@@ -1,42 +1,60 @@
 import {config as dotenvConfig} from "https://deno.land/x/dotenv@v3.2.2/mod.ts"
 import * as path from "jsr:@std/path"
 import {getCliAvailability} from "./lib/vtCli.ts"
-export async function loadConfig() {
-    dotenvConfig({export: true})
+export async function loadConfig(remoteMode = false) {
+  if (remoteMode) {
+    // For remote: expect token in request headers, use local prompt file
+    return {
+      apiToken: null, // Will be set from headers
+      apiBase: "https://api.val.town",
+      cli: {
+        preferCli: false,
+        path: "vt",
+      },
+      prompts: {
+        valleyPath: `${import.meta.dirname}/prompts/valley.txt`, // Use local file in deployment
+        defaultValleyPath: `${import.meta.dirname}/prompts/valley.txt`,
+      },
+    };
+  }
 
-    const API_TOKEN = Deno.env.get("VAL_TOWN_API_TOKEN")
-    if (!API_TOKEN) {
-        console.error("Error: VAL_TOWN_API_TOKEN environment variable is required")
-        Deno.exit(1)
-    }
+  // Existing local config logic
+  dotenvConfig({ export: true });
 
-    // CLI preference configuration
-    const PREFER_CLI = Deno.env.get("VAL_TOWN_PREFER_CLI") !== "false" // Default to true
-    const CLI_PATH = Deno.env.get("VAL_TOWN_CLI_PATH") || "vt" // Default to "vt" in PATH
-    // Prompt file paths (can be absolute or relative to CWD)
-    const VALLEY_PROMPT_PATH = Deno.env.get("VALLEY_PROMPT_PATH")
-    const useCliIfAvailable = PREFER_CLI ?? false
-    const cliAvailable = useCliIfAvailable && await getCliAvailability(CLI_PATH)
-    const defaultPromptPath = `${import.meta.dirname}/prompts/${cliAvailable ? "valley.txt" : "valley_local.txt"}`
+  const API_TOKEN = Deno.env.get("VAL_TOWN_API_TOKEN");
+  if (!API_TOKEN) {
+    console.error("Error: VAL_TOWN_API_TOKEN environment variable is required");
+    Deno.exit(1);
+  }
 
+  // CLI preference configuration
+  const PREFER_CLI = Deno.env.get("VAL_TOWN_PREFER_CLI") !== "false"; // Default to true
+  const CLI_PATH = Deno.env.get("VAL_TOWN_CLI_PATH") || "vt"; // Default to "vt" in PATH
+  // Prompt file paths (can be absolute or relative to CWD)
+  const VALLEY_PROMPT_PATH = Deno.env.get("VALLEY_PROMPT_PATH");
+  const useCliIfAvailable = PREFER_CLI ?? false;
+  const cliAvailable = useCliIfAvailable && await getCliAvailability();
+  const defaultPromptPath = `${import.meta.dirname}/prompts/${
+    cliAvailable ? "valley.txt" : "valley_local.txt"
+  }`;
 
-    // Resolve paths relative to the current working directory if they're not absolute
-    const resolvedValleyPath = VALLEY_PROMPT_PATH
-        ? (path.isAbsolute(VALLEY_PROMPT_PATH)
-            ? VALLEY_PROMPT_PATH
-            : defaultPromptPath)
-        : undefined
-    return {
-        apiToken: API_TOKEN,
-        apiBase: "https://api.val.town",
-        cli: {
-            preferCli: PREFER_CLI,
-            path: CLI_PATH,
-        },
-        prompts: {
-            valleyPath: resolvedValleyPath,
-            // Default paths included with the binary
-            defaultValleyPath: defaultPromptPath
-        }
-    }
+  // Resolve paths relative to the current working directory if they're not absolute
+  const resolvedValleyPath = VALLEY_PROMPT_PATH
+    ? (path.isAbsolute(VALLEY_PROMPT_PATH)
+      ? VALLEY_PROMPT_PATH
+      : defaultPromptPath)
+    : undefined;
+  return {
+    apiToken: API_TOKEN,
+    apiBase: "https://api.val.town",
+    cli: {
+      preferCli: PREFER_CLI,
+      path: CLI_PATH,
+    },
+    prompts: {
+      valleyPath: resolvedValleyPath,
+      // Default paths included with the binary
+      defaultValleyPath: defaultPromptPath,
+    },
+  };
 }

deno.json

@@ -6,10 +6,5 @@
     "build:linux": "deno compile --output build/valtown-mcp-linux --include prompts/valley.txt --include prompts/valley_local.txt --target x86_64-unknown-linux-gnu --allow-net --allow-env --allow-read mod.ts",
     "build:windows": "deno compile --output build/valtown-mcp-windows.exe --include prompts/valley.txt --include prompts/valley_local.txt --target x86_64-pc-windows-msvc --allow-net --allow-env --allow-read mod.ts",
     "build:macos": "deno compile --output build/valtown-mcp-macos --include prompts/valley.txt --include prompts/valley_local.txt --target x86_64-apple-darwin --allow-net --allow-env --allow-read mod.ts"
-  },
-  "imports": {
-    "zod": "npm:zod",
-    "@modelcontextprotocol/sdk/server": "npm:@modelcontextprotocol/sdk/server",
-    "@modelcontextprotocol/sdk": "npm:@modelcontextprotocol/sdk"
   }
 }