knoweldge-base README

The project's README from github.com/rgem227/knoweldge-base. As one markdown file: README.md.

Knowledge Base Phase 1

This repository contains the phase 1 minimum viable file knowledge base.

Current Stack

PostgreSQL and object storage are reserved for a later migration. The current version does not require Docker, MinIO, or a running database service.

Local development

  1. Copy the root environment template to backend/.env:
Copy-Item ..\.env.example .env
  1. Install dependencies:
cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
  1. Initialize the SQLite database:
python -m app.db.init_db
  1. Run backend:
uvicorn app.main:app --reload

Verify

From the backend directory:

set PYTHONPATH=.
python -m pytest

PowerShell:

$env:PYTHONPATH = "."
python -m pytest

Initialize or recreate the SQLite tables:

python -m app.db.init_db

Runtime files are created under backend/data/:

The existing Docker Compose file is reserved for the later PostgreSQL and object storage migration. It is not required for the current phase.

Service start, restart, stop, and status commands are provided by the separate PowerShell control files under scripts/.

Current scope

Operational configuration is controlled through .env.example, backend/app/core/config.py, and the scripts under scripts/. The repository also includes a read-only REST API, OpenAPI endpoints, MCP integration, and the knowledge-base Skill under skills/knowledge-base/.

API examples

Log in and receive a token:

$body = @{
  username = "demo"
  password = "password-123"
} | ConvertTo-Json

Invoke-RestMethod `
  -Method Post `
  -Uri http://127.0.0.1:8000/api/v1/auth/login `
  -ContentType "application/json" `
  -Body $body

Upload a document:

$token = "<access_token>"
$knowledgeBaseId = 1

curl.exe `
  -X POST `
  "http://127.0.0.1:8000/api/v1/documents/upload" `
  -H "Authorization: Bearer $token" `
  -F "knowledge_base_id=$knowledgeBaseId" `
  -F "tags=制度,测试" `
  -F "file=@D:\path\to\guide.txt"

The generated API documentation is available at /docs.

Browser-local document preview

The frontend uses vue3-office-preview for DOCX, PPTX, XLS, and XLSX, @vue3-office/vue-pdf for PDF, and @deot/docs-markdown for Markdown. Files are fetched through the authenticated API into browser memory and rendered locally. No LibreOffice, ONLYOFFICE, Docker, or Python SDK is required for this preview path.

The original file remains in local storage. Markdown extraction and the legacy .doc, .xls, and .ppt fallback remain handled by the backend.

Folder API

Create a folder under a knowledge base:

$body = @{
  knowledge_base_id = 1
  name = "实验方案"
} | ConvertTo-Json

Invoke-RestMethod `
  -Method Post `
  -Uri http://127.0.0.1:8000/api/v1/folders `
  -Headers @{ Authorization = "Bearer $token" } `
  -ContentType "application/json" `
  -Body $body

Upload into a folder by adding folder_id to the multipart form. The web page does this automatically for the currently selected folder.

The knowledge base selector defaults to 全部. In this mode the page shows folders and root documents across all public knowledge bases. New folders are assigned to the knowledge base selected in the dialog; uploads from 全部 use the first available knowledge base unless a folder is selected.

MCP read-only service

The project includes a separate MCP service for agents. It shares the same SQLite database, local filesystem storage, JWT secret, and document reader as the FastAPI application. It supports local stdio and remote Streamable HTTP transports. Phase 1 exposes read-only tools:

The MCP process does not expose upload, move, delete, or folder-management operations. It uses the JWT identity from KB_MCP_TOKEN, so an agent cannot see documents that the corresponding user cannot read.

For local stdio clients, KB_MCP_TOKEN can be omitted. The agent must then call the authenticate tool once with the user's username and password; the short-lived session remains only in the MCP process memory.

Create the MCP environment once from PowerShell:

cd backend
python -m venv .mcp-venv
.\.mcp-venv\Scripts\python.exe -m pip install -r requirements-mcp.txt

Set the same database and storage settings as the API, then put a login access_token in KB_MCP_TOKEN:

$env:PYTHONPATH = "."
$env:KB_MCP_TOKEN = "<access_token>"
.\.mcp-venv\Scripts\python.exe -m app.mcp_server

The process speaks MCP over stdin/stdout. Do not add ordinary print() output to the service; diagnostics must go to stderr so the protocol remains valid.

For remote Streamable HTTP mode:

