Logseq API MCP服务器

用于Logseq API与动态工具发现集成的模型上下文协议服务器

](https://www.python.org/downloads/) ![MCP](https://modelcontextprotocol.io/) ![MIT License](LICENSE) ![UV](https://docs.astral.sh/uv/) ![Tests](https://github.com/gustavo-meilus/logseq-api-mcp/actions/workflows/test.yml) ![Quality](https://github.com/gustavo-meilus/logseq-api-mcp/actions/workflows/quality.yml) ![PR Validation](https://github.com/gustavo-meilus/logseq-api-mcp/actions/workflows/pr-validation.yml)

概述

Logseq API MCP服务器在模型上下文协议客户和 Logseq 知识库。该服务器使AI助手和其他MCP客户端能够与您的Logseq笔记进行交互，提取教育内容，分析知识关系，并通过一套全面的专业工具处理结构化信息。

🚀 关键创新：特点a 动态刀具发现系统 自动检测、导入和注册添加到中的任何新工具 src/tools/ 目录- 需要零配置!

非常适合：

📚 教育内容管理 -提取并整理抽认卡和学习材料
🎓 学习系统 -构建基于人工智能的学习助手和间隔重复工具
🔍 知识库分析 -在笔记中发现关系和模式
📊 内容发现 -在人工智能的帮助下浏览复杂的知识图
🧠 学术研究 -分析课程材料和学习资源

特性

🛠️ 核心工具（9个可用）

读取操作

get_all_pages -包含元数据的完整页面列表
get_page_blocks -分层块体结构分析
get_page_links -页面关系和引用发现
get_block_content -包含儿童的详细区块内容
get_all_page_content -全面的页面内容提取
get_linked_flashcards -高级抽认卡收集和分析

写入操作

append_block_in_page -将块附加到具有定位选项的页面
create_page -创建具有属性和格式的新页面
edit_block -使用内容、属性和光标控件编辑现有块

🔄 动态工具发现

自动发现 -自动从以下位置查找和导入工具 src/tools/
零配置 -无需手动导入或注册
即时集成 -新工具立即可用
CI验证 -自动化测试确保所有工具正常工作

🎯 针对AI/LLM消费进行了优化

干净的结构化输出 -表情包增强的分层格式
教育内容重点 -专业抽认卡和学习材料提取
综合元数据 -块ID、UUID、时间戳、属性和关系
智能内容组织 -自动分类和摘要生成
语言无关 -适用于任何Logseq知识库语言

安装

先决条件

Python 3.11+ -支持async/await的现代Python
紫外线 -快速Python包管理器和项目管理
正在运行Logseq实例 启用API时
Logseq API令牌 用于身份验证

快速设置

克隆仓库

   git clone https://github.com/gustavo-meilus/logseq-api-mcp.git
   cd logseq-api-mcp

使用uv进行安装

   uv sync

配置环境

   cp .env.template .env
   # Edit .env with your Logseq API details

启动服务器

   uv run mcp run src/server.py

配置

创建一个 .env 项目根目录中的文件：

# Logseq API Configuration
LOGSEQ_API_ENDPOINT=http://127.0.0.1:12315/api
LOGSEQ_API_TOKEN=your_api_token_here

获取您的Logseq API代币

打开Logseq应用程序
首选 设置→ 特性→ 开发者模式
启用 “HTTP API服务器”
复制显示的API令牌
请注意API端点（默认值： http://127.0.0.1:12315/api)
激活API

可用工具

工具	描述	输出	最适合
`get_all_pages`	列出所有包含基本元数据的页面	568页（135页期刊，433页常规）	导航、页面发现
`get_page_blocks`	分层块树结构	带ID、UUID的多级树	结构分析、导航
`get_page_links`	链接到目标页面的页面	使用元数据进行引用分析	关系发现
`get_block_content`	带孩子的详细区块信息	区块内容+直接孩子	深度内容分析
`get_all_page_content`	完整的页面内容+参考文献	链接源的完整内容	全面的内容审查
`get_linked_flashcards`	来自页面+链接页面的抽认卡	2页20张抽认卡	学习材料提取
`append_block_in_page`	将块附加到带有定位的页面	带有详细信息的成功确认	内容创建、组织
`create_page`	创建具有属性的新页面	页面创建确认	页面管理、结构
`edit_block`	完全控制编辑现有块	编辑更改确认	内容修改、更新

工具详细信息和示例

🗂️ `get_all_pages`

目的： 获取知识库中所有页面的干净列表

输出格式：

📊 LOGSEQ PAGES LISTING
📈 Total pages: 568
📅 Journal pages: 135
📄 Regular pages: 433

📄 REGULAR PAGES:
📄 Domain Driven Design (DDD) I | ID: 3460 | UUID: 682cfd19-7df6-46e0-a6f3-c09eca3b2530
📄 MBA Engenharia de Software | ID: 170 | UUID: 682fa28c-a3cc-47f2-ae65-7b7db57e1d67

使用案例：

知识库探索
页面库存和组织
按名称或元数据查找特定页面

______________________________________________________________________

🌳 `get_page_blocks`

目的： 获取任何页面的分层块结构

输入示例： "Domain Driven Design (DDD) I"

输出特性：

具有缩进级别的树结构
块ID、UUID和父子关系
属性提取和元数据
多级层次结构支持（最多8+级）

样本输出：

🌳 PAGE BLOCKS TREE STRUCTURE
📄 Page: Domain Driven Design (DDD) I (ID: 3460)
📊 Total blocks: 1

📋 tipo:: #aula curso:: [[MBA Engenharia de Software]]
   📊 ID:3544 | UUID:682cfd19-2826-46b7-8222-0821b11abc60 | Level:1
   👇 Children: 7

  H1 # Flashcards [heading: 1]
     📊 ID:3552 | UUID:682cfd19-4c9c-40dd-8cb1-c2625315b8ae | Level:2
     👇 Children: 10

______________________________________________________________________

🔗 `get_page_links`

目的： 查找链接到目标页面的所有页面

“领域驱动设计（DDD）I”的示例结果：

🔗 PAGE LINKS ANALYSIS
📄 Target Page: Domain Driven Design (DDD) I
📊 Found 1 pages linking to this page

📄 1. Domain Driven Design (DDD) II
   🔑 ID: 3588 | UUID: 682cfd19-3a24-4636-a5d5-c62ea57d352e
   📊 References: 1 | Journal: No
   ⚙️ Properties: relacionado: Domain Driven Design (DDD) I

应用：

发现相关内容和交叉引用
构建知识图谱和关系图
查找课程顺序和学习路径

______________________________________________________________________

🔍 `get_block_content`

目的： 获取特定区块及其直接子区块的详细信息

输入示例： 通用唯一标识符 682cfd19-3c3f-427c-a0be-c5a3a197ea20

输出：

🔍 MAIN BLOCK
📌 Block ID: 3465
🔑 UUID: 682cfd19-3c3f-427c-a0be-c5a3a197ea20

📝 CONTENT:
💡 Flashcard
Por que o DDD prioriza a colaboração entre desenvolvedores e especialistas do domínio? #card
+ [ ] Porque os especialistas do domínio são responsáveis apenas por aprovar a infraestrutura tecnológica.
+ [ ] Para garantir que o software seja construído com base no conhecimento profundo do domínio, reduzindo ambiguidades e erros.

👶 IMMEDIATE CHILDREN:
🔸 CHILD 1:
Resposta Correta: Para garantir que o software seja construído com base no conhecimento profundo do domínio, reduzindo ambiguidades e erros.

______________________________________________________________________

📖 `get_all_page_content`

目的： 从页面中提取全面的内容，包括属性、块和链接引用

主要特点：

完整的分层内容结构
属性提取和格式化
闪存卡识别和提取
链接引用分析
教育内容优化

示例摘要：

📖 Domain Driven Design (DDD) I
📊 1 blocks | 1 linked sources

📄 COMPREHENSIVE CONTENT:
📄 Page Properties [3544]
   📋 curso: MBA Engenharia de Software | tipo: aula | professor: Guilherme Bezerra de Lima

🎯 # Flashcards [3552]
   💡 Flashcard [3465]
      ❓ Q: Por que o DDD prioriza a colaboração entre desenvolvedores e especialistas do domínio?

______________________________________________________________________

✏️ `append_block_in_page`

目的： 通过精确的定位控制将新块附加到任何页面

主要特点：

定位选项 -在特定块之前、作为兄弟块或在页面末尾插入
页面级块 -支持页面级块创建
内容灵活性 -支持任何文本内容，包括markdown
即时反馈 -详细确认定位信息

示例用法：

# Basic block append
await append_block_in_page("My Page", "New content here")

# Positioned before specific block
await append_block_in_page("My Page", "Important note", before="block-uuid-123")

# As sibling of another block
await append_block_in_page("My Page", "Related content", sibling="block-uuid-456")

# Page-level block
await append_block_in_page("My Page", "Page property", is_page_block=True)

输出示例：

✅ **BLOCK APPENDED SUCCESSFULLY**
📄 Page: My Page
📝 Content: New content here
📍 Positioned: At the end of the page
🔗 **NEXT STEPS:**
• Check your Logseq graph to see the new block
• Use get_page_blocks to verify the block was added
• Use get_block_content to get details of the new block

______________________________________________________________________

📄 `create_page`

目的： 创建具有自定义属性和格式的新页面

主要特点：

属性支持 -添加自定义属性和元数据
格式选项 -支持markdown和org格式
日志检测 -自动日志页面识别
综合元数据 -整页实体信息

示例用法：

# Basic page creation
await create_page("New Page")

# With properties
properties = {"status": "active", "priority": "high"}
await create_page("Project Page", properties=properties)

# With format specification
await create_page("Org Page", format="org")

# Complete page with all options
await create_page("Complete Page", properties=properties, format="markdown")

输出示例：

✅ **PAGE CREATED SUCCESSFULLY**
📄 Page: New Page
⚙️ Properties set: 2 items
📝 Format: markdown
🔗 **NEXT STEPS:**
• Check your Logseq graph to see the new page
• Use get_all_pages to verify the page was created
• Use get_page_blocks to start adding content

______________________________________________________________________

✏️ `edit_block`

目的： 编辑现有块，完全控制内容、属性和行为

主要特点：

内容编辑 -通过预览修改块内容
物业管理 -添加、更新或删除块特性
光标控制 -将光标定位在特定位置
焦点管理 -编辑后控制块焦点

示例用法：

# Edit content only
await edit_block("block-uuid-123", content="Updated content")

# Update properties
properties = {"status": "completed", "priority": "high"}
await edit_block("block-uuid-123", properties=properties)

# Set cursor position and focus
await edit_block("block-uuid-123", cursor_position=10, focus=True)

# Complete edit with all options
await edit_block("block-uuid-123",
                content="New content",
                properties=properties,
                cursor_position=5,
                focus=True)

输出示例：

✅ **BLOCK EDITED SUCCESSFULLY**
🔑 Block UUID: block-uuid-123
📝 **UPDATED CONTENT:**

新内容

⚙️ **UPDATED PROPERTIES:**
• status: completed
• priority: high
📍 Cursor positioned at index 5
🎯 Focus: Enabled
🔗 **NEXT STEPS:**
• Check your Logseq graph to see the updated block
• Use get_block_content to verify the changes
• Continue editing or add more content

______________________________________________________________________

🧠 `get_linked_flashcards`

目的： 从目标页面和所有链接页面中全面提取抽认卡

“领域驱动设计（DDD）I”的真实示例结果：

🎯 LINKED FLASHCARDS ANALYSIS
📄 Target Page: Domain Driven Design (DDD) I
🔗 Searched 2 pages (target + 1 linked)
💡 Found 20 flashcards total

📚 Domain Driven Design (DDD) I (10 flashcards)
📚 Domain Driven Design (DDD) II (10 flashcards)

📊 SUMMARY:
• Total flashcards: 20
• Total answer blocks: 0
• Pages with flashcards: 2
• Average answers per flashcard: 0.0

高级功能：

多项选择题支持
答案块提取和链接
跨页闪存卡发现
教育元数据保存
学习系统集成就绪

使用示例

添加到您的Claude Desktop MCP设置(~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "logseq-api": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/logseq-api-mcp",
        "python",
        "src/server.py"
      ],
      "env": {
        "LOGSEQ_API_ENDPOINT": "http://127.0.0.1:12315/api",
        "LOGSEQ_API_TOKEN": "your_token_here"
      }
    }
  }
}

