@grumppie/ownsearch 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# ownsearch
+
+**ownsearch** is a local search layer for agents.
+
+It indexes approved folders into a local Qdrant vector store, exposes retrieval through an MCP server, and gives agents grounded access to private knowledge without requiring a hosted search service.
+
+V1 is intentionally text-first: reliable local retrieval for documentation, code, and extracted PDF text. Future versions are intended to expand into multimodal indexing and search for images, audio, video, and richer document workflows.
+
+## What it does
+
+- Indexes local folders into a persistent vector store
+- Chunks and embeds supported files with Gemini
+- Supports incremental reindexing for changed and deleted files
+- Exposes search and context retrieval through MCP
+- Lets agents retrieve ranked hits, exact chunks, or bundled grounded context
+
+## V1 scope
+
+- text and code files
+- extracted text from PDFs
+- Gemini `gemini-embedding-001`
+- Docker-backed Qdrant
+- stdio MCP server for local agent attachment
+
+## Quickstart
+
+Install `ownsearch` globally:
+
+```bash
+npm install -g @grumppie/ownsearch
+```
+
+Set it up, index a folder, and start searching:
+
+```bash
+ownsearch setup
+ownsearch doctor
+ownsearch index ./docs --name docs
+ownsearch list-roots
+ownsearch search "what is this repo about?" --limit 5
+ownsearch search-context "what is this repo about?" --limit 8 --max-chars 12000
+ownsearch serve-mcp
+```
+
+On first run, `ownsearch setup` can prompt for `GEMINI_API_KEY` and save it to `~/.ownsearch/.env`, which is then reused automatically by later CLI and MCP runs.
+
+The installed binary remains `ownsearch`, so the scoped package name only affects installation and `npx` usage.
+
+To connect `ownsearch` to a supported agent, print a config snippet for your client:
+
+```bash
+ownsearch print-agent-config codex
+ownsearch print-agent-config claude-desktop
+ownsearch print-agent-config cursor
+```
+
+## Local development
+
+If you want to run `ownsearch` from source while developing locally:
+
+```bash
+npm install
+npm run build
+node dist/cli.js setup
+node dist/cli.js index ./docs --name docs
+node dist/cli.js search "what is this repo about?" --limit 5
+node dist/cli.js serve-mcp
+```
+
+## CLI commands
+
+- `ownsearch setup`
+  Starts or reconnects to the local Qdrant Docker container, creates local config, and can save `GEMINI_API_KEY` into `~/.ownsearch/.env`.
+- `ownsearch doctor`
+  Checks config, Gemini key presence, Qdrant connectivity, and active collection settings.
+- `ownsearch index <folder> --name <name>`
+  Indexes a folder incrementally into the local vector collection.
+- `ownsearch list-roots`
+  Lists approved indexed roots.
+- `ownsearch search "<query>"`
+  Returns ranked search hits from the vector store.
+- `ownsearch search-context "<query>"`
+  Returns a compact grounded context bundle for agents.
+- `ownsearch delete-root <rootId>`
+  Removes a root from config and deletes its vectors from Qdrant.
+- `ownsearch store-status`
+  Shows collection status and vector configuration.
+- `ownsearch serve-mcp`
+  Starts the stdio MCP server.
+- `ownsearch print-agent-config <agent>`
+  Prints an MCP config snippet for supported agents.
+
+## MCP tools
+
+The MCP server currently exposes:
+
+- `index_path`
+- `search`
+- `search_context`
+- `get_chunks`
+- `list_roots`
+- `delete_root`
+- `store_status`
+
+Recommended agent flow:
+
+1. Call `search_context` for fast grounded retrieval.
+2. If more precision is needed, call `search`.
+3. Use `get_chunks` on selected hit IDs for exact source text.
+
+## Notes
+
+- Config is stored in `~/.ownsearch/config.json`
+- Shared CLI and MCP secrets can be stored in `~/.ownsearch/.env`
+- Qdrant runs locally in Docker as `ownsearch-qdrant`
+- `GEMINI_API_KEY` may come from the shell environment, the current working directory `.env`, or `~/.ownsearch/.env`
+- Node.js `20+` is required
+
+## Roadmap
+
+Planned after the text-first v1:
+
+- richer document extraction
+- better reranking and deduplication
+- watch mode for automatic reindexing
+- HTTP MCP transport
+- multimodal indexing and search for:
+  - images
+  - audio
+  - video
+  - richer document formats
+
+The multimodal phase will require careful collection migration because Gemini text and multimodal embedding spaces are not interchangeable across model families.
+
+## License
+
+MIT