frontmatter-mcp 0.2.0__tar.gz

frontmatter_mcp-0.2.0/.adr-dir

@@ -0,0 +1 @@
+docs/adr

frontmatter_mcp-0.2.0/.claude/settings.json

@@ -0,0 +1,22 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "make lint 2>&1 || true"
+          }
+        ]
+      }
+    ]
+  },
+  "permissions": {
+    "allow": [
+      "mcp__serena"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

frontmatter_mcp-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/ruff-action@v3
+        with:
+          args: check
+      - uses: astral-sh/ruff-action@v3
+        with:
+          args: format --check
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Set up Python
+        run: uv python install 3.11
+      - name: Install dependencies
+        run: uv sync --group dev
+      - name: Run tests
+        run: uv run python -m pytest

frontmatter_mcp-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,79 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Extract version from tag
+        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_ENV
+
+      - name: Wait for TestPyPI propagation
+        run: sleep 30
+
+      - name: Test install from TestPyPI
+        run: |
+          pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ frontmatter-mcp==${VERSION}
+          pip show frontmatter-mcp
+
+  publish-pypi:
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

frontmatter_mcp-0.2.0/.github/workflows/release-please.yml

@@ -0,0 +1,18 @@
+name: Release Please
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}

frontmatter_mcp-0.2.0/.gitignore

@@ -0,0 +1,28 @@
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Claude Code
+CLAUDE.local.md
+settings.local.json
+docs/workspace/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.ruff_cache/
+.pytest_cache/

frontmatter_mcp-0.2.0/.python-version

@@ -0,0 +1 @@
+3.11

frontmatter_mcp-0.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

frontmatter_mcp-0.2.0/.serena/.gitignore

@@ -0,0 +1 @@
+/cache

frontmatter_mcp-0.2.0/.serena/memories/code_style.md

@@ -0,0 +1,51 @@
+# Code Style and Conventions
+
+## Python Style
+
+- Formatter/Linter: Ruff
+- Quote style: Double quotes
+- Indent style: Spaces
+- Rules: E, F, I (isort), B (bugbear)
+
+## Type Hints
+
+- Use type hints for function signatures
+- Use `dict[str, Any]` style (Python 3.9+ syntax)
+- Use `list[str]` instead of `List[str]`
+
+## Docstrings
+
+- Use docstrings for public functions
+- Google-style format:
+  - Args:
+  - Returns:
+  - Notes:
+
+## Naming
+
+- Functions: snake_case
+- Classes: PascalCase
+- Constants: UPPER_SNAKE_CASE
+
+## Git Conventions
+
+### Commit Messages (Conventional Commits)
+
+| Type | Usage |
+|------|-------|
+| feat | New feature |
+| fix | Bug fix |
+| docs | Documentation only |
+| style | Code style changes |
+| refactor | Code refactoring |
+| test | Test additions/changes |
+| chore | Build/tool changes |
+
+### Branch Naming
+
+Pattern: `{type}/{description}`
+
+Examples:
+- `feat/rename-tools`
+- `fix/json-encoding`
+- `docs/update-readme`

frontmatter_mcp-0.2.0/.serena/memories/project_overview.md

@@ -0,0 +1,48 @@
+# Project Overview
+
+## Purpose
+
+frontmatter-mcp is an MCP (Model Context Protocol) server for querying and manipulating Markdown frontmatter using DuckDB SQL.
+
+## Tech Stack
+
+- Python 3.11+
+- FastMCP (MCP server framework)
+- DuckDB (SQL query engine)
+- python-frontmatter (YAML frontmatter parsing)
+- pyarrow (data interchange)
+- Hatchling (build backend)
+- Ruff (linting/formatting)
+- pytest (testing)
+- uv (package manager)
+
+## Codebase Structure
+
+```
+src/frontmatter_mcp/
+  __init__.py
+  server.py       # Main MCP server and tool definitions
+  frontmatter.py  # Frontmatter parsing utilities
+  query.py        # DuckDB query execution
+  schema.py       # Schema inspection
+
+tests/
+  test_server.py  # Integration tests
+
+docs/
+  workspace/      # Branch-specific work documents (gitignored)
+  adr/            # Architecture Decision Records
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| query_inspect | Get schema from frontmatter |
+| query | SQL query with DuckDB |
+| update | Update single file |
+| batch_update | Update multiple files |
+| batch_array_add | Add value to array property |
+| batch_array_remove | Remove value from array property |
+| batch_array_replace | Replace value in array property |
+| batch_array_sort | Sort array property |

frontmatter_mcp-0.2.0/.serena/memories/suggested_commands.md

@@ -0,0 +1,56 @@
+# Suggested Commands
+
+## Development
+
+```bash
+# Install dependencies
+uv sync
+
+# Run the MCP server
+uv run frontmatter-mcp --base-dir /path/to/markdown
+
+# Run tests
+make test
+# or
+uv run pytest tests -v
+
+# Lint
+make lint
+# or
+uv run ruff check src tests
+uv run ruff format --check src tests
+
+# Auto-fix lint issues
+make fix
+# or
+uv run ruff check --fix src tests
+uv run ruff format src tests
+```
+
+## Build & Publish
+
+```bash
+# Build package
+uv build
+
+# Publish to PyPI
+uv publish
+```
+
+## Git
+
+```bash
+# Branch naming: {type}/{description}
+# Types: feat, fix, docs, style, refactor, test, chore
+
+# Example
+git checkout -b feat/new-feature
+```
+
+## ADR (Architecture Decision Records)
+
+```bash
+adr new <title>
+adr list
+adr new -s <number> <title>  # Supersede existing ADR
+```

frontmatter_mcp-0.2.0/.serena/memories/task_completion.md

@@ -0,0 +1,34 @@
+# Task Completion Checklist
+
+## Before Committing
+
+1. Run linter and fix issues:
+   ```bash
+   make fix
+   ```
+
+2. Run tests:
+   ```bash
+   make test
+   ```
+
+3. Verify lint passes:
+   ```bash
+   make lint
+   ```
+
+## Workflow
+
+1. Create branch: `{type}/{description}`
+2. Create plan: `docs/workspace/{branch}/PLAN.md`
+3. Implement changes
+4. Create notes if needed: `docs/workspace/{branch}/NOTES_{YYYYMMDD_HHMMSS}.md`
+5. Create PR and merge
+
+## Documentation Rules
+
+- No emojis
+- No horizontal rules (`---`)
+- Keep concise, use lists/tables
+- No secrets/credentials in docs
+- No local paths (e.g., `/Users/username/`)

frontmatter_mcp-0.2.0/.serena/project.yml

@@ -0,0 +1,84 @@
+# list of languages for which language servers are started; choose from:
+#   al               bash             clojure          cpp              csharp           csharp_omnisharp
+#   dart             elixir           elm              erlang           fortran          go
+#   haskell          java             julia            kotlin           lua              markdown
+#   nix              perl             php              python           python_jedi      r
+#   rego             ruby             ruby_solargraph  rust             scala            swift
+#   terraform        typescript       typescript_vts   yaml             zig
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+# Special requirements:
+#   - csharp: Requires the presence of a .sln file in the project folder.
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- python
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# whether to use the project's gitignore file to ignore files
+# Added on 2025-04-07
+ignore_all_files_in_gitignore: true
+
+# list of additional paths to ignore
+# same syntax as gitignore, so you can use * and **
+# Was previously called `ignored_dirs`, please update your config if you are using that.
+# Added (renamed) on 2025-04-07
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+project_name: "frontmatter-mcp"
+included_optional_tools: []

frontmatter_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## [0.2.0](https://github.com/kzmshx/frontmatter-mcp/compare/v0.1.0...v0.2.0) (2025-11-29)
+
+
+### ⚠ BREAKING CHANGES
+
+* Tool names have changed
+    - inspect_frontmatter -> query_inspect
+    - query_frontmatter -> query
+    - update_frontmatter -> update
+
+### Features
+
+* add batch array tools for array property operations ([#6](https://github.com/kzmshx/frontmatter-mcp/issues/6)) ([04d46a9](https://github.com/kzmshx/frontmatter-mcp/commit/04d46a988400b58c5776728454f17a19a3ed976b))
+* add batch_update tool ([#5](https://github.com/kzmshx/frontmatter-mcp/issues/5)) ([a5b2bcf](https://github.com/kzmshx/frontmatter-mcp/commit/a5b2bcfb6b637444766518c1ac355c8531703f40))
+* add MIT License to the project ([4618791](https://github.com/kzmshx/frontmatter-mcp/commit/4618791cdae128494000d856eac90d4cad3fd353))
+* add update_frontmatter tool ([#1](https://github.com/kzmshx/frontmatter-mcp/issues/1)) ([d53b16b](https://github.com/kzmshx/frontmatter-mcp/commit/d53b16b376d9e49664e543701bd3491baec30af1))
+* implement MCP server with inspect and query tools ([c64a5cb](https://github.com/kzmshx/frontmatter-mcp/commit/c64a5cb438a9b4c5f5fcea14380a57f9f1eab7b0))
+* rename tools for better naming convention ([#4](https://github.com/kzmshx/frontmatter-mcp/issues/4)) ([1458c5f](https://github.com/kzmshx/frontmatter-mcp/commit/1458c5f57fcf90f9d72aff22d6e971b99d8a47d1))
+
+
+### Bug Fixes
+
+* output Unicode directly instead of escape sequences ([56c96d2](https://github.com/kzmshx/frontmatter-mcp/commit/56c96d298655fd30bd73535dccf0952870fde14b))
+* return dict instead of JSON string from tools ([#3](https://github.com/kzmshx/frontmatter-mcp/issues/3)) ([c34b399](https://github.com/kzmshx/frontmatter-mcp/commit/c34b3996e6b434b769127e65fc01cf3290a06238))
+
+
+### Documentation
+
+* add architecture decision records ([50c1809](https://github.com/kzmshx/frontmatter-mcp/commit/50c1809db4645de11c3be71a9d5e1a4b89a99cab))
+* add PR review commands to CLAUDE.md ([#10](https://github.com/kzmshx/frontmatter-mcp/issues/10)) ([1df3391](https://github.com/kzmshx/frontmatter-mcp/commit/1df33918dc70d0b233c36058946f43527e33e3e1))
+* add README with installation and usage guide ([790a313](https://github.com/kzmshx/frontmatter-mcp/commit/790a3138e207f7c906e98541d2516b52266a3c41))
+* add shared documentation rules to CLAUDE.md ([3aac2bb](https://github.com/kzmshx/frontmatter-mcp/commit/3aac2bb5fc93630baaaeeb05866eefc4c71c0dd1))
+* improve README with clear tool documentation ([40202c1](https://github.com/kzmshx/frontmatter-mcp/commit/40202c1f3400ecd31df11f114e0262e9940b6457))
+* translate all documentation to English ([1a24138](https://github.com/kzmshx/frontmatter-mcp/commit/1a241384b1e8da81aecec8a9fe859d0d13142b77))
+* update README with new tool names and batch tools ([#7](https://github.com/kzmshx/frontmatter-mcp/issues/7)) ([08c5ce7](https://github.com/kzmshx/frontmatter-mcp/commit/08c5ce7c8dd68462628912e4962cb53063f85323))
+
+## Changelog

frontmatter_mcp-0.2.0/CLAUDE.md

@@ -0,0 +1,89 @@
+# CLAUDE.md
+
+## Conventional Commits / ブランチ命名
+
+| type       | 用途                                                 |
+| ---------- | ---------------------------------------------------- |
+| `feat`     | 新機能                                               |
+| `fix`      | バグ修正                                             |
+| `docs`     | ドキュメントのみ                                     |
+| `style`    | コードの意味に影響しない変更（空白、フォーマット等） |
+| `refactor` | バグ修正でも機能追加でもないコード変更               |
+| `test`     | テストの追加・修正                                   |
+| `chore`    | ビルドプロセスやツールの変更                         |
+
+ブランチ名: `{type}/{description}` (例: `feat/rename-tools`, `fix/json-encoding`)
+
+## 開発ワークフロー
+
+1. ブランチを作成 (`{type}/{description}`)
+2. `docs/workspace/{branch}/PLAN.md` を作成
+3. ユーザーと PLAN.md の内容を確認・吟味してから実装開始
+4. 実装
+5. 作業一段落ごとに `NOTES_{YYYYMMDD_HHMMSS}.md` を作成
+6. PR 作成・マージ
+
+## PR レビュー対応
+
+| 操作             | コマンド                                                                                    |
+| ---------------- | ------------------------------------------------------------------------------------------- |
+| CI 状態確認      | `gh pr checks {n}`                                                                          |
+| コメント取得     | `gh api repos/{owner}/{repo}/pulls/{n}/comments`                                            |
+| コメントへの返信 | `gh api repos/{owner}/{repo}/pulls/{n}/comments/{comment_id}/replies -X POST -f body="..."` |
+
+修正後はコミットハッシュ付きでコメントに返信する。
+
+## ドキュメント構成
+
+### docs/workspace/{branch}/
+
+ブランチごとの作業ドキュメント。`.gitignore` に登録済み。
+
+構成:
+
+- `PLAN.md`: 機能仕様と実装タスク
+- `NOTES_{YYYYMMDD_HHMMSS}.md`: 作業ログ（発見、問題、解決策）。作業一段落ごとに作成
+
+### docs/adr/
+
+`adr` CLI（adr-tools）で管理する。Git 管理対象。
+
+- 新規作成: `adr new <タイトル>`
+- 一覧表示: `adr list`
+- 既存 ADR の置換: `adr new -s <番号> <タイトル>`
+
+## ドキュメント作成ルール
+
+### 共通ルール
+
+- 絵文字使用禁止
+- 区切り線 (`---`) 使用禁止
+
+### 共通記述スタイル
+
+- 簡潔に事実を記載
+- 不要な装飾や冗長な説明を避ける（可読性を重視しリストやテーブルは使って良い）
+- コードや設定は具体例を示す
+
+### セキュリティルール（重要）
+
+`docs/` 以下のドキュメントは Git 管理されるため、以下の情報は記載禁止:
+
+- 秘密鍵、トークン、パスワード
+- API キー、認証情報
+- 個人を特定可能な情報（氏名、メールアドレス、ユーザー名）
+- ローカル環境固有のパス（`/Users/username/` など）
+- プロジェクト ID やリソース名は記載可（例: `exp-batch-predictions`）
+- 具体的な設定値が必要な場合は `.env.example` などのテンプレートファイルを参照する
+- ローカル環境固有の情報は `CLAUDE.local.md` に記載する
+
+### docs/workspace/{branch}/PLAN.md ルール
+
+- h1 見出しは `# PLAN` とする
+- h2、h3、h4 は使用してよい（ただし過度な階層化は避ける）
+
+### docs/workspace/{branch}/NOTES_{YYYYMMDD_HHMMSS}.md ルール
+
+- h1 見出しはファイル名と同じにする（例: `# NOTES_20251129_094500`）
+- h3 以下は使わず、h2 見出し直下に要点を簡潔に記載
+- 参照リンクは各見出し内に記載

frontmatter_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 kzmshx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

frontmatter_mcp-0.2.0/Makefile

@@ -0,0 +1,17 @@
+.PHONY: help
+help: ## Show help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: lint
+lint: ## Run linter
+	uv run ruff check src tests
+	uv run ruff format --check src tests
+
+.PHONY: fix
+fix: ## Auto-fix lint issues
+	uv run ruff check --fix src tests
+	uv run ruff format src tests
+
+.PHONY: test
+test: ## Run tests
+	uv run pytest tests -v