annotheca 0.1.0__py3-none-any.whl

annotheca/__init__.py

@@ -0,0 +1,3 @@
+"""Annotheca: a local reference manager for research projects."""
+
+__version__ = '0.1.0'

annotheca/__main__.py

@@ -0,0 +1,5 @@
+"""Allows `python -m annotheca`."""
+
+from annotheca import cli
+
+cli.main()

annotheca/api.py

@@ -0,0 +1,194 @@
+"""HTTP API and static web interface."""
+
+import mimetypes
+import pathlib
+from typing import Any
+from urllib import parse
+
+import fastapi
+import httpx
+import pydantic
+from fastapi import responses
+from fastapi import staticfiles
+
+from annotheca import bundle
+from annotheca import library as library_lib
+from annotheca import models
+from annotheca import sources
+
+_STATIC_DIR = pathlib.Path(__file__).parent / 'static'
+
+# Exception types mapped to an HTTP status and the error code the
+# interface translates for the user.
+_ERRORS = {
+    library_lib.NotFoundError: (404, 'not_found'),
+    library_lib.ConflictError: (409, 'name_taken'),
+    library_lib.InvalidPdfError: (422, 'not_pdf'),
+    bundle.InvalidBundleError: (422, 'not_bundle'),
+}
+
+
+class NameBody(pydantic.BaseModel):
+    name: models.Name
+
+
+class AddPapersBody(pydantic.BaseModel):
+    """Either pasted references or an already known paper to file."""
+    text: str | None = None
+    paper_id: int | None = None
+
+
+class NotesBody(pydantic.BaseModel):
+    notes: str
+
+
+class AnnotationChanges(pydantic.BaseModel):
+    color: models.Color | None = None
+    geometry: list[Any] | None = None
+    body: str | None = None
+
+
+def create_app(library: library_lib.Library,
+               client: httpx.Client | None = None) -> fastapi.FastAPI:
+    """Builds the web application.
+
+    Args:
+        library: Where everything is stored.
+        client: HTTP client for the scholarly sources; a default one is
+            created when omitted.
+    """
+    client = client or sources.make_client()
+    app = fastapi.FastAPI(title='Annotheca', docs_url=None, redoc_url=None)
+    api = fastapi.APIRouter(prefix='/api')
+
+    for error_type, (status, code) in _ERRORS.items():
+        app.add_exception_handler(error_type, _error_handler(status, code))
+
+    @app.exception_handler(sources.ResolveError)
+    def _resolve_error(request, error):
+        del request  # Unused.
+        return responses.JSONResponse({'detail': str(error)}, status_code=422)
+
+    @api.get('/projects')
+    def list_projects():
+        return library.list_projects()
+
+    @api.post('/projects', status_code=201)
+    def create_project(body: NameBody):
+        return library.create_project(body.name)
+
+    @api.get('/projects/{project_id}')
+    def get_project(project_id: int):
+        return library.get_project(project_id)
+
+    @api.get('/projects/{project_id}/bibtex')
+    def export_bibtex(project_id: int):
+        name, content = library.export_bibtex(project_id)
+        return _download(content, f'{name}.bib', 'application/x-bibtex')
+
+    @api.get('/projects/{project_id}/bundle')
+    def export_bundle(project_id: int):
+        """The project with its notes, annotations and PDFs, to share."""
+        name, content = bundle.export_project(library, project_id)
+        return _download(content, f'{name}.annotheca', 'application/zip')
+
+    @api.post('/projects/import', status_code=201)
+    async def import_bundle(request: fastapi.Request):
+        return bundle.import_project(library, await request.body())
+
+    @api.post('/projects/{project_id}/folders', status_code=201)
+    def create_folder(project_id: int, body: NameBody):
+        return library.create_folder(project_id, body.name)
+
+    @api.patch('/projects/{project_id}', status_code=204)
+    def rename_project(project_id: int, body: NameBody):
+        library.rename('project', project_id, body.name)
+
+    @api.delete('/projects/{project_id}', status_code=204)
+    def delete_project(project_id: int):
+        library.delete('project', project_id)
+
+    @api.patch('/folders/{folder_id}', status_code=204)
+    def rename_folder(folder_id: int, body: NameBody):
+        library.rename('folder', folder_id, body.name)
+
+    @api.delete('/folders/{folder_id}', status_code=204)
+    def delete_folder(folder_id: int):
+        library.delete('folder', folder_id)
+
+    @api.post('/folders/{folder_id}/papers')
+    def add_papers(folder_id: int, body: AddPapersBody):
+        """Files pasted references, or a known paper, in a folder."""
+        if body.paper_id is not None:
+            paper_ids = [body.paper_id]
+        elif body.text and body.text.strip():
+            entries = sources.resolve(body.text, client)
+            paper_ids = list(dict.fromkeys(map(library.add_paper, entries)))
+        else:
+            raise sources.ResolveError('unresolvable')
+        added = library.file_papers(folder_id, paper_ids)
+        return {'paper_ids': paper_ids, 'added': added,
+                'already_there': len(paper_ids) - added}
+
+    @api.put('/placements/{placement_id}/notes', status_code=204)
+    def set_notes(placement_id: int, body: NotesBody):
+        library.set_notes(placement_id, body.notes)
+
+    @api.delete('/placements/{placement_id}', status_code=204)
+    def remove_placement(placement_id: int):
+        library.remove_placement(placement_id)
+
+    @api.get('/papers/{paper_id}/pdf')
+    def get_pdf(paper_id: int):
+        path = library.pdf_path(paper_id)
+        if not path.exists():
+            raise library_lib.NotFoundError
+        return responses.FileResponse(path, media_type='application/pdf')
+
+    @api.put('/papers/{paper_id}/pdf', status_code=204)
+    async def upload_pdf(paper_id: int, request: fastapi.Request):
+        library.save_pdf(paper_id, await request.body())
+
+    @api.post('/papers/{paper_id}/pdf/fetch')
+    def fetch_pdf(paper_id: int):
+        """Looks for an open-access PDF; reports whether one was found."""
+        pdf = sources.find_pdf(library.get_paper(paper_id), client)
+        if pdf:
+            library.save_pdf(paper_id, pdf)
+        return {'found': pdf is not None}
+
+    @api.get('/placements/{placement_id}/annotations')
+    def list_annotations(placement_id: int):
+        return library.list_annotations(placement_id)
+
+    @api.post('/placements/{placement_id}/annotations', status_code=201)
+    def create_annotation(placement_id: int, body: models.Annotation):
+        return library.create_annotation(placement_id, body.model_dump())
+
+    @api.patch('/annotations/{annotation_id}')
+    def update_annotation(annotation_id: int, body: AnnotationChanges):
+        return library.update_annotation(
+            annotation_id, body.model_dump(exclude_none=True))
+
+    @api.delete('/annotations/{annotation_id}', status_code=204)
+    def delete_annotation(annotation_id: int):
+        library.delete_annotation(annotation_id)
+
+    app.include_router(api)
+    mimetypes.add_type('text/javascript', '.mjs')
+    app.mount('/', staticfiles.StaticFiles(directory=_STATIC_DIR, html=True))
+    return app
+
+
+def _download(content: str | bytes, filename: str,
+              media_type: str) -> responses.Response:
+    disposition = f"attachment; filename*=UTF-8''{parse.quote(filename)}"
+    return responses.Response(content, media_type=media_type,
+                              headers={'Content-Disposition': disposition})
+
+
+def _error_handler(status: int, code: str):
+    def handle(request: fastapi.Request, error: Exception):
+        del request, error  # Unused.
+        return responses.JSONResponse({'detail': code}, status_code=status)
+    return handle

