Notedthat

A markdown-first knowledgebase system exposed as an HTTP API, MCP server, and WebDAV endpoint. NotedThat stores notes as plain Markdown files, indexes them for semantic search via Qdrant, and surfaces them through multiple access protocols so editors, AI agents, and WebDAV clients can all work with the same content.

Status: pre-v1 — under active development. APIs and crate interfaces are unstable.

Documentation

• SPECIFICATIONS.md — full product and architecture specification
• DEVELOPMENT.md — developer commands and test conventions
• RELEASING.md — release runbook and Trusted Publishing setup
• LICENSE — Mozilla Public License 2.0

Crate Map

Crate	Path	Role
notedthat-core	crates/notedthat-core	Shared domain types, path/range/error/auth primitives, config
notedthat-storage-s3	crates/notedthat-storage-s3	S3 storage adapter
notedthat-indexer	crates/notedthat-indexer	Chunking, embedder client, Qdrant integration
notedthat-write	crates/notedthat-write	Shared write path (commit(), commit_delete(), MIME sniff, 5 GiB limit) — used by HTTP API + WebDAV surfaces
notedthat-api-http	crates/notedthat-api-http	HTTP API surface
notedthat-webdav	crates/notedthat-webdav	WebDAV surface
notedthat-mcp	crates/notedthat-mcp	MCP tool schemas and HTTP-backed implementation
notedthat-server	crates/notedthat-server	Main server binary — HTTP API + WebDAV + remote MCP in one process (release facade). Published to ghcr.io/notedthat/server per tagged release.
notedthat-mcp-stdio	crates/notedthat-mcp-stdio	MCP-over-stdio transport adapter

All 9 crates share a single version via ecosystem-level Semantic Versioning. See RELEASING.md for the versioning policy.

Running locally

NotedThat requires an S3-compatible object store. For local development, we use SeaweedFS >= 4.18 in Docker.

# 1. Start SeaweedFS on the S3 gateway port (8333)
docker run -d --name nt-seaweedfs \
  -p 8333:8333 \
  chrislusf/seaweedfs:4.18 server -s3 -filer

# 2. Start the NotedThat server
NOTEDTHAT_API_TOKEN=dev-token \
NOTEDTHAT_KBS=notes,scratch \
NOTEDTHAT_S3_ENDPOINT_URL=http://127.0.0.1:8333 \
NOTEDTHAT_S3_REGION=us-east-1 \
NOTEDTHAT_S3_ACCESS_KEY_ID=any \
NOTEDTHAT_S3_SECRET_ACCESS_KEY=any \
NOTEDTHAT_S3_FORCE_PATH_STYLE=true \
NOTEDTHAT_LISTEN_ADDR=127.0.0.1:8080 \
RUST_LOG=info,notedthat=debug \
cargo run -p notedthat-server

# 3. Verify the server is running
curl http://127.0.0.1:8080/healthz

# 4. Try the API
curl -H "Authorization: Bearer dev-token" \
     http://127.0.0.1:8080/v1/knowledgebases

# 5. Upload a file
echo "# Hello World" | curl -X PUT \
  -H "Authorization: Bearer dev-token" \
  -H "Content-Type: text/markdown" \
  --data-binary @- \
  http://127.0.0.1:8080/v1/knowledgebases/notes/hello.md

# 6. Read it back
curl -H "Authorization: Bearer dev-token" \
     http://127.0.0.1:8080/v1/knowledgebases/notes/hello.md

Docker (prebuilt image)

Once the first tagged release exists, the server image is published to GHCR at ghcr.io/notedthat/server. Every published image is cosign-signed (keyless via Sigstore/Fulcio) and carries a SLSA L2 build provenance attestation.

docker pull ghcr.io/notedthat/server:latest

docker run --rm -p 8080:8080 -p 8081:8081 -p 8082:8082 \
  -e NOTEDTHAT_API_TOKEN=dev-token \
  -e NOTEDTHAT_KBS=notes,scratch \
  -e NOTEDTHAT_S3_ENDPOINT_URL=http://host.docker.internal:8333 \
  -e NOTEDTHAT_S3_REGION=us-east-1 \
  -e NOTEDTHAT_S3_ACCESS_KEY_ID=any \
  -e NOTEDTHAT_S3_SECRET_ACCESS_KEY=any \
  ghcr.io/notedthat/server:latest

Ports published:

• 8080 — HTTP API
• 8081 — WebDAV
• 8082 — MCP HTTP (Streamable HTTP, POST /mcp; TLS-terminate at a reverse proxy before exposing publicly)

Or use docker compose up with the bundled docker-compose.yml for a full local stack (SeaweedFS + Qdrant + server).

Verify the signature + provenance before running in production:

gh attestation verify oci://ghcr.io/notedthat/server:0.2.0 --owner NotedThat

