second-brain-joplin 0.1.0__tar.gz

second_brain_joplin-0.1.0/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,json,toml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

second_brain_joplin-0.1.0/.env.example

@@ -0,0 +1,5 @@
+# Joplin Data API token — found at Tools → Options → Web Clipper in Joplin Desktop
+JOPLIN_API_TOKEN=your-token-here
+
+# Joplin API base URL — default is fine unless you changed the port
+JOPLIN_BASE_URL=http://localhost:41184

second_brain_joplin-0.1.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,32 @@
+name: Bug
+description: An unexpected problem or incorrect behavior
+labels: ["needs-triage"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What was expected
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Package version
+      placeholder: "e.g. 0.1.0"
+  - type: textarea
+    id: env
+    attributes:
+      label: Environment
+      placeholder: "OS, Python version, Joplin version"

second_brain_joplin-0.1.0/.github/ISSUE_TEMPLATE/epic.yml

@@ -0,0 +1,24 @@
+name: Epic
+description: A large, multi-issue initiative
+labels: ["epic", "needs-triage"]
+body:
+  - type: textarea
+    id: goal
+    attributes:
+      label: Goal
+      description: What does this epic accomplish when all sub-issues are closed?
+    validations:
+      required: true
+  - type: textarea
+    id: sub-issues
+    attributes:
+      label: Sub-issues
+      description: List the issues that make up this epic (fill in after filing them).
+      placeholder: "- [ ] #1\n- [ ] #2"
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: How do we know this epic is done?
+    validations:
+      required: true

second_brain_joplin-0.1.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,27 @@
+name: Feature
+description: A request, idea, or new functionality
+labels: ["needs-triage"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / motivation
+      description: What problem does this solve, or what need does it address?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+    validations:
+      required: true

second_brain_joplin-0.1.0/.github/ISSUE_TEMPLATE/spike.yml

@@ -0,0 +1,25 @@
+name: Spike
+description: A time-boxed investigation that informs follow-on work
+labels: ["needs-triage"]
+body:
+  - type: textarea
+    id: question
+    attributes:
+      label: Question to answer
+      description: What do we need to know by the end of this spike?
+    validations:
+      required: true
+  - type: input
+    id: timebox
+    attributes:
+      label: Timebox
+      placeholder: "e.g. 2 hours, 1 day"
+    validations:
+      required: true
+  - type: textarea
+    id: output
+    attributes:
+      label: Expected output
+      description: What artifact or decision does this spike produce?
+    validations:
+      required: true

second_brain_joplin-0.1.0/.github/ISSUE_TEMPLATE/task.yml

@@ -0,0 +1,22 @@
+name: Task
+description: A specific, well-scoped piece of work (including docs and chores)
+labels: ["needs-triage"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: What needs to be done
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Done when
+      description: Clear, verifiable definition of done.
+    validations:
+      required: true
+  - type: textarea
+    id: notes
+    attributes:
+      label: Implementation notes
+      description: Relevant context, links, or constraints.

second_brain_joplin-0.1.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "github_actions"

second_brain_joplin-0.1.0/.github/labeler.yml

@@ -0,0 +1,23 @@
+component:joplin-api:
+  - src/second_brain_joplin/joplin_client.py
+
+component:mcp:
+  - src/second_brain_joplin/server.py
+  - src/second_brain_joplin/tools.py
+
+component:search:
+  - src/second_brain_joplin/search.py
+
+component:docs:
+  - docs/**
+  - "*.md"
+  - "!CONTRIBUTING.md"
+
+component:ci:
+  - .github/workflows/**
+  - .github/project.yml
+  - .github/labeler.yml
+  - pyproject.toml
+
+component:templates:
+  - templates/**

second_brain_joplin-0.1.0/.github/project.yml

@@ -0,0 +1,70 @@
+# Declarative PM spec for second-brain-joplin.
+# Applied manually via `gh` CLI or GitHub UI; no automated sync script at this stage.
+# See docs/project-management.md for how this spec is used.
+
+labels:
+  # component labels
+  - name: "component:joplin-api"
+    color: "0075ca"
+    description: "Joplin REST API client"
+  - name: "component:mcp"
+    color: "0075ca"
+    description: "MCP server and tool definitions"
+  - name: "component:search"
+    color: "0075ca"
+    description: "Semantic search and embeddings"
+  - name: "component:docs"
+    color: "0075ca"
+    description: "Documentation"
+  - name: "component:ci"
+    color: "0075ca"
+    description: "CI/CD and build"
+  - name: "component:templates"
+    color: "0075ca"
+    description: "Joplin note templates"
+
+  # phase labels
+  - name: "phase-0"
+    color: "e4e669"
+    description: "Bootstrap: repo scaffold, CI, package skeleton"
+  - name: "phase-1"
+    color: "e4e669"
+    description: "Core read MCP tools"
+  - name: "phase-2"
+    color: "e4e669"
+    description: "Semantic search"
+  - name: "phase-3"
+    color: "e4e669"
+    description: "Write workflow and publish"
+
+  # meta labels
+  - name: "epic"
+    color: "6f42c1"
+    description: "Multi-issue initiative"
+  - name: "backlog"
+    color: "d4c5f9"
+    description: "Unscheduled work"
+  - name: "needs-triage"
+    color: "e11d48"
+    description: "Not yet triaged"
+  - name: "blocked"
+    color: "b60205"
+    description: "Blocked by another issue or external dependency"
+  - name: "good first issue"
+    color: "7057ff"
+    description: "Good for newcomers"
+  - name: "help wanted"
+    color: "008672"
+    description: "Extra attention is needed"
+
+milestones:
+  - title: "v0.1 — Bootstrap"
+    description: "Repo scaffold, CI, package skeleton"
+  - title: "v0.2 — Core Read Tools"
+    description: "All read MCP tools working against Joplin REST API"
+  - title: "v0.3 — Semantic Search"
+    description: "Embedding index and semantic search tool"
+  - title: "v0.4 — Write Workflow"
+    description: "Human-gated note creation"
+  - title: "v1.0 — Publish"
+    description: "PyPI release, full docs, Joplin note templates"

second_brain_joplin-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync
+      - name: Ruff check
+        run: uv run ruff check src tests
+      - name: Ruff format check
+        run: uv run ruff format --check src tests
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync
+      - name: Run tests
+        run: uv run pytest --tb=short

second_brain_joplin-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release (PyPI)
+
+# Builds the sdist + wheel and publishes to PyPI via an OIDC trusted publisher
+# (no stored token). The trusted publisher is registered on https://pypi.org for
+# the `jomkz/second-brain-joplin` repo, workflow `release.yml`, environment
+# `pypi`. See docs/releasing.md.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Validate metadata
+        run: uvx twine check dist/*
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

second_brain_joplin-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+
+# Ruff / pytest cache
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Embeddings / local index (generated at runtime)
+.index/
+*.npy
+*.faiss
+
+# macOS
+.DS_Store
+
+# Editor
+.idea/
+.vscode/
+*.swp

second_brain_joplin-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+# Run `uv run pre-commit install` once to enable these on every commit.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.20
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

second_brain_joplin-0.1.0/.python-version

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

second_brain_joplin-0.1.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — Bootstrap
+
+Initial project skeleton — the MCP server starts and all tools are stubbed.
+
+### Added
+
+- `second-brain-joplin` CLI with a `serve` subcommand and `--version`.
+- FastMCP server exposing five stubbed tools (`joplin_overview`,
+  `joplin_search`, `joplin_read`, `joplin_recent`, `joplin_create`), each
+  returning a `{"status": "not implemented"}` payload.
+- `JoplinClient` skeleton with a working `ping()` against the Joplin Web Clipper
+  REST API; remaining methods stubbed for v0.2.
+- `.env` support via `python-dotenv` (`JOPLIN_API_TOKEN`, `JOPLIN_BASE_URL`).
+- Test suite with `pytest` + `respx`, and a 90% coverage gate.
+- uv-based toolchain, `uv.lock`, and CI (ruff lint + format check, pytest on
+  Python 3.11/3.12/3.13).
+- PyPI release workflow via OIDC trusted publishing.
+- Dependabot config; pre-commit, EditorConfig, and pinned Python version.
+- Documentation: install, notebook structure (PARA), project management,
+  releasing runbook, security policy, and an inspiration/reference note.
+
+[Unreleased]: https://github.com/jomkz/second-brain-joplin/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/jomkz/second-brain-joplin/releases/tag/v0.1.0

second_brain_joplin-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing
+
+Thanks for your interest in second-brain-joplin.
+
+## Development setup
+
+We use [uv](https://docs.astral.sh/uv/) as the primary toolchain:
+
+```bash
+git clone https://github.com/jomkz/second-brain-joplin
+cd second-brain-joplin
+uv sync
+uv run pre-commit install   # enable lint/format on commit
+```
+
+<details>
+<summary>pip fallback</summary>
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[test]"
+```
+</details>
+
+## Running tests
+
+```bash
+uv run pytest
+```
+
+Tests enforce a 90% coverage gate (configured in `pyproject.toml`).
+
+## Running the server locally
+
+```bash
+cp .env.example .env
+# Edit .env with your Joplin API token; it is loaded automatically via python-dotenv
+uv run second-brain-joplin serve
+```
+
+## Issue triage checklist
+
+See [docs/project-management.md](docs/project-management.md) for the full model
+(issue types, labels, milestones). Every triaged issue should have:
+
+1. **Issue type** — Epic / Feature / Task / Spike / Bug (set via sidebar)
+2. **Milestone** — which release it targets (or `backlog` label if unscheduled)
+3. One or more **`component:*`** labels
+4. **Phase label** if applicable (`phase-0` through `phase-3`)
+5. **Parent Epic** set as a sub-issue where relevant
+
+## Label conventions
+
+| Prefix | Values | Applied by |
+|---|---|---|
+| `component:` | `joplin-api`, `mcp`, `search`, `docs`, `ci`, `templates` | Maintainer (issues); labeler bot (PRs) |
+| `phase-` | `phase-0`, `phase-1`, `phase-2`, `phase-3` | Maintainer |
+| meta | `epic`, `backlog`, `needs-triage`, `blocked`, `good first issue`, `help wanted` | Maintainer |
+
+## Commit style
+
+No strict convention yet — use a short imperative summary line. DCO sign-off (`git commit -s`) is encouraged but not enforced at this stage.
+
+## Pull requests
+
+- Target `main`.
+- Keep PRs focused — one logical change per PR.
+- Add or update tests for any new behavior.
+- CI must pass before merge.

second_brain_joplin-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jomkz
+
+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.

second_brain_joplin-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: second-brain-joplin
+Version: 0.1.0
+Summary: MCP server that connects Claude Code (and other MCP clients) to your Joplin knowledge base
+Project-URL: Homepage, https://github.com/jomkz/second-brain-joplin
+Project-URL: Repository, https://github.com/jomkz/second-brain-joplin
+Project-URL: Issues, https://github.com/jomkz/second-brain-joplin/issues
+License: MIT
+License-File: LICENSE
+Keywords: ai,claude,joplin,knowledge-base,mcp,second-brain
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest-cov>=5.0; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Requires-Dist: respx>=0.21; extra == 'test'
+Description-Content-Type: text/markdown
+
+# second-brain-joplin
+
+An MCP server that turns your [Joplin](https://joplinapp.org/) knowledge base into searchable memory for any MCP-capable AI client — Claude Code, Cursor, and others.
+
+Inspired by [second-brain-mcp](https://github.com/noesskeetit/second-brain-mcp) (for Obsidian). This project covers the same use case for Joplin: your AI assistant reads, searches, and files notes directly, without leaving the tool you already use.
+
+> **Status:** Pre-alpha — MCP tools are stubbed. See the [roadmap](#roadmap) and open issues.
+
+---
+
+## How it works
+
+Joplin Desktop exposes a local REST API on `localhost:41184` (the Web Clipper service). This server wraps that API as MCP tools, so your AI client can query and update your notes in real time — no export step, no sync lag.
+
+```
+Claude Code / Cursor
+       │  MCP
+       ▼
+second-brain-joplin (this server)
+       │  HTTP + token
+       ▼
+Joplin Desktop (localhost:41184)
+       │
+       ▼
+Your notes
+```
+
+---
+
+## Prerequisites
+
+- **Joplin Desktop** running with the Web Clipper service enabled:  
+  **Tools → Options → Web Clipper → Enable Web Clipper Service**
+- **API token** — copy it from the Web Clipper settings panel
+- **Python ≥ 3.11** or [`uvx`](https://docs.astral.sh/uv/) (recommended — no install needed)
+
+---
+
+## Quickstart
+
+### Claude Code
+
+```bash
+claude mcp add -s user second-brain-joplin \
+  -e JOPLIN_API_TOKEN=your-token-here \
+  -- uvx second-brain-joplin serve
+```
+
+### Other MCP clients
+
+| Setting | Value |
+|---|---|
+| Command | `uvx second-brain-joplin serve` |
+| `JOPLIN_API_TOKEN` | token from Joplin Web Clipper settings |
+| `JOPLIN_BASE_URL` | `http://localhost:41184` (default) |
+
+See [docs/install.md](docs/install.md) for per-client setup guides.
+
+---
+
+## MCP Tools
+
+| Tool | Description | Writes? |
+|---|---|---|
+| `joplin_overview` | List all notebooks with note counts | No |
+| `joplin_search` | Keyword search across all notes | No |
+| `joplin_read` | Read a note by ID | No |
+| `joplin_recent` | Notes modified in the last N days | No |
+| `joplin_create` | Create a note (human-gated) | Yes |
+
+> All tools are stubbed in v0.1. Implementation tracked in [v0.2 milestone](https://github.com/jomkz/second-brain-joplin/milestone/2).
+
+---
+
+## vs. second-brain-mcp (Obsidian)
+
+| | [second-brain-mcp](https://github.com/noesskeetit/second-brain-mcp) | second-brain-joplin |
+|---|---|---|
+| Note app | Obsidian | Joplin |
+| Storage | Plain `.md` files on disk | Joplin REST API |
+| Requires app running | No | Yes (Joplin + Web Clipper) |
+| Semantic search | Yes (bge-m3) | Planned (v0.3) |
+| Write support | Human-gated | Human-gated (v0.4) |
+| Install | `uvx second-brain-mcp` | `uvx second-brain-joplin` |
+
+---
+
+## Notebook structure
+
+The [PARA method](https://fortelabs.com/blog/para/) works well with Joplin. See [docs/notebook-structure.md](docs/notebook-structure.md) for a recommended setup.
+
+---
+
+## Roadmap
+
+| Milestone | Theme | Status |
+|---|---|---|
+| [v0.1 — Bootstrap](https://github.com/jomkz/second-brain-joplin/milestone/1) | Repo, CI, package skeleton | Done |
+| [v0.2 — Core Read Tools](https://github.com/jomkz/second-brain-joplin/milestone/2) | All read MCP tools working | Planned |
+| [v0.3 — Semantic Search](https://github.com/jomkz/second-brain-joplin/milestone/3) | Embedding index, semantic search | Planned |
+| [v0.4 — Write Workflow](https://github.com/jomkz/second-brain-joplin/milestone/4) | Human-gated note creation | Planned |
+| [v1.0 — Publish](https://github.com/jomkz/second-brain-joplin/milestone/5) | PyPI, full docs, templates | Planned |
+
+---
+
+## Security & privacy
+
+This server keeps your notes local: it talks only to Joplin's Web Clipper REST API on `localhost` and runs on your own machine. Anything an MCP client can read, the connected AI can read — so apply least privilege and don't expose notebooks with credentials or other sensitive data. Note creation is planned as an explicit human-gated flow (v0.4); v0.1 does no silent writes. See [SECURITY.md](SECURITY.md) for details and how to report a vulnerability.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome — especially for testing against different Joplin versions and OS platforms.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).