annotheca/bibtex.py

@@ -0,0 +1,193 @@
+"""BibTeX entries: parsing, formatting, citation keys and identifiers."""
+
+import dataclasses
+import re
+import unicodedata
+from typing import Any
+
+_DOI_RE = re.compile(r'\b(10\.\d{4,9}/[^\s"<>{}]+)', re.IGNORECASE)
+_ARXIV_NEW_RE = re.compile(r'\b(\d{4}\.\d{4,5})(?:v\d+)?\b')
+_ARXIV_OLD_RE = re.compile(
+    r'arxiv(?:\.org/(?:abs|pdf)/|:)\s*([a-z-]+(?:\.[a-z]{2})?/\d{7})',
+    re.IGNORECASE)
+_ARXIV_DOI_PREFIX = '10.48550/arxiv.'
+_ENTRY_RE = re.compile(r'@\s*([a-zA-Z]+)\s*\{')
+_FIELD_NAME_RE = re.compile(r'\s*([^\s=,{}]+)\s*=\s*')
+_BARE_VALUE_RE = re.compile(r'[^\s,#}]*')
+_CONCATENATION_RE = re.compile(r'\s*#\s*')
+_SEPARATOR_RE = re.compile(r'\s*,')
+_IGNORED_TYPES = frozenset(('comment', 'preamble', 'string'))
+_LATEX_ACCENT_RE = re.compile(
+    r'\\([`\'^"~]|c(?=[\s{]))\s*\{?([a-zA-Z])\}?')
+_COMBINING_ACCENTS = {
+    '`': '\u0300', "'": '\u0301', '^': '\u0302', '~': '\u0303',
+    '"': '\u0308', 'c': '\u0327'}
+
+# Fields printed first, in this order; the others follow alphabetically.
+_FIELD_ORDER = ('author', 'title', 'journal', 'booktitle', 'year')
+# Fields naming where a paper was published, by preference.
+_VENUE_FIELDS = (
+    'journal', 'booktitle', 'publisher', 'howpublished', 'archiveprefix')
+_TITLE_STOPWORDS = frozenset(
+    ('a', 'an', 'the', 'on', 'of', 'for', 'in', 'to', 'and', 'with'))
+
+
+@dataclasses.dataclass
+class Entry:
+    """A single BibTeX entry.
+
+    Attributes:
+        entry_type: Lowercase entry type, e.g. 'article'.
+        citekey: The citation key.
+        fields: Field values keyed by lowercase field name.
+    """
+    entry_type: str
+    citekey: str
+    fields: dict[str, str]
+
+    @property
+    def doi(self) -> str | None:
+        """The normalized DOI, if the entry has one."""
+        return find_doi(self.fields.get('doi', ''))
+
+    @property
+    def arxiv_id(self) -> str | None:
+        """The arXiv identifier, from the DOI, eprint, URL or journal."""
+        doi = self.doi
+        if doi and doi.startswith(_ARXIV_DOI_PREFIX):
+            return doi.removeprefix(_ARXIV_DOI_PREFIX)
+        sources = ('eprint', 'url', 'journal', 'note')
+        return find_arxiv_id(
+            ' '.join(self.fields.get(name, '') for name in sources))
+
+    def summary(self) -> dict[str, Any]:
+        """The citation key, title, authors, year and venue, as plain text."""
+        venue = next((self.fields[name] for name in _VENUE_FIELDS
+                      if name in self.fields), '')
+        return {
+            'citekey': self.citekey,
+            'title': plain(self.fields.get('title', self.citekey)),
+            'authors': split_authors(self.fields.get('author', '')),
+            'year': self.fields.get('year', ''),
+            'venue': plain(venue),
+        }
+
+    @property
+    def title_key(self) -> str | None:
+        """The title as lowercase alphanumerics, used to spot duplicates."""
+        title = plain(self.fields.get('title', '')).lower()
+        return re.sub(r'[^a-z0-9]', '', title) or None
+
+
+def find_doi(text: str) -> str | None:
+    """Returns the first DOI found in `text`, lowercased, or None."""
+    match = _DOI_RE.search(text)
+    return match.group(1).rstrip('.,;)]').lower() if match else None
+
+
+def find_arxiv_id(text: str) -> str | None:
+    """Returns the first arXiv identifier found in `text`, or None."""
+    match = _ARXIV_NEW_RE.search(text) or _ARXIV_OLD_RE.search(text)
+    return match.group(1) if match else None
+
+
+def parse(text: str) -> list[Entry]:
+    """Parses every entry of a BibTeX string.
+
+    Macros are kept verbatim rather than expanded, e.g. `month = jun` gives
+    'jun'. Entries without a citation key are skipped.
+    """
+    entries = []
+    position = 0
+    while match := _ENTRY_RE.search(text, position):
+        end = _closing(text, match.end(), '}')
+        citekey, comma, body = text[match.end():end].partition(',')
+        entry_type = match.group(1).lower()
+        if comma and citekey.strip() and entry_type not in _IGNORED_TYPES:
+            entries.append(Entry(entry_type, citekey.strip(), _fields(body)))
+        position = end + 1
+    return entries
+
+
+def format_entry(entry: Entry) -> str:
+    """Formats an entry as BibTeX source."""
+    rank = {name: i for i, name in enumerate(_FIELD_ORDER)}
+    names = sorted(entry.fields, key=lambda n: (rank.get(n, len(rank)), n))
+    lines = [f'@{entry.entry_type}{{{entry.citekey},']
+    lines += [f'  {name} = {{{entry.fields[name]}}},' for name in names]
+    lines.append('}')
+    return '\n'.join(lines)
+
+
+def make_citekey(fields: dict[str, str]) -> str:
+    """Builds a Google Scholar style key such as 'vaswani2017attention'."""
+    authors = split_authors(fields.get('author', ''))
+    last_name = ''
+    if authors:
+        first = authors[0]
+        last_name = first.split(',')[0] if ',' in first else first.split()[-1]
+    title_words = re.findall(
+        r'[a-z0-9]+', _ascii(plain(fields.get('title', ''))))
+    word = next((w for w in title_words if w not in _TITLE_STOPWORDS), '')
+    key = _ascii(last_name) + fields.get('year', '').strip() + word
+    return re.sub(r'[^a-z0-9]', '', key) or 'ref'
+
+
+def split_authors(author_field: str) -> list[str]:
+    """Splits a BibTeX author field into plain author names."""
+    names = re.split(r'\s+and\s+', plain(author_field))
+    return [name.strip() for name in names if name.strip()]
+
+
+def plain(text: str) -> str:
+    """Strips the LaTeX braces, accents and escapes common in fields."""
+    text = _LATEX_ACCENT_RE.sub(
+        lambda m: m.group(2) + _COMBINING_ACCENTS[m.group(1)], text)
+    text = unicodedata.normalize('NFC', re.sub(r'\\([&%$#_])', r'\1', text))
+    return ' '.join(text.replace('{', '').replace('}', '').split())
+
+
+def _fields(text: str) -> dict[str, str]:
+    """Parses the `name = value` pairs of an entry body."""
+    fields = {}
+    position = 0
+    while match := _FIELD_NAME_RE.match(text, position):
+        parts = []
+        position = match.end()
+        while True:
+            if text.startswith(('{', '"'), position):
+                end = _closing(text, position + 1, '}' if text[position] == '{'
+                               else '"')
+                parts.append(text[position + 1:end])
+                position = end + 1
+            else:
+                bare = _BARE_VALUE_RE.match(text, position)
+                parts.append(bare.group())
+                position = bare.end()
+            concatenation = _CONCATENATION_RE.match(text, position)
+            if not concatenation:
+                break
+            position = concatenation.end()
+        fields[match.group(1).lower()] = ' '.join(''.join(parts).split())
+        if separator := _SEPARATOR_RE.match(text, position):
+            position = separator.end()
+    return fields
+
+
+def _closing(text: str, start: int, closer: str) -> int:
+    """Index of the first `closer` outside braces from `start`, or the end."""
+    depth = 0
+    for index in range(start, len(text)):
+        char = text[index]
+        if char == closer and depth == 0:
+            return index
+        if char == '{':
+            depth += 1
+        elif char == '}':
+            depth -= 1
+    return len(text)
+
+
+def _ascii(text: str) -> str:
+    decomposed = unicodedata.normalize('NFKD', text)
+    return decomposed.encode('ascii', 'ignore').decode().lower()

