{"_id":"@bouroo/ollama-cloud-mcp","_rev":"2-0e1a197eb4eea890860538f97999557a","name":"@bouroo/ollama-cloud-mcp","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@bouroo/ollama-cloud-mcp","version":"0.1.0","keywords":["mcp","modelcontextprotocol","ollama","web-search","web-fetch"],"author":{"name":"Kawin Viriyaprasopsook","email":"kawin.v@kkumail.com"},"license":"MIT","_id":"@bouroo/ollama-cloud-mcp@0.1.0","maintainers":[{"name":"bouroo","email":"bouroo@gmail.com"}],"homepage":"https://github.com/bouroo/ollama-cloud-mcp#readme","bugs":{"url":"https://github.com/bouroo/ollama-cloud-mcp/issues"},"bin":{"ollama-cloud-mcp":"dist/index.js"},"dist":{"shasum":"b3d16dd787fbd10ea270b465a485f946573238e6","tarball":"https://registry.npmjs.org/@bouroo/ollama-cloud-mcp/-/ollama-cloud-mcp-0.1.0.tgz","fileCount":4,"integrity":"sha512-fbryxtnZvw67bcERvvRkpWmF3U4apzQDvR7316gJnHcSPsxSPldO0FEWIKKiR+p5ko8bfyyXsMRTdiFAjjDrUw==","signatures":[{"sig":"MEQCICoNI09T6geijV8k+LkPlcAKln9znS3v0EI1YqYtJk9aAiBppo99sLd3fGV2Cg50vMXmEpsAnytuRGMXNw9IFelTQA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1233478},"type":"module","gitHead":"2425e856f207250e510d6c6d4805bb6f4e1b32a7","scripts":{"test":"bun test","build":"bun build src/index.ts --target=node --outdir=dist --format=esm","smoke":"node scripts/smoke.mjs","prepack":"bun run typecheck && bun run test && bun run build","typecheck":"tsc --noEmit"},"_npmUser":{"name":"bouroo","email":"bouroo@gmail.com"},"repository":{"url":"git+https://github.com/bouroo/ollama-cloud-mcp.git","type":"git"},"_npmVersion":"11.19.1","description":"MCP server exposing Ollama's web_search and web_fetch capabilities over stdio.","directories":{},"_nodeVersion":"26.8.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"zod":"^4.6.2","@types/bun":"^1.4.2","typescript":"^7.0.2","@types/node":"^22.20.2","@modelcontextprotocol/sdk":"^1.30.0"},"_npmOperationalInternal":{"tmp":"tmp/ollama-cloud-mcp_0.1.0_1789232018634_0.15249555912234114","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"_id":"@bouroo/ollama-cloud-mcp@0.1.1","bin":{"ollama-cloud-mcp":"dist/index.js"},"bugs":{"url":"https://github.com/bouroo/ollama-cloud-mcp/issues"},"dist":{"shasum":"7db9a331438abea5e0f226d98a4703d4d1577448","tarball":"https://registry.npmjs.org/@bouroo/ollama-cloud-mcp/-/ollama-cloud-mcp-0.1.1.tgz","integrity":"sha512-xTKaDViQB8ZZhFE9LmijE72vphS3eC9X2F7L4yQ2Yz95z2BsxCBl8X+wQPLcw7RNLut6FvYClKdOw8rwugKWJw==","fileCount":4,"unpackedSize":750900,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@bouroo%2follama-cloud-mcp@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD1iBfE6IpKweug6uxhPCd224XJcGSyfTl9wHnpiXZVUgIgK72auI8xlG0eRVo1IvlNydnGhr4M90nM3N2TiWGlQbk="}]},"name":"@bouroo/ollama-cloud-mcp","type":"module","author":{"name":"Kawin Viriyaprasopsook","email":"kawin.v@kkumail.com"},"gitHead":"ac788b3e49e72def14b8a3ec2483717893d25f51","license":"MIT","scripts":{"test":"bun test","build":"bun build src/index.ts --target=node --outdir=dist --format=esm","smoke":"node scripts/smoke.mjs","prepack":"bun run typecheck && bun run test && bun run build","typecheck":"tsc --noEmit"},"version":"0.1.1","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:53946b84-bbeb-411c-b4be-8abf728249a4"},"approver":{"name":"bouroo","email":"bouroo@gmail.com"}},"homepage":"https://github.com/bouroo/ollama-cloud-mcp#readme","keywords":["mcp","modelcontextprotocol","ollama","web-search","web-fetch"],"repository":{"url":"git+https://github.com/bouroo/ollama-cloud-mcp.git","type":"git"},"_npmVersion":"12.0.2","description":"MCP server exposing Ollama's web_search and web_fetch capabilities over stdio.","directories":{},"maintainers":[{"name":"bouroo","email":"bouroo@gmail.com"}],"_nodeVersion":"24.20.0","publishConfig":{"access":"public"},"devDependencies":{"zod":"^4.6.2","@types/bun":"^1.4.2","typescript":"^7.0.2","@types/node":"^22.20.2","@modelcontextprotocol/sdk":"^1.30.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ollama-cloud-mcp_0.1.1_1789380385598_0.09790684918258052"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-12T16:53:38.474Z","modified":"2026-09-14T10:06:25.968Z","0.1.0":"2026-09-12T16:53:38.817Z","0.1.1":"2026-09-14T10:06:25.690Z"},"bugs":{"url":"https://github.com/bouroo/ollama-cloud-mcp/issues"},"author":{"name":"Kawin Viriyaprasopsook","email":"kawin.v@kkumail.com"},"license":"MIT","homepage":"https://github.com/bouroo/ollama-cloud-mcp#readme","keywords":["mcp","modelcontextprotocol","ollama","web-search","web-fetch"],"repository":{"url":"git+https://github.com/bouroo/ollama-cloud-mcp.git","type":"git"},"description":"MCP server exposing Ollama's web_search and web_fetch capabilities over stdio.","maintainers":[{"name":"bouroo","email":"bouroo@gmail.com"}],"readme":"# @bouroo/ollama-cloud-mcp\n\n[![npm version](https://img.shields.io/npm/v/@bouroo/ollama-cloud-mcp.svg)](https://www.npmjs.com/package/@bouroo/ollama-cloud-mcp)\n[![downloads](https://img.shields.io/npm/dm/@bouroo/ollama-cloud-mcp.svg)](https://www.npmjs.com/package/@bouroo/ollama-cloud-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)\n[![CI](https://github.com/bouroo/ollama-cloud-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/bouroo/ollama-cloud-mcp/actions/workflows/ci.yml)\n\nAn [MCP](https://modelcontextprotocol.io) server that exposes [Ollama's web search and web fetch](https://docs.ollama.com/capabilities/web-search) capabilities as two tools — `web_search` and `web_fetch` — over stdio.\n\n## Contents\n\n- [Features](#features)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Usage](#usage)\n- [API](#api)\n  - [`web_search`](#web_search)\n  - [`web_fetch`](#web_fetch)\n- [Configuration](#configuration)\n- [Behaviour notes](#behaviour-notes)\n- [Project structure](#project-structure)\n- [Development](#development)\n- [Continuous integration](#continuous-integration)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Features\n\n- **Two tools, one server** — `web_search` for ranked results, `web_fetch` for a single page's content, over stdio.\n- **Self-contained bundle** — no runtime dependencies, so `npx` runs it with nothing to install. CI proves it by handshaking against the built file alone in an empty directory.\n- **Hosted or local** — authenticates against `https://ollama.com` with an API key, or points `OLLAMA_HOST` at a signed-in local daemon and needs no key at all.\n- **Errors stay errors** — a missing key, a rejected key, rate limiting or a server error is returned as a tool error the model can explain, instead of taking down the server.\n- **Protocol-clean** — stdout carries only the MCP stream; diagnostics go to stderr.\n\n## Requirements\n\n- **Node.js** — the current Active LTS. CI tracks `lts/*`, and no `engines` floor is declared, so no version is claimed that CI does not actually test.\n- **An Ollama API key** for the hosted API — free, from <https://ollama.com/settings/keys>. Alternatively, point `OLLAMA_HOST` at a signed-in local daemon (see [Configuration](#configuration)).\n\n## Installation\n\nThere is no install step: `npx` fetches and runs the published package, which ships as a single self-contained bundle with no runtime dependencies.\n\n```bash\nnpx -y @bouroo/ollama-cloud-mcp --help\n```\n\n## Usage\n\nRegister the server with your MCP client.\n\n**Claude Code**\n\n```bash\nclaude mcp add ollama-cloud --env OLLAMA_API_KEY=your-key-here -- npx -y @bouroo/ollama-cloud-mcp\n```\n\n**Claude Desktop / other clients** — add this to `claude_desktop_config.json` or the equivalent `mcpServers` block:\n\n```json\n{\n  \"mcpServers\": {\n    \"ollama-cloud\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bouroo/ollama-cloud-mcp\"],\n      \"env\": { \"OLLAMA_API_KEY\": \"your-key-here\" }\n    }\n  }\n}\n```\n\nOnce registered, the client discovers both tools and can call them.\n\n## API\n\n### `web_search`\n\nSearch the web and return ranked results. Use it for information beyond the model's training cutoff: news, releases, prices, current documentation.\n\n| Argument | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `query` | string | yes | The search term, e.g. `\"what is ollama?\"` |\n| `max_results` | integer | no | 1–10. Defaults to `5`. |\n\nReturns `structuredContent.results` — an array of `{ title, url, content }` — plus a readable text rendering:\n\n```\nWeb search results for \"what is ollama?\" (2):\n\n[1] Ollama\nURL: https://ollama.com/\nCloud models are now available in Ollama...\n\n[2] What is Ollama? Introduction to the AI model management tool\nURL: https://www.hostinger.com/tutorials/what-is-ollama\nAn introduction to running and managing local models...\n```\n\n### `web_fetch`\n\nFetch a single page and return its content. Use it after `web_search` to read a promising result in full.\n\n| Argument | Type | Required | Notes |\n| --- | --- | --- | --- |\n| `url` | string | yes | May omit the scheme: `\"ollama.com\"` becomes `https://ollama.com/`. Only `http` and `https` are accepted. |\n\nReturns `structuredContent` — `{ title, content, links }` — plus a readable text rendering:\n\n```\nFetched ollama.com\nTitle: Ollama\n\nCloud models are now available in Ollama...\n\nLinks (2):\n- http://ollama.com/\n- https://github.com/ollama/ollama\n```\n\n## Configuration\n\n| Variable | Required | Default | Description |\n| --- | --- | --- | --- |\n| `OLLAMA_API_KEY` | For the hosted API | — | Bearer token for `https://ollama.com`. |\n| `OLLAMA_HOST` | No | `https://ollama.com` | Override the API base URL. A bare `host:port` is treated as `http://`, matching Ollama's own convention — e.g. `OLLAMA_HOST=127.0.0.1:11434` talks to a local daemon instead. |\n\nPointing `OLLAMA_HOST` at a local, signed-in Ollama daemon is supported and needs no API key: the daemon handles its own authentication. If `OLLAMA_API_KEY` is set, it is always sent.\n\n## Behaviour notes\n\n- **Errors are returned as tool errors, not crashes.** A missing key, a rejected key (HTTP 401/403), rate limiting (429) or a server error (5xx) comes back as `isError: true` with a message naming the cause, so the model can explain it instead of the client losing the server.\n- **An empty result set is not an error** — `web_search` reports `No web results found for \"<query>\".`\n- **Requests time out after 30 seconds** rather than hanging the tool call.\n- **stdout carries only the MCP protocol stream.** All diagnostics go to stderr.\n- Ollama's docs suggest a context length of at least ~32,000 tokens when feeding fetched pages to a model; `web_fetch` returns page content verbatim and does not truncate it.\n\n## Project structure\n\n```\nsrc/\n  index.ts                       composition root: CLI entry (stdio, --help, --version)\n  domain/                        pure model — types, constants, pure rules\n    errors.ts                    OllamaWebError and the missing-key message\n    config.ts                    OllamaConfig, base-URL normalization and resolution\n    web.ts                       response types, URL and max-results normalization\n  interfaces/OllamaWebPort.ts    the outbound contract the use cases depend on\n  usecases/                      application logic\n    searchWeb.ts                 validate, clamp, call the port, parse the response\n    fetchPage.ts                 normalize the url, call the port, parse the response\n    parseResponses.ts            shape raw payloads into the response types\n  adapters/                      implementations that touch the outside world\n    OllamaWebClient.ts           fetch transport: auth, timeout, status mapping\n    McpServer.ts                 tool registration, schemas, text formatting\ntest/\n  domain/config.test.ts          config resolution and base-URL normalization\n  domain/web.test.ts             target-URL and max-results normalization\n  usecases/webOperations.test.ts the use cases driven through a stub port\n  adapters/OllamaWebClient.test.ts  transport, auth and error mapping\n  adapters/McpServer.test.ts     in-memory MCP protocol tests\n  helpers.ts                     shared fakes\nscripts/smoke.mjs                end-to-end stdio smoke test\n```\n\n`test/` mirrors the `src/` layers. The `OllamaWebPort` seam keeps `usecases/` independent of any concrete HTTP client — `OllamaWebClient` implements it, and the use-case tests exercise it with a stub.\n\n## Development\n\nRequires [Bun](https://bun.sh) for the toolchain; the published artifact runs on plain Node.\n\n```bash\nbun install\nbun run typecheck   # tsc --noEmit\nbun run test        # unit + in-memory MCP protocol tests\nbun run build       # bundles src/index.ts -> dist/index.js\nbun run smoke       # end-to-end stdio handshake against dist/\n\n# With a key, exercise the live API as well:\nOLLAMA_API_KEY=... node scripts/smoke.mjs \"what is ollama?\"\n```\n\n`bun run smoke` drives the built server over real stdio: it performs the MCP initialize handshake, lists tools, and calls `web_search`. Without `OLLAMA_API_KEY` it asserts the missing-key error path instead, which still proves the request wiring end to end.\n\n## Continuous integration\n\n`.github/workflows/ci.yml` runs on every push to `main` and every pull request, on the current Active LTS (`lts/*`):\n\n- type-check, test, build\n- drive a **full MCP handshake against a copy of the built bundle sitting alone in an empty directory**, with no `node_modules` to fall back on — this is what makes the \"zero runtime dependencies\" claim tested rather than asserted\n- the same handshake against the source build\n\n## Contributing\n\n1. Fork the repository.\n2. Create a branch: `git checkout -b feat/your-feature`.\n3. Commit your changes following [Conventional Commits](https://www.conventionalcommits.org/): `git commit -m \"feat: add …\"`.\n4. Push to the branch: `git push origin feat/your-feature`.\n5. Open a pull request.\n\nPlease add tests for any behaviour change and make sure `bun run typecheck`, `bun run test` and `bun run smoke` pass.\n\n## License\n\nMIT © [Kawin Viriyaprasopsook](https://github.com/bouroo)\n","readmeFilename":"README.md"}