WebDAV

With the server running (steps 1-2 above), also set the WebDAV credentials:

export NOTEDTHAT_WEBDAV_USERNAME=webdav-user-please-change
export NOTEDTHAT_WEBDAV_PASSWORD=webdav-pass-please-change

# 7. PROPFIND root (list KBs)
curl -X PROPFIND -u "$NOTEDTHAT_WEBDAV_USERNAME:$NOTEDTHAT_WEBDAV_PASSWORD" \
  -H 'Depth: 1' http://127.0.0.1:8081/

# 8. PUT a markdown file via WebDAV
echo "# Hello WebDAV" | curl -X PUT \
  -u "$NOTEDTHAT_WEBDAV_USERNAME:$NOTEDTHAT_WEBDAV_PASSWORD" \
  --data-binary @- \
  http://127.0.0.1:8081/notes/hello-webdav.md

# 9. GET it back
curl -u "$NOTEDTHAT_WEBDAV_USERNAME:$NOTEDTHAT_WEBDAV_PASSWORD" \
  http://127.0.0.1:8081/notes/hello-webdav.md

# 10. DELETE it
curl -X DELETE -u "$NOTEDTHAT_WEBDAV_USERNAME:$NOTEDTHAT_WEBDAV_PASSWORD" \
  http://127.0.0.1:8081/notes/hello-webdav.md

MCP (Claude Desktop, Cursor, Zed)

With the server running (steps 1-2 above), configure your MCP client to launch notedthat-mcp-stdio as a subprocess.

Remote MCP hosting

NotedThat also exposes an HTTP MCP endpoint for remote clients that support the MCP HTTP transport:

• Endpoint: POST /mcp on port 8082 (configurable via NOTEDTHAT_MCP_HTTP_BIND)
• Auth: Authorization: Bearer <NOTEDTHAT_API_TOKEN> (same token as the HTTP API)
• Note: public deployments require HTTPS termination at a reverse proxy before exposing this port

See docs/API.md for the full MCP transport and Resources protocol docs.

Install options

Three ways to get notedthat-mcp-stdio onto your PATH — all equivalent, pick whichever fits your setup. Installer scripts become available after the first tagged release.

Shell installer (macOS / Linux):

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/NotedThat/NotedThat/releases/latest/download/notedthat-mcp-stdio-installer.sh | sh

PowerShell installer (Windows):

powershell -c "irm https://github.com/NotedThat/NotedThat/releases/latest/download/notedthat-mcp-stdio-installer.ps1 | iex"

cargo install (requires a Rust toolchain):

cargo install notedthat-mcp-stdio

Once installed, wire it into your MCP client:

{
  "mcpServers": {
    "notedthat": {
      "command": "notedthat-mcp-stdio",
      "env": {
        "NOTEDTHAT_URL": "http://localhost:8080",
        "NOTEDTHAT_TOKEN": "your-token-here"
      }
    }
  }
}

Every prebuilt binary is cosign-signed with a SLSA L2 build provenance attestation — verify before running:

cosign verify-blob \
  --bundle notedthat-mcp-stdio.bundle \
  --certificate-identity-regexp 'https://github.com/NotedThat/NotedThat/.+' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  notedthat-mcp-stdio

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "notedthat": {
      "command": "notedthat-mcp-stdio",
      "env": {
        "NOTEDTHAT_URL": "http://localhost:8080",
        "NOTEDTHAT_TOKEN": "your-token-here"
      }
    }
  }
}

Restart Claude Desktop after saving.

Cursor

Add to Cursor's settings (.cursor/mcp.json or via Settings → MCP):

{
  "mcpServers": {
    "notedthat": {
      "command": "notedthat-mcp-stdio",
      "env": {
        "NOTEDTHAT_URL": "http://localhost:8080",
        "NOTEDTHAT_TOKEN": "your-token-here"
      }
    }
  }
}

Zed

Add to Zed settings (~/.config/zed/settings.json):

{
  "assistant": {
    "mcp_servers": {
      "notedthat": {
        "command": {
          "path": "notedthat-mcp-stdio",
          "env": {
            "NOTEDTHAT_URL": "http://localhost:8080",
            "NOTEDTHAT_TOKEN": "your-token-here"
          }
        }
      }
    }
  }
}

Full environment variable reference: docs/CONFIGURATION.md

Full API documentation: docs/API.md

Contributing

See CONTRIBUTING.md for the contribution process — PR workflow, commit conventions (Conventional Commits + signed + DCO), testing requirements, and AI-assistance disclosure. Build, test, and run commands live in DEVELOPMENT.md. The project is pre-v1, so interfaces change frequently — check open issues before starting significant work.

License

Mozilla Public License 2.0. See LICENSE for the full text.