$env:PYTHONPATH = "."
$env:MCP_TRANSPORT = "streamable-http"
$env:MCP_HOST = "0.0.0.0"
$env:MCP_PORT = "8020"
$env:MCP_PATH = "/mcp"
$env:MCP_STATELESS_HTTP = "true"
.\.mcp-venv\Scripts\python.exe -m app.mcp_server

The remote endpoint is https://your-domain/mcp after HTTPS reverse proxy configuration. Remote clients must send Authorization: Bearer <access_token>. Configure the remote client with the same endpoint and protected Bearer credential used by the API connection.

The browser page /mcp-token.html reads the current logged-in account and requests an MCP Token without reading or storing the account password. The administrator page /admin.html is protected by the administrator role and allows user status, role, password, and MCP Token expiration policy changes.

Run the local protocol smoke test:

$env:PYTHONPATH = "."
.\.mcp-venv\Scripts\python.exe scripts\mcp_stdio_smoke.py

knoweldge-base (rgem227/knoweldge-base)

Searching Database…

293 ·GitHub
Knoweldge-base
这是什么？Knowledge Base 是一个可自建部署的个人或团队知识库：你把文档上传到多级文件夹里，在浏览器中预览，AI 智能体还能通过只读的 MCP 服务读取这些文档。这是第一阶段的最小可用版本。
这是托管服务，还是要我自己部署运行的？它是一个自建部署的 Web 应用：后端用 FastAPI，数据库是 SQLite，文件存储在本地文件系统，前端基于 Vue。同一个仓库里还附带一个供 AI 智能体使用的独立 MCP 服务。
怎么把它跑起来？把根目录的环境变量模板复制为 backend/.env，安装依赖，初始化 SQLite 数据库，然后启动后端。scripts/ 目录下的 PowerShell 脚本可以负责启动、停止、重启和查看状态，API 文档会自动在 /docs 提供。
我需要先装 Docker 或数据库服务器吗？不需要。当前版本不依赖 Docker、MinIO 或任何在运行的数据库服务——SQLite 加本地文件就够了。仓库里现有的 Docker Compose 文件是为以后迁移到 PostgreSQL 和对象存储预留的。
它现在有哪些做不到的事？它是明确的第一阶段 MVP：文档编辑、软删除和恢复只有所有者能操作，文件夹只有在为空时才能删除，旧格式的 DOC、XLS 和 PPT 的文字提取只能尽力而为。
我可以往里面存哪些类型的文件？单文件和批量上传都支持 PDF、文本/Markdown/HTML、图片、PowerPoint、Word 和 Excel 文件，每个文档都带有元数据和标签。
浏览器内预览需要 LibreOffice 或别的办公文档服务器吗？不需要——文件通过带身份验证的 API 拉取到浏览器内存里，由 Vue 组件在本地渲染：DOCX/PPTX/XLS(X) 用 vue3-office-preview，PDF 用 vue-pdf，Markdown 用 docs-markdown。
谁能看到我的文档？访问要经过管理员创建的用户账号和 JWT 登录，MCP 令牌也携带这个 JWT 身份，所以智能体只能看到其所属用户有权限读取的文档。文件保存在本地存储中并有路径穿越防护，管理员还有审计日志页面可用。
误删的文档还能找回来吗？可以——删除是软删除，有回收站列表和恢复功能，而且这两个操作都仅限文档所有者使用。整个文件夹和文档还可以跨知识库复制，包括递归复制整个文件夹。
AI 智能体怎么登录 MCP 服务？可以在 KBMCPTOKEN 里放一个长期有效的访问令牌；本地 stdio 客户端也可以不用令牌，改为用你的用户名和密码调用一次 authenticate 工具——这种短期会话只保存在 MCP 进程内存里。/mcp-token.html 页面可以签发令牌，不会读取或保存你的密码。
它也有普通的 REST API 吗？有——后端提供只读的 REST API，带 OpenAPI 端点，文档自动生成在 /docs。远程 MCP 客户端通过 HTTPS 反向代理连接，并使用 Authorization: Bearer 凭据，仓库里还在 skills/knowledge-base/ 下附带了一个 knowledge-base Skill。
What are similar projects?jevbox, gin-vue-admin, agentic-inbox, Octop, clevis, ApeAdmin, siyuan, financial_intelligence_system_web
Which topics is it in?personal-knowledge-management, office, jwt, fastapi, search, knowledge-base, authentication, pdf, vue, sqlite, rest-api, mcp-server
Creator
rgem227
Size
5.2 MB
Stars
293
Updated
CommitSep 22
Age
26d
Commits · 90 Days