# mdquery
Universal markdown querying tool with SQL-like syntax for searching and analyzing markdown files across different note-taking systems and static site generators.
## Table of Contents
- [mdquery](#mdquery)
- [Table of Contents](#table-of-contents)
- [🚀 Quick Start](#-quick-start)
- [📚 Documentation](#-documentation)
- [Project Structure](#project-structure)
- [Usage](#usage)
- [Command Line Interface](#command-line-interface)
- [Python API](#python-api)
- [✨ Key Features](#-key-features)
- [🔍 Quick Examples](#-quick-examples)
- [Find Research Notes](#find-research-notes)
- [Content Analysis](#content-analysis)
- [Cross-Reference Analysis](#cross-reference-analysis)
- [📋 Supported Markdown Systems](#-supported-markdown-systems)
- [🧪 Development](#-development)
- [Running Tests](#running-tests)
- [Requirements](#requirements)
- [Contributing](#contributing)
- [🆘 Need Help?](#-need-help)
- [📄 License](#-license)
## 🚀 Quick Start
### Command Line Usage
```bash
# Install
pip install -r requirements.txt
pip install -e .
# Index your notes
mdquery index /path/to/your/notes
# Query your notes
mdquery query "SELECT * FROM files WHERE tags LIKE '%research%'"
```
### AI Assistant Integration (MCP)
Use mdquery with AI assistants like Claude Desktop:
**Single Directory:**
```json
{
"mcpServers": {
"mdquery": {
"command": "python",
"args": ["-m", "mdquery.mcp_server"],
"env": {
"MDQUERY_NOTES_DIR": "/Users/username/Documents/Notes"
}
}
}
}
```
**Multiple Directories:**
```json
{
"mcpServers": {
"mdquery-personal": {
"command": "python",
"args": ["-m", "mdquery.mcp_server"],
"env": {
"MDQUERY_NOTES_DIR": "/Users/username/PersonalNotes"
}
},
"mdquery-work": {
"command": "python",
"args": ["-m", "mdquery.mcp_server"],
"env": {
"MDQUERY_NOTES_DIR": "/Users/username/WorkDocs"
}
}
}
}
```
Then ask your AI assistant: *"Analyze my markdown notes and find patterns in my research topics"*
## 📚 Documentation
| Resource | Description |
|----------|-------------|
| **[📖 Complete Documentation](docs/README.md)** | Full documentation hub with all guides |
| **[🎯 User Guide](docs/user-guide/README.md)** | Getting started, installation, and usage |
| **[📝 Query Syntax](docs/user-guide/query-syntax.md)** | Complete SQL syntax reference and examples |
| **[🔧 API Reference](docs/api/README.md)** | Developer API documentation |
| **[💡 Examples](docs/user-guide/examples/README.md)** | Real-world usage examples and workflows |
| **[⚡ Best Practices](docs/user-guide/best-practices.md)** | Performance tips and optimization |
## Project Structure
```
mdquery/
├── __init__.py # Package initialization and exports
├── models.py # Core data models (QueryResult, FileMetadata, ParsedContent)
├── indexer.py # File indexing engine
├── query.py # SQL query engine
├── cache.py # Cache management system
├── cli.py # Command-line interface
├── mcp.py # MCP server interface
└── parsers/
├── __init__.py # Parsers package initialization
├── frontmatter.py # Frontmatter parser
├── markdown.py # Markdown content parser
├── tags.py # Tag extraction parser
└── links.py # Link extraction parser
```
## Usage
### Command Line Interface
```bash
# Query markdown files
mdquery query "SELECT * FROM files WHERE tags LIKE '%research%'"
# Index a directory
mdquery index /path/to/notes --recursive
# View schema
mdquery schema --table files
```
### Python API
```python
from mdquery import QueryResult, FileMetadata, ParsedContent
from mdquery.query import QueryEngine
from mdquery.indexer import Indexer
# Initialize components
indexer = Indexer()
query_engine = QueryEngine()
# Index files and query
indexer.index_directory("/path/to/notes")
result = query_engine.execute_query("SELECT * FROM files")
```
## ✨ Key Features
- **Universal Compatibility**: Works with Obsidian, Joplin, Jekyll, and generic markdown
- **SQL-Like Queries**: Familiar syntax for powerful searches and analysis
- **Full-Text Search**: Fast content search with SQLite FTS5
- **Rich Metadata**: Query frontmatter, tags, links, and content structure
- **High Performance**: Efficient indexing and caching for large collections
- **Multiple Interfaces**: CLI tool and MCP server for AI integration
## 🔍 Quick Examples
### Find Research Notes
```sql
SELECT filename, tags FROM files
WHERE tags LIKE '%research%'
ORDER BY modified_date DESC;
```
### Content Analysis
```sql
SELECT tag, COUNT(*) as usage FROM tags
GROUP BY tag
ORDER BY usage DESC
LIMIT 10;
```
### Cross-Reference Analysis
```sql
SELECT f.filename, COUNT(l.link_target) as outgoing_links
FROM files f
JOIN links l ON f.id = l.file_id
WHERE l.is_internal = 1
GROUP BY f.id
ORDER BY outgoing_links DESC;
```
## 📋 Supported Markdown Systems
| System | Wikilinks | Nested Tags | Frontmatter | Collections |
|--------|-----------|-------------|-------------|-------------|
| **Obsidian** | ✅ `[[Page]]` | ✅ `#parent/child` | ✅ YAML | ✅ Folders |
| **Joplin** | ❌ | ❌ | ✅ Metadata | ✅ Notebooks |
| **Jekyll** | ❌ | ❌ | ✅ YAML | ✅ `_posts`, `_pages` |
| **Generic** | ❌ | ❌ | ✅ YAML | ✅ Directories |
## 🧪 Development
This project follows a structured implementation plan. See `.kiro/specs/mdquery/tasks.md` for the complete task list and implementation order.
### Running Tests
```bash
# Run all tests
python tests/run_comprehensive_tests.py
# Generate performance test data (1000+ files)
python tests/generate_performance_data.py
# Run specific test categories
python -m pytest tests/test_format_compatibility.py -v
```
## Requirements
- Python 3.8+
- SQLite3 (included with Python)
- Dependencies listed in requirements.txt
## Contributing
See the [documentation](docs/README.md) for complete guides on:
- [API Reference](docs/api/README.md) for developers
- [Examples](docs/user-guide/examples/README.md) for usage patterns
- [Best Practices](docs/user-guide/best-practices.md) for optimization
## 🆘 Need Help?
| Question | Resource |
|----------|----------|
| **How do I get started?** | [User Guide](docs/user-guide/README.md) |
| **What queries can I write?** | [Query Syntax Guide](docs/user-guide/query-syntax.md) |
| **How do I use the Python API?** | [API Reference](docs/api/README.md) |
| **Can you show me real examples?** | [Examples Collection](docs/user-guide/examples/README.md) |
| **How do I optimize performance?** | [Best Practices](docs/user-guide/best-practices.md) |
| **Does it work with my markdown system?** | [Supported Systems](#-supported-markdown-systems) |
## 📄 License
MIT License
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/mdquery",
"name": "mdquery",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "markdown, query, sql, search, obsidian, jekyll, static-site-generator",
"author": "mdquery",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/cb/87/906c400458ee0c6447dd4a2c6c2ecf641689ff003f6f5482a2f381c1758e/mdquery-0.4.0.tar.gz",
"platform": null,
"description": "# mdquery\n\nUniversal markdown querying tool with SQL-like syntax for searching and analyzing markdown files across different note-taking systems and static site generators.\n\n## Table of Contents\n\n- [mdquery](#mdquery)\n - [Table of Contents](#table-of-contents)\n - [\ud83d\ude80 Quick Start](#-quick-start)\n - [\ud83d\udcda Documentation](#-documentation)\n - [Project Structure](#project-structure)\n - [Usage](#usage)\n - [Command Line Interface](#command-line-interface)\n - [Python API](#python-api)\n - [\u2728 Key Features](#-key-features)\n - [\ud83d\udd0d Quick Examples](#-quick-examples)\n - [Find Research Notes](#find-research-notes)\n - [Content Analysis](#content-analysis)\n - [Cross-Reference Analysis](#cross-reference-analysis)\n - [\ud83d\udccb Supported Markdown Systems](#-supported-markdown-systems)\n - [\ud83e\uddea Development](#-development)\n - [Running Tests](#running-tests)\n - [Requirements](#requirements)\n - [Contributing](#contributing)\n - [\ud83c\udd98 Need Help?](#-need-help)\n - [\ud83d\udcc4 License](#-license)\n\n## \ud83d\ude80 Quick Start\n\n### Command Line Usage\n\n```bash\n# Install\npip install -r requirements.txt\npip install -e .\n\n# Index your notes\nmdquery index /path/to/your/notes\n\n# Query your notes\nmdquery query \"SELECT * FROM files WHERE tags LIKE '%research%'\"\n```\n\n### AI Assistant Integration (MCP)\n\nUse mdquery with AI assistants like Claude Desktop:\n\n**Single Directory:**\n```json\n{\n \"mcpServers\": {\n \"mdquery\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"mdquery.mcp_server\"],\n \"env\": {\n \"MDQUERY_NOTES_DIR\": \"/Users/username/Documents/Notes\"\n }\n }\n }\n}\n```\n\n**Multiple Directories:**\n```json\n{\n \"mcpServers\": {\n \"mdquery-personal\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"mdquery.mcp_server\"],\n \"env\": {\n \"MDQUERY_NOTES_DIR\": \"/Users/username/PersonalNotes\"\n }\n },\n \"mdquery-work\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"mdquery.mcp_server\"],\n \"env\": {\n \"MDQUERY_NOTES_DIR\": \"/Users/username/WorkDocs\"\n }\n }\n }\n}\n```\n\nThen ask your AI assistant: *\"Analyze my markdown notes and find patterns in my research topics\"*\n\n## \ud83d\udcda Documentation\n\n| Resource | Description |\n|----------|-------------|\n| **[\ud83d\udcd6 Complete Documentation](docs/README.md)** | Full documentation hub with all guides |\n| **[\ud83c\udfaf User Guide](docs/user-guide/README.md)** | Getting started, installation, and usage |\n| **[\ud83d\udcdd Query Syntax](docs/user-guide/query-syntax.md)** | Complete SQL syntax reference and examples |\n| **[\ud83d\udd27 API Reference](docs/api/README.md)** | Developer API documentation |\n| **[\ud83d\udca1 Examples](docs/user-guide/examples/README.md)** | Real-world usage examples and workflows |\n| **[\u26a1 Best Practices](docs/user-guide/best-practices.md)** | Performance tips and optimization |\n\n## Project Structure\n\n```\nmdquery/\n\u251c\u2500\u2500 __init__.py # Package initialization and exports\n\u251c\u2500\u2500 models.py # Core data models (QueryResult, FileMetadata, ParsedContent)\n\u251c\u2500\u2500 indexer.py # File indexing engine\n\u251c\u2500\u2500 query.py # SQL query engine\n\u251c\u2500\u2500 cache.py # Cache management system\n\u251c\u2500\u2500 cli.py # Command-line interface\n\u251c\u2500\u2500 mcp.py # MCP server interface\n\u2514\u2500\u2500 parsers/\n \u251c\u2500\u2500 __init__.py # Parsers package initialization\n \u251c\u2500\u2500 frontmatter.py # Frontmatter parser\n \u251c\u2500\u2500 markdown.py # Markdown content parser\n \u251c\u2500\u2500 tags.py # Tag extraction parser\n \u2514\u2500\u2500 links.py # Link extraction parser\n```\n\n## Usage\n\n### Command Line Interface\n\n```bash\n# Query markdown files\nmdquery query \"SELECT * FROM files WHERE tags LIKE '%research%'\"\n\n# Index a directory\nmdquery index /path/to/notes --recursive\n\n# View schema\nmdquery schema --table files\n```\n\n### Python API\n\n```python\nfrom mdquery import QueryResult, FileMetadata, ParsedContent\nfrom mdquery.query import QueryEngine\nfrom mdquery.indexer import Indexer\n\n# Initialize components\nindexer = Indexer()\nquery_engine = QueryEngine()\n\n# Index files and query\nindexer.index_directory(\"/path/to/notes\")\nresult = query_engine.execute_query(\"SELECT * FROM files\")\n```\n\n## \u2728 Key Features\n\n- **Universal Compatibility**: Works with Obsidian, Joplin, Jekyll, and generic markdown\n- **SQL-Like Queries**: Familiar syntax for powerful searches and analysis\n- **Full-Text Search**: Fast content search with SQLite FTS5\n- **Rich Metadata**: Query frontmatter, tags, links, and content structure\n- **High Performance**: Efficient indexing and caching for large collections\n- **Multiple Interfaces**: CLI tool and MCP server for AI integration\n\n## \ud83d\udd0d Quick Examples\n\n### Find Research Notes\n```sql\nSELECT filename, tags FROM files\nWHERE tags LIKE '%research%'\nORDER BY modified_date DESC;\n```\n\n### Content Analysis\n```sql\nSELECT tag, COUNT(*) as usage FROM tags\nGROUP BY tag\nORDER BY usage DESC\nLIMIT 10;\n```\n\n### Cross-Reference Analysis\n```sql\nSELECT f.filename, COUNT(l.link_target) as outgoing_links\nFROM files f\nJOIN links l ON f.id = l.file_id\nWHERE l.is_internal = 1\nGROUP BY f.id\nORDER BY outgoing_links DESC;\n```\n\n## \ud83d\udccb Supported Markdown Systems\n\n| System | Wikilinks | Nested Tags | Frontmatter | Collections |\n|--------|-----------|-------------|-------------|-------------|\n| **Obsidian** | \u2705 `[[Page]]` | \u2705 `#parent/child` | \u2705 YAML | \u2705 Folders |\n| **Joplin** | \u274c | \u274c | \u2705 Metadata | \u2705 Notebooks |\n| **Jekyll** | \u274c | \u274c | \u2705 YAML | \u2705 `_posts`, `_pages` |\n| **Generic** | \u274c | \u274c | \u2705 YAML | \u2705 Directories |\n\n## \ud83e\uddea Development\n\nThis project follows a structured implementation plan. See `.kiro/specs/mdquery/tasks.md` for the complete task list and implementation order.\n\n### Running Tests\n\n```bash\n# Run all tests\npython tests/run_comprehensive_tests.py\n\n# Generate performance test data (1000+ files)\npython tests/generate_performance_data.py\n\n# Run specific test categories\npython -m pytest tests/test_format_compatibility.py -v\n```\n\n## Requirements\n\n- Python 3.8+\n- SQLite3 (included with Python)\n- Dependencies listed in requirements.txt\n\n## Contributing\n\nSee the [documentation](docs/README.md) for complete guides on:\n- [API Reference](docs/api/README.md) for developers\n- [Examples](docs/user-guide/examples/README.md) for usage patterns\n- [Best Practices](docs/user-guide/best-practices.md) for optimization\n\n## \ud83c\udd98 Need Help?\n\n| Question | Resource |\n|----------|----------|\n| **How do I get started?** | [User Guide](docs/user-guide/README.md) |\n| **What queries can I write?** | [Query Syntax Guide](docs/user-guide/query-syntax.md) |\n| **How do I use the Python API?** | [API Reference](docs/api/README.md) |\n| **Can you show me real examples?** | [Examples Collection](docs/user-guide/examples/README.md) |\n| **How do I optimize performance?** | [Best Practices](docs/user-guide/best-practices.md) |\n| **Does it work with my markdown system?** | [Supported Systems](#-supported-markdown-systems) |\n\n## \ud83d\udcc4 License\n\nMIT License\n",
"bugtrack_url": null,
"license": null,
"summary": "Universal markdown querying tool with SQL-like syntax",
"version": "0.4.0",
"project_urls": {
"Homepage": "https://github.com/yourusername/mdquery"
},
"split_keywords": [
"markdown",
" query",
" sql",
" search",
" obsidian",
" jekyll",
" static-site-generator"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9b34d9c0f296cb3b77f9ea0376512308e24b0d9afb6d781655fed9d4c21c3a48",
"md5": "4e3d8af2f4caa9336b797751f221d70a",
"sha256": "3e97d6e44571542eb31a693b764c0a7a72ba6cbcc83261329259ac941123ea05"
},
"downloads": -1,
"filename": "mdquery-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4e3d8af2f4caa9336b797751f221d70a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 165008,
"upload_time": "2025-09-19T17:46:46",
"upload_time_iso_8601": "2025-09-19T17:46:46.174920Z",
"url": "https://files.pythonhosted.org/packages/9b/34/d9c0f296cb3b77f9ea0376512308e24b0d9afb6d781655fed9d4c21c3a48/mdquery-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cb87906c400458ee0c6447dd4a2c6c2ecf641689ff003f6f5482a2f381c1758e",
"md5": "9c1d6d0b505bb3195f22e25c19ad44ca",
"sha256": "4c17b140a8a3d4c942112af7fb0221bae137412f28b356fb453c087a1b6e9685"
},
"downloads": -1,
"filename": "mdquery-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "9c1d6d0b505bb3195f22e25c19ad44ca",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 152073,
"upload_time": "2025-09-19T17:46:47",
"upload_time_iso_8601": "2025-09-19T17:46:47.407656Z",
"url": "https://files.pythonhosted.org/packages/cb/87/906c400458ee0c6447dd4a2c6c2ecf641689ff003f6f5482a2f381c1758e/mdquery-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-19 17:46:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "mdquery",
"github_not_found": true,
"lcname": "mdquery"
}
JSON