注：替换 /path/to/logseq-api-mcp 使用克隆存储库的实际路径。

发展

项目结构

logseq-api-mcp/
├── .github/
│   ├── workflows/             # GitHub Actions CI/CD
│   │   ├── test.yml           # Main test suite
│   │   ├── pr-validation.yml  # PR validation
│   │   ├── comprehensive-test.yml # Extended testing
│   │   └── quality.yml        # Code quality & security
│   ├── ISSUE_TEMPLATE/        # Issue templates
│   └── pull_request_template.md # PR template
├── src/
│   ├── server.py              # MCP server implementation
│   ├── registry.py            # Dynamic tool discovery & registration
│   └── tools/                 # Tool implementations (auto-discovered)
│       ├── __init__.py        # Dynamic tool importer
│       ├── get_all_pages.py   # Page listing tool
│       ├── get_page_blocks.py # Block structure tool
│       ├── get_page_links.py  # Page links tool
│       ├── get_block_content.py # Block detail tool
│       ├── get_all_page_content.py # Complete content tool
│       ├── get_linked_flashcards.py # Flashcard extraction tool
│       ├── append_block_in_page.py # Block creation tool
│       ├── create_page.py     # Page creation tool
│       └── edit_block.py      # Block editing tool
├── tests/
│   ├── conftest.py            # Shared test fixtures
│   ├── test_append_block_in_page.py # Block creation tests
│   ├── test_create_page.py    # Page creation tests
│   ├── test_edit_block.py     # Block editing tests
│   ├── test_get_tools.py      # Read operation tests
│   ├── test_mcp_server.py     # Server validation tests
│   ├── test_runner.py         # Test runner utility
│   └── TEST_SUMMARY.md        # Test documentation
├── pyproject.toml             # UV project configuration
├── .env.template              # Environment template
└── README.md                  # This file

