AI Dot Md

📝 AIDotMd

Your AI agents do the research. AIDotMd captures, organizes, and shares it — on your own machine.

Self-hosted knowledge base where Claude, Cursor, and Windsurf write your docs automatically via MCP.

Quick Start · MCP Integration · Features · Sharing · Configuration · Tech Stack

______________________________________________________________________

为什么是AIDotMd？

每个使用AI工具的开发人员都会遇到同样的问题。AIDotMd是这样修复它的：

______________________________________________________________________

✨ 特性

捕获、组织和共享人工智能生成的知识所需的一切——零云依赖。

||功能|描述| |--|---------|-------------| | 🤖 | AI原生MCP服务器 |9个内置工具——代理可以列出、创建、搜索和流式传输文档| | ⚡ | 直播渲染器 |通过SSE观看代理写入时markdown逐块渲染| | 📜 | 版本历史 |查看和还原文档或部分的任何以前版本| | 🐳 | 单命令设置 | docker-compose up --build --全栈，无需配置| | 🔒 | 自托管 |您的文档、数据和存储。默认为SQLite，S3/R2可选| | 🔍 | 全文搜索 |跨所有部分和文档的即时搜索| | 🎨 | 美丽的读者 |干净、无干扰的文档阅读器，支持黑暗模式| | 📂 | 分段和段塞 |将文件组织成章节；每个文档都有一个人类可读的URL| | 📸 | 图片上传 |拖放存储在文件系统或S3上的图像上传| | 🔏 | 草案/已发布 |在草稿（仅限管理员）和已发布（公开）之间切换文档| | 🌐 | 随时随地分享 |配置公共URL（Cloudflare、ngrok等），复制链接始终有效| | 🖨️ | PDF导出 |直接从浏览器将任何文档打印为PDF——干净、样式化的输出| | 🚇 | Cloudflare隧道 |内置隧道服务——立即通过公共URL共享您的本地文档| | 🔄 | 自动更新 |使用部署感知说明从GitHub检查新版本|

______________________________________________________________________

🚀 快速开始

一个命令。全栈。不到一分钟就准备好了。

git clone https://github.com/Nikhil-Singh-2503/aidotmd.git
cd aidotmd
docker-compose up --build

打开 http://localhost:3000 --就是这样。

数据持续存在 在 ./data/ 在您的主机上——容器重启时不会丢失任何数据。

______________________________________________________________________

🌐 共享您的文档

快速共享（零配置）

AIDotMd包括一个 Cloudflare隧道 在Docker中自动运行的服务——无需帐户、域或配置。

启动堆栈时，会为容器分配一个免费的公共URL：

docker-compose up --build

# Once running, get your public URL:
docker-compose logs cloudflared | grep trycloudflare.com
# → https://abc123xyz.trycloudflare.com

与任何人共享该URL——他们可以在任何地方从任何设备读取您发布的文档。

注： 每次Docker重启时，URL都会发生变化。有关永久URL，请参阅下面的升级指南。

配置复制链接按钮

默认情况下 复制链接 每个文档页面上的按钮都会复制当前浏览器的URL（例如。 localhost:3000/docs/...).要使其始终复制公共URL，请执行以下操作：

1. 首选 设置→ 共享
2. 粘贴您的公共URL（Cloudflare、ngrok或任何自定义域）
3. 切换 “使用公共URL进行共享” → ON
4. 点击 保存

从现在开始，复制链接副本 https://your-public-url.com/docs/... --即使您在本地主机上浏览。

在每个文档页面上

每个文档的右上角都有三个操作按钮：

自动更新系统

AIDotMd包括一个内置的更新检查器，可帮助您保持最新状态：

要检查更新，请转到 管理员→ 更新 在管理面板中。

系统检查GitHub版本并提供：

• 当前版本与最新版本比较
• 主要/次要更新指标
• 部署特定的更新说明（docker compose vs git命令）
• 链接到GitHub上的完整更新日志

草稿与已发布

控制哪些文档对公众可见：

• 发表 --任何具有该URL的人都可以看到（所有文档的默认值）
• 草案 --仅在管理面板中可见；直接URL返回404

在文档编辑器中切换可见性 能见度 → 已发布/草稿。

______________________________________________________________________

永久公共URL（可选升级）

对于重新启动时不会更改的固定URL，请设置一个命名的Cloudflare隧道：

先决条件： 自由 Cloudflare帐户 +添加到Cloudflare DNS的域。

# 1. Install cloudflared and authenticate
brew install cloudflare/cloudflare/cloudflared   # macOS
cloudflared tunnel login                          # opens browser

# 2. Create tunnel and add DNS record
cloudflared tunnel create aidotmd
cloudflared tunnel route dns aidotmd docs.yourdomain.com

