DocsMint
by HiAi-gg
README.md
# DocsMint
**Turn your documents into knowledge you and your AI agents can use.**
Write and organize notes, guides, and project documentation in one workspace.
Find answers with search that understands related concepts, then give your
agents access to the same documents through MCP, REST, the SDK, or CLI.
**[Connect DocsMint Cloud](https://docsmint.com/mcp/connect?source=github_mcp)** to get started without
operating the stack, or **[self-host with Docker](#quickstart)** to run the
Apache-2.0 application on your own infrastructure.
[](LICENSE)
[](https://github.com/hiai-gg/docsmint/releases)
[](https://www.npmjs.com/package/@hiai-gg/docsmint)
[](https://hub.docker.com/r/vgalibov/docsmint)
[](https://github.com/hiai-gg/docsmint/actions/workflows/ci.yml)
[](https://hol.org/registry/plugins/hiai-gg%2Fdocsmint)
[](https://glama.ai/mcp/servers/HiAi-gg/docsmint)
[](https://lobehub.com/mcp/hiai-gg-docsmint)
[](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.HiAi-gg%2Fdocsmint/versions/latest)
[](https://docsmint.com/mcp/connect?source=github_mcp)
[](https://bun.sh)
[](https://www.typescriptlang.org)
[](https://svelte.dev)
[](https://elysiajs.com)
[](https://tailwindcss.com)
[](https://orm.drizzle.team)
[](https://github.com/hiai-gg/docsmint/stargazers)
[](CONTRIBUTING.md)
<img width="1920" height="974" alt="DocsMint installable document workspace" src="https://github.com/user-attachments/assets/94701d01-a361-4ca1-b16d-de2a0c64d684" />
## Connect your AI agent
Connect DocsMint Cloud instantly or run the self-hosted stdio bridge against
your own DocsMint API. Both paths give agents access to persistent knowledge;
the self-hosted bridge exposes 22 focused tools covering all 31 existing operations plus bounded batch actions and direct workspace-item inspection, with 2 prompts and 3 resources.
**Recommended: [DocsMint Cloud setup](https://docsmint.com/mcp/connect?source=github_mcp).**
No server installation is required. Sign up or log in, choose your workspace,
and follow your client's connection instructions. OAuth-capable clients use
browser consent; API-key clients create an MCP/API credential in the authenticated
browser UI. Hosted MCP follows your plan and workspace permissions. Prefer
workspace-bound or category-scoped credentials.
The Cloud endpoint is `https://docsmint.com/mcp` (Streamable HTTP). OAuth-capable
clients discover the hosted resource and authorization-server metadata; current
authorization and client-connection methods are described in the
[DocsMint Cloud setup guide](https://docsmint.com/mcp/connect?source=github_mcp).
Browser consent binds access to the selected workspaces, optional categories, and requested scopes.
DocsMint Cloud 1.1.9 and later supports hourly access tokens and rotating refresh tokens for up to
30 days from authorization when the client supports renewal. Existing connections need one reconnect
to enable refresh; clients without refresh support still reconnect after access expires.
API-key clients can instead send
`Authorization: Bearer <key>` with an MCP/API credential created in the authenticated
browser UI. Credentials cannot create or elevate other credentials; lifecycle
management belongs to the signed-in browser session.
**Self-hosted alternative:** run [DocsMint with Docker](#quickstart), create an API
key in its browser UI, and configure `HIAI_DOCS_URL` and `HIAI_DOCS_API_KEY` for
`npx --yes --package @hiai-gg/docsmint docsmint-mcp`. Install Bun 1.4.4 or
later to execute the published binary. The npm package is a stdio bridge to
your own API; it does not install the DocsMint application or Cloud OAuth server.
See the [MCP guide](https://github.com/HiAi-gg/docsmint/blob/main/packages/mcp-server/README.md)
for client configuration. The [Glama OSS Server listing](https://glama.ai/mcp/servers/HiAi-gg/docsmint)
describes this bridge; the hosted [DocsMint Cloud Connector](https://glama.ai/mcp/connectors/io.github.HiAi-gg/docsmint)
is a separate listing.
## Why DocsMint?
- **Keep knowledge easy to edit.** Use a rich visual editor or Markdown;
organize documents with folders, categories, and tags.
- **Find the document you mean.** Search combines keywords, meaning, typo
tolerance, and graph relationships across languages.
- **Keep agents close to the source.** Let your tools search, read, and update
the same knowledge through MCP, REST, a typed SDK, and CLI.
- **Choose what an integration can access.** Category keys grant explicit
`read`, `edit`, and `write` permissions for a defined part of your library.
- **Keep retrieval up to date.** Document edits and metadata changes refresh
the search index automatically in the background.
- **Choose how you run it.** Use [managed DocsMint](https://docsmint.com) or
self-host the application, database, search, queues, and files.
## Security patch 2.1.1
Bun 1.4.4, SvelteKit/Vite and Better Auth patch refreshes preserve the existing MCP/REST contract. See [2.1.1 release notes](docs/release/v2.1.1-notes.md) and the [security report](docs/security/2026-11-02-security-refresh.md).
## What's new in 2.1.0?
- Add stateless Bearer HTTP MCP for self-hosted installations, including the public web-origin proxy and configurable Origin/CORS policy.
- Keep the 22-tool catalog and generate schemas, annotations and branch examples from real MCP discovery.
- Return redacted argument diagnostics as JSON-RPC errors without replacing upstream dispatch; keep compatible compact text and structured results.
- Add server-side document filters, stable cursor pagination, scoped totals, previews, metadata-rich export and normalized search fields.
- Add credential/workspace discovery and an explicit SDK API prefix while retaining existing routes, fields and methods.
[2.1.0 release notes](docs/release/v2.1.0-notes.md).
## Previous release: 2.0.4
Hosted MCP integrations can discover granted workspaces, including empty spaces, with
`list_workspace_structure(kind="workspaces")` and select one with the optional
`workspaceId` argument. The catalog remains 22 tools. Host authorization hooks preserve
the connection's existing workspace/category boundaries. Multi-scope reads carry labeled
results and independent pagination. Existing single-scope calls remain compatible.
The OSS frontend adopts SvelteKit 3; dependency updates resolve the current security
audit findings. No database migration is required. See the
[2.0.4 release notes](docs/release/v2.0.4-notes.md).
## Previous release: 1.0.3
- Make MCP tool selection clearer: use a single-document tool for one document
and `batch_documents` when multiple explicit IDs need the same action.
- Keep the 22-tool catalog, all 31 underlying operations, input schemas,
authorization, and stdio behavior unchanged. The LobeHub tool descriptions
match the released MCP catalog.
- DocsMint Cloud remains a separate hosted Connector. Cloud descriptions
change only when the hosted service adopts this package version.
No database migration is required. See the [release notes](https://github.com/HiAi-gg/docsmint/releases/tag/v1.0.3)
and [changelog](https://github.com/HiAi-gg/docsmint/blob/main/CHANGELOG.md).
## Install with an AI agent
Prefer an assisted self-hosted setup? Give your coding agent this prompt.
You will need Docker and a choice of AI provider.
```text
Install DocsMint from https://github.com/HiAi-gg/docsmint.
Verify Docker and Docker Compose v2, clone the repository, and run
`bash scripts/quickstart.sh`. Do not print or commit .env. Ask me to enter only
an OpenRouter key or select Ollama, then run quickstart again. Verify
http://localhost:50701, http://localhost:50700/api/health, and
`docker compose ps`. Do not replace Bun, rewrite migrations, disable GraphRAG,
or delete volumes.
```
After startup, open **http://localhost:50701** and create the first account.
For manual installation, use the Docker quickstart below.
## Quickstart
### Requirements
- Docker Engine or Docker Desktop
- Docker Compose v2
- One of:
- an [OpenRouter](https://openrouter.ai/) API key; or
- a local [Ollama](https://ollama.com/) instance
### Start with Docker
```bash
git clone https://github.com/HiAi-gg/docsmint.git
cd docsmint
bash scripts/quickstart.sh
```
On its first run, the script creates an ignored root `.env`, generates the
database, authentication, and storage secrets, builds the PostgreSQL image,
applies migrations, and starts the complete application.
Published application images are on
[Docker Hub](https://hub.docker.com/r/vgalibov/docsmint). There is no untagged
`latest` image; pull the role-specific tags:
```bash
docker pull vgalibov/docsmint:api-latest
docker pull vgalibov/docsmint:web-latest
docker pull vgalibov/docsmint:caddy-latest
```
Use versioned tags `api-v1.0.3`, `web-v1.0.3`, and `caddy-v1.0.3` for
reproducible deploys. Caddy is the supporting reverse proxy with rate limiting;
it is separate from the API and web application. The quickstart still builds the Compose stack from this repository so PostgreSQL,
Redis, and SeaweedFS start together with the application.
For OpenRouter, add one value to `.env` and run the script again:
```dotenv
OPENROUTER_API_KEY=sk-or-your-key
```
For Ollama, select the local provider instead:
```dotenv
AI_PROVIDER=ollama
OLLAMA_PORT=11434
```
Then make sure the configured local models are available:
```bash
ollama pull bge-m3
ollama pull qwen3:8b
bash scripts/quickstart.sh
```
Open **http://localhost:50701**. The API health endpoint is
**http://localhost:50700/api/health**.
### First use
1. Create your account in the web application.
2. Create a category or folder and add or import a document.
3. Wait for the document pipeline to finish chunking and embedding.
4. Search using an exact phrase, a related concept, an alternate language, or
a misspelling.
5. Open **Settings → API** when you want to connect a CLI, MCP client, or
external application.
The canonical local ports are:
| Service | Port |
| -------------------- | ------: |
| Web application | `50701` |
| REST API | `50700` |
| PostgreSQL | `5437` |
| Redis | `6384` |
| SeaweedFS S3 gateway | `50702` |
| SeaweedFS filer UI | `50703` |
See [Deployment](https://github.com/HiAi-gg/docsmint/blob/main/docs/DEPLOYMENT.md) for domains, TLS, provider tuning,
backups, and production operation.
Embedding provider URLs, models, and credentials are deployment configuration.
They are never stored in browser settings or local storage.
## Use DocsMint from the terminal
One public package, **`@hiai-gg/docsmint`**, includes the TypeScript SDK,
`docsmint` CLI, and `docsmint-mcp` bridge. These clients connect to a running
DocsMint deployment; use the Docker quickstart to install the self-hosted server.
```bash
bun add @hiai-gg/docsmint
```
```bash
bunx --package @hiai-gg/docsmint docsmint init \
--url http://localhost:50700 \
--key 'your-global-or-category-key'
bunx --package @hiai-gg/docsmint docsmint search "project architecture"
bunx --package @hiai-gg/docsmint docsmint list
bunx --package @hiai-gg/docsmint docsmint read <document-id>
bunx --package @hiai-gg/docsmint docsmint create \
--title "Release notes" --content "# Highlights"
```
Credentials can also be supplied through `HIAI_DOCS_URL` and
`HIAI_DOCS_API_KEY`. See the [CLI guide](https://github.com/HiAi-gg/docsmint/blob/main/packages/cli/README.md) for every
command and configuration precedence.
## Connect an MCP client
Give agents a secure path to search, read, and maintain your knowledge without
database or filesystem access. DocsMint publishes MCP tools plus ready-made
research prompts, scoped resources, and a document-manager skill.
### Hosted DocsMint
Connect directly to the managed Streamable HTTP endpoint. Keep the API key in
an environment variable rather than writing it into client configuration:
```bash
codex mcp add docsmint \
--url https://docsmint.com/mcp \
--bearer-token-env-var HIAI_DOCS_API_KEY
```
### Self-hosted DocsMint
Run the published stdio bridge against your own DocsMint API:
```json
{
"mcpServers": {
"docsmint": {
"command": "npx",
"args": ["--yes", "--package", "@hiai-gg/docsmint", "docsmint-mcp"],
"env": {
"HIAI_DOCS_URL": "http://localhost:50700",
"HIAI_DOCS_API_KEY": "your-global-or-category-key"
}
}
}
}
```
Category keys let you expose only the documents and operations an agent needs.
Use a global key only for trusted owner-wide automation. See the
[complete MCP reference](https://github.com/HiAi-gg/docsmint/blob/main/packages/mcp-server/README.md) for Bun, npm, local
checkout, all tools, prompts, resources, permissions, and REST mappings.
### Self-hosted HTTP
The same 22-tool contract is also available at `/mcp` on your installation's
**public web origin**. With the default Compose ports, that is
`http://localhost:50701/mcp`; with Caddy, use your normal application domain,
such as `https://docs.example.com/mcp`. The web server streams requests to the
backend using its trusted `API_URL` setting (`http://api:50700` in Compose).
Do not point `API_URL` back at the public web server.
Create a global or category-scoped key in **Settings → API**, then supply it
as an environment variable to your MCP client:
```bash
codex mcp add docsmint-selfhost \
--url https://docs.example.com/mcp \
--bearer-token-env-var HIAI_DOCS_API_KEY
```
Self-hosted HTTP uses `Authorization: Bearer <key>`; it does not implement
DocsMint Cloud OAuth or accept a browser session as an API credential. Category
keys keep their existing category and independent read/edit/write restrictions.
An ordinary OSS installation has a personal space rather than Cloud workspace
slugs: omit `X-Docsmint-Workspace` on these requests.
Configure the public application URL and the exact browser origins you trust:
```dotenv
PUBLIC_APP_URL=https://docs.example.com
CORS_ORIGINS=https://docs.example.com,https://trusted-client.example.com
MCP_HTTP_ENABLED=true
```
`PUBLIC_APP_URL` is used for trusted absolute document links; leaving it unset
keeps OSS document links relative. `CORS_ORIGINS` applies to the HTTP integration
endpoints. An allowed browser origin receives CORS headers, an unknown Origin
is rejected, and authenticated server clients may omit Origin. Do not use a
wildcard for credentialed browser access. Compose passes these settings to the
API container; restart the application through your normal deployment workflow
after changing them.
The HTTP transport is stateless and does not issue `Mcp-Session-Id`. Send MCP
JSON-RPC through POST; accepted notifications return 202. GET and DELETE return
405 because this endpoint provides neither a standalone SSE listener nor
server-side sessions. Clients must accept JSON and SSE responses: the installed
MCP SDK can use SSE for legacy protocol requests even when modern JSON mode is
configured. `/mcp/` is normalized internally without redirecting the POST or
dropping its Bearer header. The proxy preserves response status, authentication
challenges, CORS headers and streaming bodies, and does not forward browser
cookies or server workspace assertions as authority.
Set `MCP_HTTP_ENABLED=false` to disable this HTTP endpoint independently. The
existing REST API and stdio bridge remain available; existing stdio client
configuration does not need to change.
## TypeScript SDK
```bash
bun add @hiai-gg/docsmint
```
```ts
import { DocsClient } from '@hiai-gg/docsmint';
const docs = new DocsClient({
baseUrl: 'http://localhost:50700',
apiKey: process.env.HIAI_DOCS_API_KEY,
});
const created = await docs.createDoc({
title: 'Meeting notes',
content: '# Agenda',
});
const results = await docs.search('what did we decide?');
console.log(created.id, results.items);
```
The SDK is a typed `fetch` client with retries for transient failures and
idempotent document creation retries. See the
[SDK reference](https://github.com/HiAi-gg/docsmint/blob/main/packages/sdk/README.md) and [REST API](https://github.com/HiAi-gg/docsmint/blob/main/docs/API.md).
## API keys and integrations
Create and revoke integration keys from **Settings → API**.
| Credential | Intended use | Access |
| -------------- | -------------------------------------------- | -------------------------------------- |
| Global API key | Trusted owner-wide CLI, MCP, SDK, or service | All owner content |
| Category key | Least-privilege agent or product integration | One category with selected permissions |
| Operator key | Administration and reindex operations | `/api/admin/*` only |
Category permissions are explicit and non-hierarchical:
- `read` permits list, read, search, and export;
- `edit` permits updates to existing content, attachments, and versions;
- `write` permits create, move, delete, share, and publish operations.
Combine permissions when an integration needs more than one capability.
API-key lifecycle operations require the owning browser session; an API key
cannot create or elevate another key. Server-to-server integrations are not
affected by browser CORS. Browser integrations must add their exact origin to
`CORS_ORIGINS`.
## What is included?
Documents use structured TipTap JSON as canonical content. Markdown is the
source-editing, import, and export format. The same document store serves the
web application and public integration interfaces.
```text
frontend/ SvelteKit workspace and TipTap editor
backend/ Elysia REST API, search, workers, and authentication
packages/db/ Drizzle schema and migrations
packages/sdk/ Typed API client
packages/cli/ Terminal client
packages/mcp-server/ MCP stdio and HTTP contract
postgres/ PostgreSQL image with vector and graph extensions
```
The Docker deployment runs:
- **Web** — document editor, folders, categories, sharing, settings, and search;
- **API** — documents, attachments, versions, keys, search, and administration;
- **PostgreSQL 18** — relational data, pgvector/pgvectorscale vectors, and the
Apache AGE graph in one database;
- **Redis 8** — BullMQ queues, caching, retries, and job recovery;
- **SeaweedFS** — S3-compatible attachment storage.
## How search works
Every document save schedules background work. Content is chunked, changed
chunks are embedded, and the completed generation is activated atomically. The
previous valid generation remains searchable if a provider call fails.
Search combines exact title matches, multilingual lexical search, typo-tolerant
fuzzy matching, semantic vectors, adaptive query expansion, and Apache AGE
graph neighbors. Reciprocal rank fusion combines the channels without allowing
one weak provider result to dominate. A cross-encoder then reranks the fused
prefix against the original query (Voyage rerank-2.5 by default). On a labeled
24-document corpus that moved MRR 0.969 → 1.000 and nDCG@10 0.958 → 0.986
versus RRF-only. Rerank, expansion, embeddings, and AGE failures keep the
remaining channels. Authorization is applied before retrieval and again before
results are returned.
GraphRAG is part of the normal search path in the reference configuration. It
extracts entities after embeddings are ready and finds related documents beyond
direct keyword or vector similarity. It degrades gracefully when an external
model is unavailable.
For pipeline internals and tuning, see [Architecture](https://github.com/HiAi-gg/docsmint/blob/main/docs/ARCHITECTURE.md) and
[Deployment](https://github.com/HiAi-gg/docsmint/blob/main/docs/DEPLOYMENT.md).
## Stack
- Bun 1.4.4+, TypeScript, Elysia, Zod, and Pino
- Svelte 5, SvelteKit, Tailwind CSS, and TipTap
- Better Auth and Drizzle ORM
- PostgreSQL 18, pgvector, pgvectorscale, and Apache AGE
- Redis 8 and BullMQ
- SeaweedFS with its S3-compatible API
- OpenAI-compatible providers through OpenRouter or local Ollama
## Documentation
- [Documentation index](https://github.com/HiAi-gg/docsmint/blob/main/docs/README.md)
- [Product usage](https://github.com/HiAi-gg/docsmint/blob/main/docs/USAGE.md)
- [Roadmap](https://github.com/HiAi-gg/docsmint/blob/main/docs/ROADMAP.md)
- [REST API](https://github.com/HiAi-gg/docsmint/blob/main/docs/API.md) and [OpenAPI JSON](https://github.com/HiAi-gg/docsmint/blob/main/docs/openapi.json)
- [Architecture](https://github.com/HiAi-gg/docsmint/blob/main/docs/ARCHITECTURE.md)
- [Deployment and operations](https://github.com/HiAi-gg/docsmint/blob/main/docs/DEPLOYMENT.md)
- [Extension points](https://github.com/HiAi-gg/docsmint/blob/main/docs/EXTENDING.md)
- [Maintainer release flow](https://github.com/HiAi-gg/docsmint/blob/main/docs/RELEASING.md)
- [Security policy](https://github.com/HiAi-gg/docsmint/blob/main/SECURITY.md)
- [Changelog](https://github.com/HiAi-gg/docsmint/blob/main/CHANGELOG.md)
## Development
Use Bun 1.4.4 or later for local development.
```bash
bun install
bun run lint
bun run typecheck
bun run test
bun run build
```
Read [CONTRIBUTING.md](https://github.com/HiAi-gg/docsmint/blob/main/CONTRIBUTING.md) before opening a pull request. Please
report vulnerabilities through [SECURITY.md](https://github.com/HiAi-gg/docsmint/blob/main/SECURITY.md), not a public issue.
## License
DocsMint is released under the [Apache License 2.0](https://github.com/HiAi-gg/docsmint/blob/main/LICENSE).
Built as an independent open-source project in the
[HiAi](https://github.com/HiAi-gg) ecosystem.
TDQS
A3.9/5.0
Scored across 22 tools
Disambiguation4/5
Most tools target a distinct resource+action pair, and descriptions actively cross-reference alternatives (e.g. delete_document vs permanently_delete_document, restore_trashed_document vs restore_document_version, single vs batch operations). A few boundaries are softer: get_workspace_item is a grab-bag reader for folders/categories/tags that sits close to list_workspace_structure, and tag handling is spread across save_tag, set_document_tag, and batch_documents(action=add_tag), though the descriptions do clarify each case.
Naming Consistency4/5
Almost everything follows a snake_case verb_noun pattern (list_trash, find_documents, save_document, delete_folder, restore_trashed_document). Minor deviations: batch_documents uses a bare noun-ish verb, permanently_delete_document stacks an adverb, and save_* doubles as create-or-update rather than a verb per operation.
Tool Count3/5
22 tools is on the heavy side of the 3-15 sweet spot; the domain is genuinely broad (documents, folders, categories, tags, trash, versions, indexing, graph), so most tools earn a place. Still, a few could collapse (e.g. get_workspace_item into list/read patterns, and delete_document plus permanently_delete_document into one parameterized delete), making the surface feel wide rather than tight.
Completeness4/5
Full lifecycle coverage is present: create/read/update for documents, folders, categories, tags; trash, restore, and permanent purge; version snapshot and restore; index status and refresh; plus batch and graph exploration. Remaining gaps are minor, such as no explicit document move/copy tool outside batch_documents(action=move) and no bulk folder/tag hierarchy operations.
Maintenance
ActivityNo data
ResponsivenessOutdated data