开发设置

# Install with development dependencies
uv sync --dev

# Format code (auto-fixes issues)
uv run ruff check --fix && uv run ruff format

# Test server with MCP inspector
uv run mcp dev src/server.py

# Run server directly
uv run mcp run src/server.py

添加新工具

感谢the 动态发现系统，添加新工具非常简单：

1.创建工具文件

创建 src/tools/your_new_tool.py:

def your_new_tool(param: str) -> dict:
    """
    Your tool description here.

    Args:
        param: Description of parameter

    Returns:
        Dict with tool results
    """
    return {
        "result": f"Processed: {param}",
        "status": "success"
    }

2.就是这样！ 🎉

系统自动：

✅ 发现您的工具文件
✅ 进口作用
✅ 寄存器 它与MCP服务器
✅ 确认在CI测试中

工具要求

文件位置：必须在 src/tools/ 目录
功能可见性：不要以以下字符开头函数名 _
文件名称：不要以开头的文件名 _
文档：包括带有描述的文档字符串
键入提示：用于更好的IDE支持

动态发现过程

New Tool File → Auto-Scan → Import → Registration → Validation

自动扫描: src/tools/__init__.py 扫描目录 .py 文件
导入：动态导入所有公共函数
注册: src/registry.py 在MCP服务器上自动注册
验证：测试自动验证工具是否存在

