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
What is this?Knoweldge Base is a self-hosted personal or team knowledge base: you upload documents into nested folders, preview them in the browser, and AI agents can read them through a read-only MCP service. This is the Phase 1 minimum viable version.
Is this a hosted service or something I run myself?It is a self-hosted web application: a FastAPI backend with a SQLite database and local-filesystem storage, plus a Vue-based frontend. There is also a separate MCP service for AI agents bundled in the same repo.
How do I get it running?Copy the root environment template to backend/.env, install dependencies, initialize the SQLite database, and run the backend. PowerShell scripts under scripts/ handle start, stop, restart, and status, and API docs are auto-served at /docs.
Do I need Docker or a database server first?No. The current version needs no Docker, MinIO, or running database service — SQLite and local files are enough. The existing Docker Compose file is reserved for a later PostgreSQL and object-storage migration.
Is there anything it cannot do yet?It is an explicit Phase 1 MVP: document editing, soft delete, and restore are owner-only operations, folders can only be deleted when empty, and text extraction for legacy DOC, XLS, and PPT is best-effort.
What kinds of files can I store in it?Single-file and batch uploads accept PDF, text/Markdown/HTML, images, PowerPoint, Word, and Excel files, and every document carries metadata and tags.
Do I need LibreOffice or another office server for in-browser previews?No — files are fetched through the authenticated API into browser memory and rendered locally by Vue components: vue3-office-preview for DOCX/PPTX/XLS(X), vue-pdf for PDF, and docs-markdown for Markdown.
Who can see my documents?Access goes through administrator-created users and JWT login, and MCP tokens carry that JWT identity, so an agent only sees documents its user can read. Files stay in local storage with path traversal protection, and admins get audit log pages.
Can I recover a document I deleted by mistake?Yes — deletion is a soft delete with a recycle bin listing and restore, and both operations are restricted to the document owner. Whole folders and documents can also be copied across knowledge bases, including recursive folder copies.
How does an AI agent log in to the MCP service?Either put a long-lived access token in KBMCPTOKEN, or for local stdio clients omit it and call the authenticate tool once with your username and password — that short-lived session stays only in the MCP process memory. A /mcp-token.html page issues tokens without reading or storing your password.
Does it also have a plain REST API?Yes — the backend exposes a read-only REST API with OpenAPI endpoints and generated documentation at /docs. Remote MCP clients connect through an HTTPS reverse proxy with an Authorization: Bearer credential, and the repo also ships a knowledge-base Skill under skills/knowledge-base/.
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
25d
Commits · 90 Days