annotheca/bundle.py

@@ -0,0 +1,152 @@
+"""Project bundles: a whole project in one file, to share it.
+
+A bundle is a zip archive holding `project.json`, which describes the
+folders, papers, notes and annotations, and the PDFs as `pdfs/<citekey>.pdf`.
+"""
+
+import io
+import itertools
+import json
+import zipfile
+from typing import Any, Literal
+
+import pydantic
+
+from annotheca import bibtex
+from annotheca import library as library_lib
+from annotheca import models
+
+_MANIFEST = 'project.json'
+
+
+class InvalidBundleError(ValueError):
+    """The file is not an Annotheca project bundle."""
+
+
+class _Paper(pydantic.BaseModel):
+    citekey: str
+    entry_type: str
+    fields: dict[str, str]
+
+
+class _Placement(pydantic.BaseModel):
+    citekey: str
+    notes: str = ''
+    added_by: str = ''
+    annotations: list[models.Annotation] = []
+
+
+class _Folder(pydantic.BaseModel):
+    name: models.Name
+    placements: list[_Placement]
+
+
+class _Manifest(pydantic.BaseModel):
+    format: Literal['annotheca']
+    version: Literal[1]
+    name: models.Name
+    papers: list[_Paper]
+    folders: list[_Folder] = pydantic.Field(min_length=1)
+
+    @pydantic.model_validator(mode='after')
+    def _check_references(self) -> '_Manifest':
+        """Rejects bundles that could only be imported halfway."""
+        citekeys = {paper.citekey for paper in self.papers}
+        names = [folder.name for folder in self.folders]
+        if len(set(names)) < len(names) or any(
+                placement.citekey not in citekeys
+                for folder in self.folders for placement in folder.placements):
+            raise ValueError('Inconsistent bundle.')
+        return self
+
+
+def export_project(library: library_lib.Library,
+                   project_id: int) -> tuple[str, bytes]:
+    """Returns the name of a project and its bundle."""
+    project = library.get_project(project_id)
+    papers = {}
+    folders = []
+    for folder in project['folders']:
+        placements = []
+        for placement in folder['placements']:
+            paper_id = placement['paper_id']
+            if paper_id not in papers:
+                entry = library.get_paper(paper_id)
+                papers[paper_id] = _Paper(
+                    citekey=entry.citekey, entry_type=entry.entry_type,
+                    fields=entry.fields)
+            placements.append(_Placement(
+                citekey=papers[paper_id].citekey, notes=placement['notes'],
+                added_by=placement['added_by'],
+                annotations=library.list_annotations(placement['id'])))
+        folders.append(_Folder(name=folder['name'], placements=placements))
+    manifest = _Manifest(format='annotheca', version=1, name=project['name'],
+                         papers=list(papers.values()), folders=folders)
+
+    buffer = io.BytesIO()
+    with zipfile.ZipFile(buffer, 'w') as archive:
+        archive.writestr(_MANIFEST, manifest.model_dump_json(indent=1),
+                         compress_type=zipfile.ZIP_DEFLATED)
+        for paper_id, paper in papers.items():
+            if (path := library.pdf_path(paper_id)).exists():
+                archive.write(path, _pdf_name(paper.citekey))
+    return project['name'], buffer.getvalue()
+
+
+def import_project(library: library_lib.Library,
+                   data: bytes) -> dict[str, Any]:
+    """Creates a project from a bundle and returns its id and name.
+
+    Papers already in the library are reused, keeping their PDF. The project
+    name gets a number appended if it is already taken.
+
+    Raises:
+        InvalidBundleError: `data` is not a valid bundle.
+    """
+    try:
+        archive = zipfile.ZipFile(io.BytesIO(data))
+        manifest = _Manifest.model_validate(
+            json.loads(archive.read(_MANIFEST)))
+    except (zipfile.BadZipFile, KeyError, ValueError) as error:
+        raise InvalidBundleError from error
+
+    paper_ids = {}
+    for paper in manifest.papers:
+        paper_id = library.add_paper(
+            bibtex.Entry(paper.entry_type, paper.citekey, paper.fields))
+        paper_ids[paper.citekey] = paper_id
+        pdf_name = _pdf_name(paper.citekey)
+        if (pdf_name in archive.namelist()
+                and not library.pdf_path(paper_id).exists()):
+            library.save_pdf(paper_id, archive.read(pdf_name))
+
+    project = _create_project(library, manifest.name)
+    default_folder = library.get_project(project['id'])['folders'][0]
+    for index, folder in enumerate(manifest.folders):
+        if index == 0:
+            folder_id = default_folder['id']
+            library.rename('folder', folder_id, folder.name)
+        else:
+            folder_id = library.create_folder(project['id'], folder.name)['id']
+        for placement in folder.placements:
+            placement_id = library.file_paper(
+                folder_id, paper_ids[placement.citekey], placement.added_by)
+            library.set_notes(placement_id, placement.notes)
+            for annotation in placement.annotations:
+                library.create_annotation(placement_id, annotation.model_dump())
+    return project
+
+
+def _create_project(library: library_lib.Library,
+                    name: str) -> dict[str, Any]:
+    """Creates a project named `name`, or `name (2)`, `name (3)`..."""
+    for number in itertools.count(1):
+        try:
+            return library.create_project(
+                name if number == 1 else f'{name} ({number})')
+        except library_lib.ConflictError:
+            continue
+
+
+def _pdf_name(citekey: str) -> str:
+    return f'pdfs/{citekey}.pdf'