# 3. Get the tunnel token
cloudflared tunnel token aidotmd

更新您的 .env 文件：

CLOUDFLARE_TUNNEL_TOKEN=

更新 docker-compose.yml --更改 cloudflared 服务：

cloudflared:
  image: cloudflare/cloudflared:latest
  restart: unless-stopped
  command: tunnel --no-autoupdate run --token ${CLOUDFLARE_TUNNEL_TOKEN}
  environment:
    CLOUDFLARE_TUNNEL_TOKEN: ${CLOUDFLARE_TUNNEL_TOKEN}
  depends_on:
    - frontend
  networks:
    - aidotmd_net

同时更新中的后端环境 docker-compose.yml:

BASE_URL: "https://docs.yourdomain.com"
USE_PUBLIC_URL: "true"
CORS_ORIGINS: "https://docs.yourdomain.com,http://localhost:3000"

重新启动： docker-compose up --build --您的文档永久可用，网址为 https://docs.yourdomain.com.

______________________________________________________________________

🤖 MCP集成

AIDotMd内置 MCP（模型上下文协议）服务器 任何兼容的AI代理都可以连接到。

您的MCP API密钥在首次启动时自动生成。在以下网址找到它 设置→ MCP 在UI中。

连接克劳德桌面

将此添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aidotmd": {
      "type": "http",
      "url": "http://localhost:3000/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

连接光标

添加 .cursor/mcp.json 在您的项目根目录中，或通过 光标设置→ MCP:

{
  "mcpServers": {
    "aidotmd": {
      "url": "http://localhost:3000/mcp/?api_key=YOUR_API_KEY_HERE"
    }
  }
}

密钥嵌入在URL中(?api_key=…)为了光标兼容性。

可用工具

list_sections      → List all documentation sections
create_section     → Create a new section
list_documents     → List documents (optionally filtered by section)
get_document       → Fetch a document by ID or slug
create_document    → Create a new document with content
update_document    → Update title, content, or append to a document
stream_write       → Stream content chunk-by-chunk (live browser render)
commit_stream      → Finalize stream and save to database
search_docs        → Full-text search across all documents

直播在行动

当代理人来电时 stream_write，浏览器呈现markdown 生活，一个字符接一个字符。绿色 ● Live 表头中的指示器脉冲。当代理人来电时 commit_stream，它切换到 已保存✓ 并且该文档被持久化。

# Example: agent researches Redis and writes a doc in real-time
await stream_write(doc_id="abc123", chunk="# Redis Commands & Data Types\n\n")
await stream_write(doc_id="abc123", chunk="Redis supports **5 core data types**...\n")
await commit_stream(doc_id="abc123")
# → Doc is live in the browser and saved to DB

______________________________________________________________________

⚙️ 配置

所有配置都可以通过环境变量进行设置 docker-compose.yml 或通过 设置UI 在 /settings.

环境变量

版本和更新 --The VERSION 字段在构建时在容器中设置，不能通过环境变量进行配置。更新系统会自动检测您是通过Docker还是源代码运行，并显示相应的更新命令。

存储：本地文件系统

默认情况下，上传的图像和导出的markdown文件存储在 ./data/ 在您的主机上（作为Docker卷挂载）。容器内的路径为 /app/data/.

要使用其他主机路径，请在中更改卷装载 docker-compose.yml:

volumes:
  - /your/custom/path:/app/data   # ← change left side to any host path

存储：兼容Cloudflare R2/S3

STORAGE_BACKEND=s3
S3_BUCKET=your-bucket
S3_REGION=auto
S3_ACCESS_KEY_ID=your-key
S3_SECRET_ACCESS_KEY=your-secret
S3_ENDPOINT_URL=https://.r2.cloudflarestorage.com

数据库：PostgreSQL

DATABASE_URL=postgresql+asyncpg://user:password@host:5432/aidotmd

改变 DATABASE_URL 需要重新启动容器： docker-compose restart backend

______________________________________________________________________

🛠️ 本地开发

更喜欢实时重新加载？单独运行服务：

后端

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload
# → API: http://localhost:8000
# → Swagger UI: http://localhost:8000/docs

前端

cd frontend
npm install
npm run dev
# → http://localhost:5173

Vite-dev服务器代理 /api, /mcp，以及 /static 到 localhost:8000.

______________________________________________________________________

🗂️ 项目结构

