{
"markdown": "# DocsMint\n\n**Turn your documents into knowledge you and your AI agents can use.**\n\nWrite and organize notes, guides, and project documentation in one workspace.\nFind answers with search that understands related concepts, then give your\nagents access to the same documents through MCP, REST, the SDK, or CLI.\n\n**[Try managed DocsMint](https://docsmint.com)** to get started without\noperating the stack, or **[self-host with Docker](#quickstart)** to run the\nApache-2.0 application on your own infrastructure.\n\n[](LICENSE)\n[](https://github.com/hiai-gg/docsmint/releases)\n[](https://www.npmjs.com/package/@hiai-gg/docsmint)\n[](https://hub.docker.com/r/vgalibov/docsmint)\n[](https://github.com/hiai-gg/docsmint/stargazers)\n[](https://github.com/hiai-gg/docsmint/actions/workflows/ci.yml)\n[](https://bun.sh)\n[](https://www.typescriptlang.org)\n[](https://svelte.dev)\n[](https://elysiajs.com)\n[](https://tailwindcss.com)\n[](https://orm.drizzle.team)\n[](CONTRIBUTING.md)\n[](https://lobehub.com/mcp/hiai-gg-docsmint)\n\n[GitHub](https://github.com/HiAi-gg/docsmint) ·\n[Docker Hub](https://hub.docker.com/r/vgalibov/docsmint) ·\n[npm](https://www.npmjs.com/package/@hiai-gg/docsmint) ·\n[LobeHub MCP](https://lobehub.com/mcp/hiai-gg-docsmint)\n\n![\"DocsMint](\"https://github.com/user-attachments/assets/94701d01-a361-4ca1-b16d-de2a0c64d684\")
\n\n## Why DocsMint?\n\n- **Keep knowledge easy to edit.** Use a rich visual editor or Markdown;\n organize documents with folders, categories, and tags.\n- **Find the document you mean.** Search combines keywords, meaning, typo\n tolerance, and graph relationships across languages.\n- **Keep agents close to the source.** Let your tools search, read, and update\n the same knowledge through MCP, REST, a typed SDK, and CLI.\n- **Choose what an integration can access.** Category keys grant explicit\n `read`, `edit`, and `write` permissions for a defined part of your library.\n- **Keep retrieval up to date.** Document edits and metadata changes refresh\n the search index automatically in the background.\n- **Choose how you run it.** Use [managed DocsMint](https://docsmint.com) or\n self-host the application, database, search, queues, and files.\n\n## What's new in 0.8.3?\n\nThis maintenance release focuses on reliable saves and integrations:\n\n- Pending editor saves stay attached to the document being edited, even when\n you switch documents.\n- Navigation waits for pending content saves; overlapping saves are serialized\n so an older request cannot overwrite a newer edit.\n- SDK document creation retries reuse an idempotency key to prevent duplicates\n after a lost response.\n- Workspace-wide tag management requires full write access; read-only and\n category-scoped credentials can no longer mutate the entire tag collection.\n- Partial category API-setting updates preserve omitted permissions.\n- Public workspace share links retain their workspace context when loading\n folders and documents.\n\nNo schema migration is added. Existing public request and response shapes\nremain supported; the tag authorization fix intentionally rejects operations\nthat exceeded the caller's permissions.\n\nRead the complete release history in the [changelog](CHANGELOG.md) or\n[GitHub Releases](https://github.com/HiAi-gg/docsmint/releases). See the\n[roadmap](docs/ROADMAP.md) for what comes next.\n\n## Install with an AI agent\n\nPrefer an assisted self-hosted setup? Give your coding agent this prompt.\nYou will need Docker and a choice of AI provider.\n\n```text\nInstall DocsMint from https://github.com/HiAi-gg/docsmint.\nVerify Docker and Docker Compose v2, clone the repository, and run\n`bash scripts/quickstart.sh`. Do not print or commit .env. Ask me to enter only\nan OpenRouter key or select Ollama, then run quickstart again. Verify\nhttp://localhost:50701, http://localhost:50700/api/health, and\n`docker compose ps`. Do not replace Bun, rewrite migrations, disable GraphRAG,\nor delete volumes.\n```\n\nAfter startup, open **http://localhost:50701** and create the first account.\nFor manual installation, use the Docker quickstart below.\n\n## Quickstart\n\n### Requirements\n\n- Docker Engine or Docker Desktop\n- Docker Compose v2\n- One of:\n - an [OpenRouter](https://openrouter.ai/) API key; or\n - a local [Ollama](https://ollama.com/) instance\n\n### Start with Docker\n\n```bash\ngit clone https://github.com/HiAi-gg/docsmint.git\ncd docsmint\nbash scripts/quickstart.sh\n```\n\nOn its first run, the script creates an ignored root `.env`, generates the\ndatabase, authentication, and storage secrets, builds the PostgreSQL image,\napplies migrations, and starts the complete application.\n\nPublished application images are on\n[Docker Hub](https://hub.docker.com/r/vgalibov/docsmint). There is no untagged\n`latest` image; pull the role-specific tags:\n\n```bash\ndocker pull vgalibov/docsmint:api-latest\ndocker pull vgalibov/docsmint:web-latest\ndocker pull vgalibov/docsmint:caddy-latest\n```\n\nUse versioned tags `api-v0.8.3`, `web-v0.8.3`, and `caddy-v0.8.3` for\nreproducible deploys. The quickstart still builds the Compose stack from this repository so PostgreSQL,\nRedis, and SeaweedFS start together with the application.\n\nFor OpenRouter, add one value to `.env` and run the script again:\n\n```dotenv\nOPENROUTER_API_KEY=sk-or-your-key\n```\n\nFor Ollama, select the local provider instead:\n\n```dotenv\nAI_PROVIDER=ollama\nOLLAMA_PORT=11434\n```\n\nThen make sure the configured local models are available:\n\n```bash\nollama pull bge-m3\nollama pull qwen3:8b\nbash scripts/quickstart.sh\n```\n\nOpen **http://localhost:50701**. The API health endpoint is\n**http://localhost:50700/api/health**.\n\n### First use\n\n1. Create your account in the web application.\n2. Create a category or folder and add or import a document.\n3. Wait for the document pipeline to finish chunking and embedding.\n4. Search using an exact phrase, a related concept, an alternate language, or\n a misspelling.\n5. Open **Settings → API** when you want to connect a CLI, MCP client, or\n external application.\n\nThe canonical local ports are:\n\n| Service | Port |\n| -------------------- | ------: |\n| Web application | `50701` |\n| REST API | `50700` |\n| PostgreSQL | `5437` |\n| Redis | `6384` |\n| SeaweedFS S3 gateway | `50702` |\n| SeaweedFS filer UI | `50703` |\n\nSee [Deployment](docs/DEPLOYMENT.md) for domains, TLS, provider tuning,\nbackups, and production operation.\n\nEmbedding provider URLs, models, and credentials are deployment configuration.\nThey are never stored in browser settings or local storage.\n\n## Use DocsMint from the terminal\n\nThe published package includes the CLI. It connects to an already running\nDocsMint server; installing it does not deploy the server.\n\n```bash\nbun add @hiai-gg/docsmint\n```\n\n```bash\nbunx --package @hiai-gg/docsmint docsmint init \\\n --url http://localhost:50700 \\\n --key 'your-global-or-category-key'\n\nbunx --package @hiai-gg/docsmint docsmint search \"project architecture\"\nbunx --package @hiai-gg/docsmint docsmint list\nbunx --package @hiai-gg/docsmint docsmint read \nbunx --package @hiai-gg/docsmint docsmint create \\\n --title \"Release notes\" --content \"# Highlights\"\n```\n\nCredentials can also be supplied through `HIAI_DOCS_URL` and\n`HIAI_DOCS_API_KEY`. See the [CLI guide](packages/cli/README.md) for every\ncommand and configuration precedence.\n\n## Connect an MCP client\n\nGive agents a secure path to search, read, and maintain your knowledge without\ndatabase or filesystem access. DocsMint publishes 17 tools plus ready-made\nresearch prompts, scoped resources, and a document-manager skill.\n\n### Hosted DocsMint\n\nConnect directly to the managed Streamable HTTP endpoint. Keep the API key in\nan environment variable rather than writing it into client configuration:\n\n```bash\ncodex mcp add docsmint \\\n --url https://docsmint.com/mcp \\\n --bearer-token-env-var HIAI_DOCS_API_KEY\n```\n\n### Self-hosted DocsMint\n\nRun the published stdio bridge against your own DocsMint API:\n\n```json\n{\n \"mcpServers\": {\n \"docsmint\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@hiai-gg/docsmint\", \"docsmint-mcp\"],\n \"env\": {\n \"HIAI_DOCS_URL\": \"http://localhost:50700\",\n \"HIAI_DOCS_API_KEY\": \"your-global-or-category-key\"\n }\n }\n }\n}\n```\n\nCategory keys let you expose only the documents and operations an agent needs.\nUse a global key only for trusted owner-wide automation. See the\n[complete MCP reference](packages/mcp-server/README.md) for Bun, npm, local\ncheckout, all tools, prompts, resources, permissions, and REST mappings.\n\n## TypeScript SDK\n\n```bash\nbun add @hiai-gg/docsmint\n```\n\n```ts\nimport { DocsClient } from '@hiai-gg/docsmint';\n\nconst docs = new DocsClient({\n baseUrl: 'http://localhost:50700',\n apiKey: process.env.HIAI_DOCS_API_KEY,\n});\n\nconst created = await docs.createDoc({\n title: 'Meeting notes',\n content: '# Agenda',\n});\n\nconst results = await docs.search('what did we decide?');\nconsole.log(created.id, results.items);\n```\n\nThe SDK is a typed `fetch` client with retries for transient failures and\nidempotent document creation retries. See the\n[SDK reference](packages/sdk/README.md) and [REST API](docs/API.md).\n\n## API keys and integrations\n\nCreate and revoke integration keys from **Settings → API**.\n\n| Credential | Intended use | Access |\n| -------------- | -------------------------------------------- | -------------------------------------- |\n| Global API key | Trusted owner-wide CLI, MCP, SDK, or service | All owner content |\n| Category key | Least-privilege agent or product integration | One category with selected permissions |\n| Operator key | Administration and reindex operations | `/api/admin/*` only |\n\nCategory permissions are explicit and non-hierarchical:\n\n- `read` permits list, read, search, and export;\n- `edit` permits updates to existing content, attachments, and versions;\n- `write` permits create, move, delete, share, and publish operations.\n\nCombine permissions when an integration needs more than one capability.\nAPI-key lifecycle operations require the owning browser session; an API key\ncannot create or elevate another key. Server-to-server integrations are not\naffected by browser CORS. Browser integrations must add their exact origin to\n`CORS_ORIGINS`.\n\n## What is included?\n\nDocuments use structured TipTap JSON as canonical content. Markdown is the\nsource-editing, import, and export format. The same document store serves the\nweb application and public integration interfaces.\n\n```text\nfrontend/ SvelteKit workspace and TipTap editor\nbackend/ Elysia REST API, search, workers, and authentication\npackages/db/ Drizzle schema and migrations\npackages/sdk/ Typed API client\npackages/cli/ Terminal client\npackages/mcp-server/ MCP stdio server\npostgres/ PostgreSQL image with vector and graph extensions\n```\n\nThe Docker deployment runs:\n\n- **Web** — document editor, folders, categories, sharing, settings, and search;\n- **API** — documents, attachments, versions, keys, search, and administration;\n- **PostgreSQL 18** — relational data, pgvector/pgvectorscale vectors, and the\n Apache AGE graph in one database;\n- **Redis 8** — BullMQ queues, caching, retries, and job recovery;\n- **SeaweedFS** — S3-compatible attachment storage.\n\n## How search works\n\nEvery document save schedules background work. Content is chunked, changed\nchunks are embedded, and the completed generation is activated atomically. The\nprevious valid generation remains searchable if a provider call fails.\n\nSearch combines exact title matches, multilingual lexical search, typo-tolerant\nfuzzy matching, semantic vectors, adaptive query expansion, and Apache AGE\ngraph neighbors. Reciprocal rank fusion combines the channels without allowing\none weak provider result to dominate. A cross-encoder then reranks the fused\nprefix against the original query (Voyage rerank-2.5 by default). On a labeled\n24-document corpus that moved MRR 0.969 → 1.000 and nDCG@10 0.958 → 0.986\nversus RRF-only. Rerank, expansion, embeddings, and AGE failures keep the\nremaining channels. Authorization is applied before retrieval and again before\nresults are returned.\n\nGraphRAG is part of the normal search path in the reference configuration. It\nextracts entities after embeddings are ready and finds related documents beyond\ndirect keyword or vector similarity. It degrades gracefully when an external\nmodel is unavailable.\n\nFor pipeline internals and tuning, see [Architecture](docs/ARCHITECTURE.md) and\n[Deployment](docs/DEPLOYMENT.md).\n\n## Stack\n\n- Bun 1.4.0+, TypeScript, Elysia, Zod, and Pino\n- Svelte 5, SvelteKit, Tailwind CSS, and TipTap\n- Better Auth and Drizzle ORM\n- PostgreSQL 18, pgvector, pgvectorscale, and Apache AGE\n- Redis 8 and BullMQ\n- SeaweedFS with its S3-compatible API\n- OpenAI-compatible providers through OpenRouter or local Ollama\n\n## Documentation\n\n- [Documentation index](docs/README.md)\n- [Product usage](docs/USAGE.md)\n- [Roadmap](docs/ROADMAP.md)\n- [REST API](docs/API.md) and [OpenAPI JSON](docs/openapi.json)\n- [Architecture](docs/ARCHITECTURE.md)\n- [Deployment and operations](docs/DEPLOYMENT.md)\n- [Extension points](docs/EXTENDING.md)\n- [Maintainer release flow](docs/RELEASING.md)\n- [Security policy](SECURITY.md)\n- [Changelog](CHANGELOG.md)\n\n## Development\n\nUse Bun 1.4.0 or later for local development.\n\n```bash\nbun install\nbun run lint\nbun run typecheck\nbun run test\nbun run build\n```\n\nRead [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Please\nreport vulnerabilities through [SECURITY.md](SECURITY.md), not a public issue.\n\n## License\n\nDocsMint is released under the [Apache License 2.0](LICENSE).\n\nBuilt as an independent open-source project in the\n[HiAi](https://github.com/HiAi-gg) ecosystem.\n",
"bytes": 15028,
"sha": "b39154da769efd921f0dd03382b11814d266ba5fba4e07c58099d62008e1041b",
"repo_slug": "hiai-gg/docsmint",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_hiai_gg_docsmint_e8f869be/readme"
}