{"id":50747145,"url":"https://github.com/arashsheyda/nuxt-volcano","last_synced_at":"2026-06-10T22:01:55.347Z","repository":{"id":361082594,"uuid":"1253017922","full_name":"arashsheyda/nuxt-volcano","owner":"arashsheyda","description":"🌋 Nuxt module for Volcano Agent SDK - build AI agents with LLM reasoning and MCP tools","archived":false,"fork":false,"pushed_at":"2026-05-29T06:47:39.000Z","size":345,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T07:08:37.172Z","etag":null,"topics":["agent","nuxt","volcano"],"latest_commit_sha":null,"homepage":"https://npmx.dev/package/nuxt-volcano","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arashsheyda.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-29T04:48:50.000Z","updated_at":"2026-05-29T06:48:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/arashsheyda/nuxt-volcano","commit_stats":null,"previous_names":["arashsheyda/nuxt-volcano"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/arashsheyda/nuxt-volcano","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arashsheyda%2Fnuxt-volcano","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arashsheyda%2Fnuxt-volcano/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arashsheyda%2Fnuxt-volcano/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arashsheyda%2Fnuxt-volcano/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arashsheyda","download_url":"https://codeload.github.com/arashsheyda/nuxt-volcano/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arashsheyda%2Fnuxt-volcano/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34172196,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","nuxt","volcano"],"created_at":"2026-06-10T22:01:55.125Z","updated_at":"2026-06-10T22:01:55.342Z","avatar_url":"https://github.com/arashsheyda.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://volcano.dev\"\u003e\n    \u003cimg src=\"https://www.volcano.dev/volcano__icn.png\" alt=\"Volcano\" width=\"80\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003enuxt-volcano\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\nNuxt module for the \u003ca href=\"https://www.volcano.dev/\"\u003eVolcano Agent SDK\u003c/a\u003e — build AI agents that combine LLM reasoning with real-world actions via MCP tools.\n\u003c/p\u003e\n\n## Features\n\n- 🔒 **Server-side only**: API keys stay safe in runtime config\n- 🔌 **Auto-imports**: `useVolcanoAgent()`, `useVolcanoLLM()`, `agent()`, and `mcp()` available in server routes\n- 💬 **Client composable**: `useVolcanoChat()` for building chat UIs with streaming support\n- 🌊 **SSE streaming**: `defineVolcanoStreamHandler()` streams tokens to the browser in real-time\n- 🤖 **Multi-provider**: OpenAI, Anthropic, Mistral, Llama, Bedrock, Vertex, Azure\n- ⚡ **Zero config**: set an API key env var and go\n\n## Quick Setup\n\nInstall the module:\n\n```bash\nnpx nuxi module add nuxt-volcano\n```\n\nAdd to `nuxt.config.ts`:\n\n```ts\nexport default defineNuxtConfig({\n  modules: ['nuxt-volcano'],\n  volcano: {\n    defaultProvider: 'openai',\n    defaultModel: 'gpt-4o-mini',\n  },\n})\n```\n\nSet your API key via environment variable:\n\n```bash\nNUXT_VOLCANO_OPENAI_API_KEY=sk-...\n```\n\n## Usage\n\n### Server API Route\n\n```ts\n// server/api/agent.post.ts\nexport default defineEventHandler(async (event) =\u003e {\n  const { prompt } = await readBody(event)\n\n  const myAgent = useVolcanoAgent()\n\n  const results = await myAgent\n    .then({ prompt })\n    .run()\n\n  return { output: results[0]?.llmOutput }\n})\n```\n\n### With MCP Tools\n\n```ts\n// server/api/research.post.ts\nexport default defineEventHandler(async (event) =\u003e {\n  const { prompt } = await readBody(event)\n\n  const myAgent = useVolcanoAgent()\n  const webTools = mcp('http://localhost:3211/mcp')\n\n  const results = await myAgent\n    .then({ prompt, mcps: [webTools] })\n    .then({ prompt: 'Summarize the findings.' })\n    .run()\n\n  return { output: results.at(-1)?.llmOutput }\n})\n```\n\n### Using a Different Provider Per-Request\n\n```ts\nconst agent = useVolcanoAgent({ provider: 'anthropic', model: 'claude-3-5-sonnet-20241022' })\n```\n\n### Direct LLM Access\n\n```ts\nconst llm = useVolcanoLLM({ provider: 'openai', model: 'gpt-4o' })\nconst response = await llm.gen('Hello!')\n```\n\n## Client-Side\n\n### `useVolcanoChat()` Chat UI Composable\n\nA Vue composable for building chat interfaces with optional SSE streaming:\n\n```vue\n\u003cscript setup\u003e\nconst { messages, input, isLoading, error, send, stop, clear } = useVolcanoChat({\n  api: '/api/chat',\n  stream: true, // Enable real-time token streaming\n  onToken: (token) =\u003e console.log(token),\n  onFinish: (msg) =\u003e console.log('Done:', msg.content),\n})\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cdiv v-for=\"msg in messages\" :key=\"msg.content\"\u003e\n    \u003cstrong\u003e{{ msg.role }}:\u003c/strong\u003e {{ msg.content }}\n  \u003c/div\u003e\n  \u003cform @submit.prevent=\"send()\"\u003e\n    \u003cinput v-model=\"input\" placeholder=\"Type a message...\" /\u003e\n    \u003cbutton v-if=\"!isLoading\" type=\"submit\"\u003eSend\u003c/button\u003e\n    \u003cbutton v-else type=\"button\" @click=\"stop()\"\u003eStop\u003c/button\u003e\n  \u003c/form\u003e\n\u003c/template\u003e\n```\n\n#### Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `api` | `string` | `'/api/agent'` | Server endpoint URL |\n| `stream` | `boolean` | `false` | Enable SSE token streaming |\n| `initialMessages` | `ChatMessage[]` | `[]` | Pre-populate chat history |\n| `body` | `object` | -- | Extra fields sent with every request |\n| `headers` | `object` | -- | Extra headers sent with every request |\n| `onToken` | `(token: string) =\u003e void` | -- | Callback per streamed token |\n| `onFinish` | `(msg: ChatMessage) =\u003e void` | -- | Callback when response completes |\n| `onError` | `(err: Error) =\u003e void` | -- | Callback on error |\n\n#### Return Value\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `messages` | `Ref\u003cChatMessage[]\u003e` | Reactive message history |\n| `input` | `Ref\u003cstring\u003e` | Bound to your text input |\n| `isLoading` | `Ref\u003cboolean\u003e` | True while waiting for a response |\n| `error` | `Ref\u003cError \\| null\u003e` | Last error, if any |\n| `send(content?)` | `(string?) =\u003e Promise` | Send a message (uses `input` if no arg) |\n| `stop()` | `() =\u003e void` | Abort the current request |\n| `clear()` | `() =\u003e void` | Reset messages to initial state |\n| `setMessages()` | `(msgs) =\u003e void` | Replace message history |\n\n### `defineVolcanoStreamHandler()` SSE Server Endpoint\n\nA server utility that creates an endpoint supporting both JSON and SSE streaming.\nAutomatically detects the `Accept: text/event-stream` header:\n\n```ts\n// server/api/chat.post.ts\nexport default defineVolcanoStreamHandler({\n  async handler(event, { prompt, onToken }) {\n    const myAgent = useVolcanoAgent()\n    const results = await myAgent\n      .then({ prompt, onToken })\n      .run()\n    return results[0]?.llmOutput ?? ''\n  },\n})\n```\n\n- **With `stream: true`** on the client → SSE response, tokens arrive in real-time\n- **Without streaming** (regular `$fetch`) → JSON response `{ output: \"...\" }`\n\n## Configuration\n\n### Module Options (`nuxt.config.ts`)\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `defaultProvider` | `string` | `'openai'` | Default LLM provider |\n| `defaultModel` | `string` | -- | Default model identifier |\n| `instructions` | `string` | -- | Global system instructions |\n| `timeout` | `number` | `60` | Default step timeout (seconds) |\n| `retry` | `RetryConfig` | -- | Retry configuration |\n| `contextMaxChars` | `number` | `20480` | Context size limit |\n| `contextMaxToolResults` | `number` | `8` | Tool results in context |\n| `maxToolIterations` | `number` | `4` | Max tool calls per step |\n| `disableParallelToolExecution` | `boolean` | `false` | Force sequential tool execution |\n| `hideProgress` | `boolean` | `false` | Suppress progress output |\n\n### Environment Variables\n\nAPI keys are set via `NUXT_VOLCANO_*` environment variables:\n\n| Variable | Provider |\n|----------|----------|\n| `NUXT_VOLCANO_OPENAI_API_KEY` | OpenAI |\n| `NUXT_VOLCANO_ANTHROPIC_API_KEY` | Anthropic |\n| `NUXT_VOLCANO_MISTRAL_API_KEY` | Mistral |\n| `NUXT_VOLCANO_VERTEX_API_KEY` | Google Vertex |\n| `NUXT_VOLCANO_AZURE_API_KEY` | Azure AI |\n| `NUXT_VOLCANO_AZURE_ENDPOINT` | Azure AI endpoint |\n| `NUXT_VOLCANO_BEDROCK_ACCESS_KEY_ID` | AWS Bedrock |\n| `NUXT_VOLCANO_BEDROCK_SECRET_ACCESS_KEY` | AWS Bedrock |\n| `NUXT_VOLCANO_BEDROCK_REGION` | AWS Bedrock region |\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Develop with the playground\npnpm dev\n\n# Run tests\npnpm test\n\n# Build the module\npnpm prepack\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farashsheyda%2Fnuxt-volcano","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farashsheyda%2Fnuxt-volcano","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farashsheyda%2Fnuxt-volcano/lists"}