aidotmd/
├── docker-compose.yml          # Single-command full-stack launch
├── data/                       # Persisted data (gitignored)
│   ├── aidotmd.db              # SQLite database
│   ├── aidotmd.config.json     # Runtime settings (MCP key, storage, etc.)
│   ├── docs/                   # Markdown file exports
│   │   └── {section}/{slug}.md
│   └── static/img/             # Uploaded images
│
├── backend/
│   ├── app/
│   │   ├── main.py             # FastAPI app + lifespan + MCP auth middleware
│   │   ├── config.py           # Pydantic settings (env vars)
│   │   ├── api/                # REST routers
│   │   │   ├── documents.py
│   │   │   ├── sections.py
│   │   │   ├── stream.py       # SSE endpoints (/live, /live/status)
│   │   │   ├── nav.py          # Sidebar tree builder
│   │   │   └── settings.py     # Settings CRUD + storage test
│   │   ├── mcp/
│   │   │   └── server.py       # FastMCP server (9 tools)
│   │   └── services/
│   │       ├── stream_manager.py   # In-memory pub/sub for live streaming
│   │       ├── document_service.py
│   │       └── settings_service.py
│   ├── alembic/                # Database migrations
│   └── requirements.txt
│
└── frontend/
    ├── nginx.conf              # SPA routing + API reverse proxy
    ├── Dockerfile              # Multi-stage: node build → nginx serve
    └── src/
        ├── pages/
        │   ├── HomePage.tsx         # Landing page
        │   ├── reader/DocPage.tsx   # Live SSE rendering + Copy Link + Print
        │   ├── admin/               # Document & section management
        │   └── Settings.tsx         # DB / Storage / MCP / Sharing config
        ├── components/
        │   ├── MarkdownRenderer.tsx
        │   └── DocsSidebar.tsx
        └── api/
            └── client.ts            # Type-safe API client

______________________________________________________________________

🏗️ 技术栈

Layer Technology Why

Backend FastAPI + SQLAlchemy (async) Fast, async-first, great OpenAPI docs

Database SQLite (default) / PostgreSQL Zero-config local; scales to Postgres for production

MCP Server FastMCP (StreamableHTTP) Protocol-compliant MCP with session management

Streaming Server-Sent Events (SSE) Native browser support, no WebSocket complexity

Frontend React 18 + Vite + Tailwind v4 Fast builds, utility-first styling

UI Components shadcn/ui + Radix Accessible, unstyled primitives

Markdown react-markdown + remark-gfm + highlight.js GFM tables, code highlighting, syntax colors

Serving nginx (Docker) SPA fallback + reverse proxy in one container

______________________________________________________________________

🆚 AIDotMd有何不同

|| AIDotMd |概念| GitBook | Docusaurus| |--|-------|--------|---------|------------| | 您的数据，您的存储 | ✅ 本地/S3|❌ 他们的云❌ 他们的云⚠️ 手册| | AI代理编写文档 | ✅ 本地MCP |❌ | ❌ | ❌ | | 直播渲染 | ✅ 上海证券交易所❌ | ❌ | ❌ | | 版本历史 | ✅ | ⚠️ 已付|⚠️ 已付|❌ | | 自托管 | ✅ | ❌ | 仅支付|✅ | | 单命令启动 | ✅ Docker |❌ | ❌ | ⚠️ 手册| | 通过链接分享（无复制粘贴） | ✅ 内置|✅ | ✅ | ❌ | | PDF导出 | ✅ | ⚠️ 已付|⚠️ 已付|❌ | | 内容无构建步骤 | ✅ | ✅ | ✅ | ❌ | | 开源 | ✅ MIT |❌ | ❌ | ✅ |

______________________________________________________________________

🤝 贡献

欢迎投稿！请先打开一个问题，讨论您想更改的内容。

提交拉取请求

提交PR时，请使用我们的 拉取请求模板:

# 1. Fork the repo
# 2. Clone your fork
git clone https://github.com/Nikhil-Singh-2503/aidotmd.git
cd aidotmd

# 3. Create a feature branch
git checkout -b feature/your-feature-name

# 4. Make changes and commit
# Follow Conventional Commits: feat/, fix/, docs/, etc.
git commit -m "feat: add awesome new feature"

# 5. Push and create PR
git push -u origin feature/your-feature-name

拉取请求清单

提交前，请确保：

• \[\]代码遵循项目惯例
• \[\]已进行自我审查
• \[\]为复杂逻辑添加了注释
• \[\]文件已更新（如需要）
• \[\]构建通行证： npm run build （前端）/测试通过
• \[\]为UI更改添加了截图

PR标题格式

使用 约定式提交:

feat(admin): add new dashboard feature
fix(search): resolve empty results issue
docs(readme): update installation steps
refactor(api): simplify document service

报告问题

• 使用GitHub问题
• 包括复制步骤
• 如果与UI相关，请添加屏幕截图
• 适当标记（错误、功能、增强）

______________________________________________________________________

📄 许可证

麻省理工学院——见 许可证 了解详情。

______________________________________________________________________

Built with ❤️ for the AI-native era of documentation.