annotheca/cli.py

@@ -0,0 +1,122 @@
+"""Command line entry point.
+
+`annotheca` opens the interface; `annotheca mcp` serves the tools for AI
+assistants; `annotheca connect` makes those tools available to Claude.
+"""
+
+import argparse
+import json
+import os
+import pathlib
+import platform
+import shutil
+import socket
+import subprocess
+import sys
+import threading
+import webbrowser
+
+import uvicorn
+
+from annotheca import __version__
+from annotheca import api
+from annotheca import library
+from annotheca import mcp_server
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Runs the requested command."""
+    parser = argparse.ArgumentParser(
+        prog='annotheca',
+        description='Manage the bibliography of your research projects.')
+    parser.add_argument('--data-dir', type=pathlib.Path,
+                        help='where the library is stored (default: '
+                        f'{_default_data_dir()})')
+    parser.add_argument('--port', type=int, default=8737,
+                        help='local port of the interface (default: '
+                        '%(default)s)')
+    parser.add_argument('--no-browser', action='store_true',
+                        help='do not open the interface in a browser')
+    parser.add_argument('--version', action='version', version=__version__)
+    commands = parser.add_subparsers(dest='command', metavar='COMMAND')
+    commands.add_parser(
+        'mcp', help='serve the tools for AI assistants over MCP (stdio)')
+    commands.add_parser(
+        'connect', help='make the tools available to Claude Code and Claude '
+        'Desktop, and show how to add them to other assistants')
+    args = parser.parse_args(argv)
+
+    data_dir = args.data_dir or _default_data_dir()
+    if args.command == 'mcp':
+        mcp_server.create_server(library.Library(data_dir)).run()
+    elif args.command == 'connect':
+        _connect(args.data_dir)
+    else:
+        _serve(data_dir, args.port, open_browser=not args.no_browser)
+
+
+def _serve(data_dir: pathlib.Path, port: int, open_browser: bool) -> None:
+    url = f'http://127.0.0.1:{port}'
+    if _port_in_use(port):
+        print(f'Port {port} is busy: opening the running instance.'
+              ' Use --port if another program holds it.')
+        if open_browser:
+            webbrowser.open(url)
+        return
+    app = api.create_app(library.Library(data_dir))
+    print(f'Annotheca is running at {url} (library: {data_dir}).'
+          ' Press Ctrl+C to stop.')
+    if open_browser:
+        threading.Timer(1.0, webbrowser.open, [url]).start()
+    uvicorn.run(app, host='127.0.0.1', port=port, log_level='warning')
+
+
+def _connect(data_dir: pathlib.Path | None) -> None:
+    """Registers `annotheca mcp` with the Claude applications found."""
+    data_args = ['--data-dir', str(data_dir.resolve())] if data_dir else []
+    command = [sys.executable, '-m', 'annotheca', *data_args, 'mcp']
+    server = {'command': command[0], 'args': command[1:]}
+
+    if claude := shutil.which('claude'):
+        subprocess.run([claude, 'mcp', 'remove', '--scope', 'user',
+                        'annotheca'], capture_output=True, check=False)
+        subprocess.run([claude, 'mcp', 'add', '--scope', 'user', 'annotheca',
+                        '--', *command], capture_output=True, check=True)
+        print('Connected to Claude Code (all projects).')
+
+    config_path = _claude_desktop_config()
+    if config_path.parent.is_dir():
+        config = (json.loads(config_path.read_text())
+                  if config_path.exists() else {})
+        config.setdefault('mcpServers', {})['annotheca'] = server
+        config_path.write_text(json.dumps(config, indent=2) + '\n')
+        print('Connected to Claude Desktop; restart it to load the tools.')
+
+    print('\nFor other assistants (Cursor, Codex, Gemini CLI...), add this '
+          'MCP server to their configuration:\n'
+          + json.dumps({'mcpServers': {'annotheca': server}}, indent=2))
+
+
+def _claude_desktop_config() -> pathlib.Path:
+    if platform.system() == 'Darwin':
+        root = pathlib.Path.home() / 'Library' / 'Application Support'
+    elif platform.system() == 'Windows':
+        root = pathlib.Path(os.environ['APPDATA'])
+    else:
+        root = pathlib.Path(os.environ.get('XDG_CONFIG_HOME')
+                            or pathlib.Path.home() / '.config')
+    return root / 'Claude' / 'claude_desktop_config.json'
+
+
+def _default_data_dir() -> pathlib.Path:
+    """$ANNOTHECA_HOME, else the XDG data directory."""
+    if home := os.environ.get('ANNOTHECA_HOME'):
+        return pathlib.Path(home)
+    xdg = os.environ.get('XDG_DATA_HOME')
+    return pathlib.Path(xdg or pathlib.Path.home() / '.local' / 'share',
+                        'annotheca')
+
+
+def _port_in_use(port: int) -> bool:
+    with socket.socket() as probe:
+        return probe.connect_ex(('127.0.0.1', port)) == 0