测试

自动化测试

该项目包括全面的自动化测试 68个测试用例 涵盖所有功能：

# Run the full test suite
uv run pytest tests/ --cov=src/tools --cov-report=html

# Run specific tool tests
uv run python tests/test_runner.py --tool append_block_in_page
uv run python tests/test_runner.py --tool create_page
uv run python tests/test_runner.py --tool edit_block

# Run server validation
uv run python tests/test_mcp_server.py

测试覆盖范围：

✅ 68个测试用例 -全面覆盖所有9种工具
✅ 服务器运行状况 -确保MCP服务器正确启动
✅ 工具发现 -验证自动刀具检测
✅ 动态注册 -确认所有工具均已注册
✅ 写入操作 -附加、创建和编辑工具的测试
✅ 读取操作 -所有get\_\*工具的测试
✅ 错误处理 -HTTP错误、网络问题、边缘情况
✅ CI集成 -在所有提交时自动运行
✅ 覆盖范围报告 -最低覆盖率要求为80%

手动测试

# Test with MCP Inspector (interactive)
uv run mcp dev src/server.py

# Direct server testing
uv run mcp run src/server.py

测试输出示例

🔍 Testing MCP Server Health and Tools...
🔧 Discovered tools (auto-discovery): ['append_block_in_page', 'create_page', 'edit_block', 'get_all_page_content', 'get_all_pages', 'get_block_content', 'get_linked_flashcards', 'get_page_blocks', 'get_page_links']

🏥 Testing server health...
✅ Server started and responded successfully
✅ Dynamic tool discovery working correctly

🎉 MCP Server test completed successfully!
   📊 Tools auto-discovered: 9
   🏥 Server health: OK
   🔄 Dynamic discovery: OK

CI/CD管道

该项目包括一个全面的CI/CD管道，包括自动测试、代码质量检查和安全扫描。

🚀 自动化工作流程

