项目简介

Theoria 是一个强大的神学研究平台，旨在帮助用户管理其个人数字图书馆（包括论文、笔记、YouTube视频转录和音频），自动规范圣经引文（OSIS格式），并提供结合语义和词法的高级搜索功能。它还集成了AI工作流，支持讲道准备、比较分析和灵修指导等任务，并严格引用来源。作为一个MCP服务器，Theoria能够以标准化的方式向大型语言模型（LLM）客户端提供丰富的神学上下文信息和功能。

主要功能点

混合搜索: 结合语义搜索和词法搜索，利用 pgvector 嵌入技术，实现精确和上下文相关的检索。
圣经锚定: 自动识别并标准化圣经引文为OSIS格式（如 'John.1.1'），并聚合语料库中所有相关经文片段。
AI工作流: 支持讲道准备、比较分析、多媒体洞察提取和灵修指南等，并提供严格的引用机制。
资源管理: 托管和管理用户上传的各种文档（PDF、DOCX、TXT、Markdown、网页、YouTube视频等）作为可供LLM访问的“资源”。
工具调用: 注册和执行各种“工具”，允许LLM客户端通过JSON-RPC协议调用这些外部功能来获取信息或执行操作。
会话管理与能力声明: 服务器负责管理与LLM客户端的会话，并声明其支持的功能和可用工具。
多传输协议支持: 支持Stdio、SSE和WebSocket等多种传输协议，提供安全、可扩展的上下文服务框架。

安装步骤

Theoria 支持通过 Python 环境直接运行，或使用 Docker Compose 部署。

前置条件:

Python 3.11 或更高版本
Node.js 20.x LTS 版本 (包含用于 Web 客户端的 npm)
(可选) Docker 和 Docker Compose (如果选择 Docker 部署方式)

Python 环境安装:

克隆仓库：'git clone https://github.com/dmedlin87/Theoria.git'
进入项目根目录：'cd Theoria'
创建并激活 Python 虚拟环境： 'python -m venv .venv' 'source .venv/bin/activate' (macOS/Linux) 或 '.venv\Scripts\activate' (Windows PowerShell)
安装 Python 依赖：'pip install -r requirements.txt'
(可选) 安装 Node.js 依赖 (如果需要运行 Web UI)： 'cd theo/services/web' 'npm install' 'cd ../../..'

数据库初始化 (SQLite 默认): 在项目根目录运行 API 服务时，会自动创建 SQLite 数据库并运行迁移。

API 认证配置: 在启动 API 前，需要配置认证。选择以下任一方式：

设置 API Key：'export THEO_API_KEYS='["your-api-key"]''
允许匿名访问 (仅限开发)：'export THEO_AUTH_ALLOW_ANONYMOUS=1'

服务器配置 (MCP客户端配置)

MCP客户端需要以下信息来连接 Theoria MCP 服务器。请注意，以下是客户端侧的配置示例，您不需要在服务器端修改代码。

{
  "server_name": "Theoria MCP Server",
  "command": "python",
  "args": [
    "-m",
    "mcp_server",
    "--host",
    "127.0.0.1",
    "--port",
    "8050"
  ],
  "env": {
    "MCP_TOOLS_ENABLED": "1",
    "THEO_AUTH_ALLOW_ANONYMOUS": "1"
  },
  "description": "连接到本地运行的 Theoria MCP 服务器，提供神学研究工具和上下文。",
  "notes": "根据您的部署方式，可以调整 --host 和 --port 参数。如果启用了认证，请配置相应的环境变量（例如 THEO_API_KEYS 或 THEO_AUTH_JWT_SECRET）。"
}

参数注释:

'server_name': 您为MCP服务器定义的名称。
'command': 启动MCP服务器的命令。通常是 'python'。
'args': 传递给命令的参数列表。
- '-m mcp_server': 运行 'mcp_server' 模块。
- '--host 127.0.0.1': MCP服务器绑定的主机地址。
- '--port 8050': MCP服务器监听的端口。
'env': 启动服务器进程时所需的环境变量。
- 'MCP_TOOLS_ENABLED: "1"': 必须设置，启用MCP工具功能。
- 'THEO_AUTH_ALLOW_ANONYMOUS: "1"': 如果没有配置API密钥或JWT，可以设置此项允许匿名访问 (仅用于开发/测试)。
'description': 对此MCP服务器的简要描述。
'notes': 额外的配置说明，例如认证方式。

基本使用方法

1. 启动主 API 服务 (可选，如果MCP服务器嵌入在API中): 在项目根目录：

'export THEO_API_KEYS='["your-api-key"]'' (或 'export THEO_AUTH_ALLOW_ANONYMOUS=1')
'uvicorn theo.services.api.app.main:app --reload --host 127.0.0.1 --port 8000' 这将启动主 FastAPI 服务，API 文档可在 'http://localhost:8000/docs' 查看。如果 'MCP_TOOLS_ENABLED=1' 环境变量已设置，MCP 服务器将嵌入在 'http://localhost:8000/mcp'。

2. 启动独立的 MCP 服务器: 在项目根目录，设置环境变量并运行：

'export MCP_TOOLS_ENABLED=1'
'export MCP_PORT=8050' (可选，默认就是 8050)
'export MCP_HOST=127.0.0.1' (可选，默认就是 127.0.0.1)
'python -m mcp_server' MCP 服务器将监听 'http://127.0.0.1:8050'。

3. 通过 Docker Compose 启动整个堆栈 (推荐): 在项目根目录的 'infra' 文件夹内：

'cd infra'
'docker compose up --build -d' 这将启动包括 PostgreSQL、Redis、API 和独立的 MCP 服务器在内的完整堆栈。
Web UI: 'http://localhost:3000'
API docs: 'http://localhost:8000/docs'
MCP Server: 'http://localhost:8050'

启动后，MCP客户端即可通过上述提供的配置信息连接到 Theoria MCP 服务器，利用其提供的资源和工具进行LLM应用开发。

关键词

项目简介

主要功能点

安装步骤

服务器配置 (MCP客户端配置)

基本使用方法

信息