拉取请求验证

✅ 测试覆盖率 -最低覆盖率要求为80%
✅ 代码质量 -Ruff linting和MyPy类型检查
✅ 安全扫描 -土匪安全分析
✅ 工具发现 -自动化工具验证
✅ MCP服务器测试 -服务器启动和功能测试

主测试套件

✅ 多Python测试 -Python 3.11、3.12和3.13
✅ 交叉平台的 -Ubuntu、Windows和macOS
✅ 性能测试 -内存使用和测试持续时间
✅ 集成测试 -带工具的真正MCP服务器

代码质量与安全

✅ 每日安全扫描 -自动漏洞检测
✅ 依赖检查 -安全和许可证验证
✅ 代码规范 -自动格式化和linting
✅ 秘密侦查 -硬编码凭证扫描

📊 质量门

所有工作流都必须通过：

✅ 要合并到main的代码
✅ 待发布的新闻稿
✅ 待批准的PR

🔧 局部测试

在本地运行相同的检查：

# Install dependencies
uv sync --dev

# Run tests with coverage
uv run pytest tests/ --cov=src/tools --cov-report=html

# Run linting
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/

# Run type checking
uv run mypy src/ --ignore-missing-imports

# Run security scan
uv run bandit -r src/

# Run dependency check
uv run safety check

📈 覆盖范围要求

最低覆盖范围： 80%用于PR验证
目标覆盖范围： 85%用于综合测试
覆盖工具： pytest-cov与HTML和XML报告

🛡️ 安全特性

匪徒 -Python安全linter
安全 -依赖漏洞扫描程序
秘密侦查 -硬编码凭证检测
许可证检查 -依赖许可证验证

贡献

我们跟随 GitHub Flow 对于所有的贡献。看贡献.md 了解完整细节。

快速开始

复刻仓库
创建要素分支

   git checkout -b feature/add-search-tool

创建您的工具 （只需添加文件-自动集成！）

   # Create src/tools/search_tool.py with your function

格式和测试

   uv run ruff check --fix && uv run ruff format
   uv run python tests/test_mcp_server.py

承诺并推动

   git commit -m "feat: add search tool for content discovery"
   git push origin feature/add-search-tool

打开拉取请求

开发效益

零配置 -无需手动导入或注册
即时反馈 -工具在创建后立即工作
自动验证 -CI测试验证一切正常
整洁架构 -动态系统使代码保持有序
综合测试 -68个测试用例，覆盖率80%
质量保证 -自动检测、类型检查和安全
CI/CD管道 -对每个PR和推送进行自动测试

代码质量标准

Python 3.11+ 采用现代async/await模式
PEP 8 通过Ruff格式实现合规性
键入提示 更好的IDE支持
错误处理 具有全面的异常管理
环境变量 用于配置
模块化设计 动态刀具加载

文档和资源

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

致谢

模型上下文协议卓越的协议规范
Logseq 强大的知识管理平台
MCP Python SDK 稳健的开发框架
紫外线用于现代Python包管理

______________________________________________________________________

专为Logseq和MCP社区设计

Logseq API MCP

快速接入

详细介绍

Logseq API MCP服务器

目录

概述

特性

🛠️ 核心工具（9个可用）

读取操作

写入操作

🔄 动态工具发现

🎯 针对AI/LLM消费进行了优化

安装

先决条件

快速设置

配置

获取您的Logseq API代币

可用工具

工具详细信息和示例

🗂️ get_all_pages

🌳 get_page_blocks

🔗 get_page_links

🔍 get_block_content

📖 get_all_page_content

✏️ append_block_in_page

📄 create_page

✏️ edit_block

🧠 get_linked_flashcards

使用示例

发展

项目结构

开发设置

添加新工具

1.创建工具文件

2.就是这样！ 🎉

工具要求

动态发现过程

测试

自动化测试

手动测试

测试输出示例

CI/CD管道

🚀 自动化工作流程

拉取请求验证

主测试套件

代码质量与安全

📊 质量门

🔧 局部测试

📈 覆盖范围要求

🛡️ 安全特性

贡献

快速开始

开发效益

代码质量标准

文档和资源

许可证

致谢

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

🗂️ `get_all_pages`

🌳 `get_page_blocks`

🔗 `get_page_links`

🔍 `get_block_content`

📖 `get_all_page_content`

✏️ `append_block_in_page`

📄 `create_page`

✏️ `edit_block`

🧠 `get_linked_flashcards`