webcal-mcp 0.1.1__tar.gz

webcal_mcp-0.1.1/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) Mark Nottingham
+
+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.

webcal_mcp-0.1.1/MANIFEST.in

@@ -0,0 +1,8 @@
+global-include py.typed
+prune build
+prune dist
+prune test
+prune tools
+prune src
+prune *.egg-info
+exclude .gitignore .editorconfig .dockerignore .coveragerc

webcal_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: webcal-mcp
+Version: 0.1.1
+Summary: MCP server exposing a remote iCalendar (webcal) feed as queryable read-only tools
+Author-email: Mark Nottingham <mnot@mnot.net>
+License-Expression: MIT
+Project-URL: homepage, https://github.com/mnot/webcal-mcp
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: mcp>=1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: icalendar>=5.0
+Requires-Dist: recurring-ical-events>=2.2
+Requires-Dist: python-dateutil>=2.8
+Provides-Extra: dev
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-md; extra == "dev"
+Requires-Dist: validate-pyproject; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: types-python-dateutil; extra == "dev"
+Dynamic: license-file
+
+# webcal-mcp
+
+A small read-only [Model Context Protocol](https://modelcontextprotocol.io/) server
+that exposes one or more remote iCalendar feeds (the `webcal://` or `.ics` kind)
+as queryable tools for an LLM agent.
+
+## Install
+
+```
+pipx install webcal-mcp
+```
+
+Or from a checkout:
+
+```
+pipx install .
+```
+
+This puts a `webcal-mcp` script on your `PATH`. Python 3.10 or later is required.
+
+## Configure
+
+Create `~/.config/webcal-mcp/config.toml` (or point `WEBCAL_MCP_CONFIG` at any
+other path). See `config.example.toml`:
+
+```toml
+default_ttl_seconds = 900
+
+[calendars.personal]
+url = "webcal://example.com/personal.ics"
+description = "Personal calendar"
+
+[calendars.work]
+url = "https://example.com/work.ics"
+description = "Work calendar"
+```
+
+`webcal://` and `webcals://` URLs are normalized to `https://`.
+
+## Run
+
+```
+webcal-mcp
+```
+
+The server speaks MCP over stdio. Wire it into an MCP-aware client (Claude
+Desktop, Claude Code, etc.) by pointing at the `webcal-mcp` script. For
+example, for Claude Code:
+
+```
+claude mcp add webcal -- webcal-mcp
+```
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `list_calendars` | Names, descriptions, capability flags for the configured calendars. |
+| `list_events` | Events in a date range, with optional `query`, `categories`, `location` filters and `brief` / `full` / `markdown` detail modes. Either bound may be omitted for open-ended windows. |
+| `events_on` | All events occurring on a given date. |
+| `get_event` | Full record for a single UID. |
+
+Recurring events are expanded within the requested window. Responses are
+cached in memory with a per-calendar TTL; revalidation uses HTTP `ETag` and
+`Last-Modified`.
+
+## Read-only
+
+Calendars are read-only today. The `CalendarSource` abstraction reserves a
+`writable` capability flag so future write-capable backends can be added
+without changing the tool surface.

webcal_mcp-0.1.1/README.md

@@ -0,0 +1,71 @@
+# webcal-mcp
+
+A small read-only [Model Context Protocol](https://modelcontextprotocol.io/) server
+that exposes one or more remote iCalendar feeds (the `webcal://` or `.ics` kind)
+as queryable tools for an LLM agent.
+
+## Install
+
+```
+pipx install webcal-mcp
+```
+
+Or from a checkout:
+
+```
+pipx install .
+```
+
+This puts a `webcal-mcp` script on your `PATH`. Python 3.10 or later is required.
+
+## Configure
+
+Create `~/.config/webcal-mcp/config.toml` (or point `WEBCAL_MCP_CONFIG` at any
+other path). See `config.example.toml`:
+
+```toml
+default_ttl_seconds = 900
+
+[calendars.personal]
+url = "webcal://example.com/personal.ics"
+description = "Personal calendar"
+
+[calendars.work]
+url = "https://example.com/work.ics"
+description = "Work calendar"
+```
+
+`webcal://` and `webcals://` URLs are normalized to `https://`.
+
+## Run
+
+```
+webcal-mcp
+```
+
+The server speaks MCP over stdio. Wire it into an MCP-aware client (Claude
+Desktop, Claude Code, etc.) by pointing at the `webcal-mcp` script. For
+example, for Claude Code:
+
+```
+claude mcp add webcal -- webcal-mcp
+```
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `list_calendars` | Names, descriptions, capability flags for the configured calendars. |
+| `list_events` | Events in a date range, with optional `query`, `categories`, `location` filters and `brief` / `full` / `markdown` detail modes. Either bound may be omitted for open-ended windows. |
+| `events_on` | All events occurring on a given date. |
+| `get_event` | Full record for a single UID. |
+
+Recurring events are expanded within the requested window. Responses are
+cached in memory with a per-calendar TTL; revalidation uses HTTP `ETag` and
+`Last-Modified`.
+
+## Read-only
+
+Calendars are read-only today. The `CalendarSource` abstraction reserves a
+`writable` capability flag so future write-capable backends can be added
+without changing the tool surface.

webcal_mcp-0.1.1/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "webcal-mcp"
+dynamic = ["version"]
+authors = [
+    {name="Mark Nottingham", email="mnot@mnot.net"}
+]
+description = "MCP server exposing a remote iCalendar (webcal) feed as queryable read-only tools"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE.md"]
+classifiers = [
+    "Operating System :: OS Independent",
+    "Development Status :: 4 - Beta"
+]
+dependencies = [
+    "mcp>=1.0",
+    "httpx>=0.27",
+    "icalendar>=5.0",
+    "recurring-ical-events>=2.2",
+    "python-dateutil>=2.8",
+]
+
+[project.optional-dependencies]
+dev = ["mypy", "black", "isort", "pylint", "pytest", "pytest-asyncio", "pytest-md", "validate-pyproject", "build", "types-python-dateutil"]
+
+[project.urls]
+homepage = "https://github.com/mnot/webcal-mcp"
+
+[project.scripts]
+webcal-mcp = "webcal_mcp.server:main"
+
+
+[build-system]
+requires = [
+    "setuptools>=82.0.1",
+    "wheel"
+]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.dynamic]
+version = {attr = "webcal_mcp.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["webcal_mcp", "webcal_mcp.*"]
+exclude = ["build*", "dist*"]
+namespaces = false
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-data]
+webcal_mcp = ["py.typed"]
+
+# Most tool configuration lives in dedicated files (managed by the template):
+#   mypy   → mypy.ini
+#   pylint → .pylintrc
+#   isort  → .isort.cfg
+# Black is the exception: it only reads pyproject.toml, so its config
+# stays here and is project-owned.
+
+[tool.black]
+line-length = 100
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

webcal_mcp-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

webcal_mcp-0.1.1/tests/test_config.py

@@ -0,0 +1,83 @@
+"""Tests for config loading and URL normalization."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from textwrap import dedent
+
+import pytest
+
+from webcal_mcp.config import CalendarConfig, load_config
+
+
+def _write(tmp_path: Path, body: str) -> Path:
+    path = tmp_path / "config.toml"
+    path.write_text(dedent(body))
+    return path
+
+
+def test_loads_multiple_calendars(tmp_path: Path) -> None:
+    cfg = load_config(
+        _write(
+            tmp_path,
+            """\
+            default_ttl_seconds = 600
+
+            [calendars.personal]
+            url = "https://example.com/p.ics"
+            description = "Personal"
+
+            [calendars.work]
+            url = "webcal://example.com/w.ics"
+            ttl_seconds = 1800
+            """,
+        )
+    )
+    assert set(cfg.calendars) == {"personal", "work"}
+    assert cfg.calendars["personal"].ttl_seconds == 600  # inherits default
+    assert cfg.calendars["work"].ttl_seconds == 1800
+    assert cfg.default_calendar is None  # ambiguous with two calendars
+
+
+def test_single_calendar_is_default(tmp_path: Path) -> None:
+    cfg = load_config(
+        _write(
+            tmp_path,
+            """\
+            [calendars.only]
+            url = "https://example.com/o.ics"
+            """,
+        )
+    )
+    assert cfg.default_calendar == "only"
+
+
+def test_missing_url_rejected(tmp_path: Path) -> None:
+    with pytest.raises(ValueError, match="missing 'url'"):
+        load_config(
+            _write(
+                tmp_path,
+                """\
+                [calendars.bad]
+                description = "no url"
+                """,
+            )
+        )
+
+
+def test_no_calendars_rejected(tmp_path: Path) -> None:
+    with pytest.raises(ValueError, match="No \\[calendars"):
+        load_config(_write(tmp_path, "default_ttl_seconds = 60\n"))
+
+
+@pytest.mark.parametrize(
+    "url,expected",
+    [
+        ("webcal://example.com/x.ics", "https://example.com/x.ics"),
+        ("webcals://example.com/x.ics", "https://example.com/x.ics"),
+        ("https://example.com/x.ics", "https://example.com/x.ics"),
+        ("http://example.com/x.ics", "http://example.com/x.ics"),
+    ],
+)
+def test_http_url_normalization(url: str, expected: str) -> None:
+    assert CalendarConfig(name="c", url=url).http_url == expected

webcal_mcp-0.1.1/tests/test_fetcher.py

@@ -0,0 +1,131 @@
+"""Tests for IcsHttpSource caching behaviour using httpx MockTransport."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+import httpx
+import pytest
+
+from webcal_mcp.config import CalendarConfig
+from webcal_mcp.fetcher import IcsHttpSource
+
+
+def _make_source(
+    handler: httpx.MockTransport, *, ttl_seconds: int = 900
+) -> tuple[IcsHttpSource, httpx.AsyncClient]:
+    client = httpx.AsyncClient(transport=handler)
+    cfg = CalendarConfig(name="c", url="https://example.com/c.ics", ttl_seconds=ttl_seconds)
+    return IcsHttpSource(cfg, client), client
+
+
+@pytest.mark.asyncio
+async def test_cached_within_ttl(simple_ics: bytes) -> None:
+    calls: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append(request)
+        return httpx.Response(200, content=simple_ics, headers={"etag": "v1"})
+
+    source, client = _make_source(httpx.MockTransport(handler))
+    try:
+        window = (
+            datetime(2026, 6, 1, tzinfo=timezone.utc),
+            datetime(2026, 6, 10, tzinfo=timezone.utc),
+        )
+        await source.events(*window)
+        await source.events(*window)
+    finally:
+        await client.aclose()
+    assert len(calls) == 1  # second call served from cache
+
+
+@pytest.mark.asyncio
+async def test_etag_revalidation(simple_ics: bytes) -> None:
+    calls: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append(request)
+        if "If-None-Match" in request.headers:
+            return httpx.Response(304)
+        return httpx.Response(200, content=simple_ics, headers={"etag": "v1"})
+
+    source, client = _make_source(httpx.MockTransport(handler), ttl_seconds=0)
+    try:
+        window = (
+            datetime(2026, 6, 1, tzinfo=timezone.utc),
+            datetime(2026, 6, 10, tzinfo=timezone.utc),
+        )
+        first = await source.events(*window)
+        second = await source.events(*window)
+    finally:
+        await client.aclose()
+
+    assert len(calls) == 2
+    assert calls[1].headers.get("If-None-Match") == "v1"
+    assert [e.uid for e in first] == [e.uid for e in second]
+
+
+@pytest.mark.asyncio
+async def test_get_event_uses_cache(simple_ics: bytes) -> None:
+    calls: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append(request)
+        return httpx.Response(200, content=simple_ics)
+
+    source, client = _make_source(httpx.MockTransport(handler))
+    try:
+        event = await source.get_event("evt-2@test")
+    finally:
+        await client.aclose()
+
+    assert event is not None
+    assert event.summary == "Lunch with Alice"
+    assert len(calls) == 1
+
+
+@pytest.mark.asyncio
+async def test_refresh_bypasses_ttl(simple_ics: bytes) -> None:
+    calls: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append(request)
+        if "If-None-Match" in request.headers:
+            return httpx.Response(304)
+        return httpx.Response(200, content=simple_ics, headers={"etag": "v1"})
+
+    # TTL is large enough that a normal call would be served from cache.
+    source, client = _make_source(httpx.MockTransport(handler), ttl_seconds=3600)
+    try:
+        window = (
+            datetime(2026, 6, 1, tzinfo=timezone.utc),
+            datetime(2026, 6, 10, tzinfo=timezone.utc),
+        )
+        await source.events(*window)
+        await source.events(*window)  # cached, no HTTP call
+        await source.events(*window, refresh=True)  # forces revalidation
+        await source.get_event("evt-1@test", refresh=True)  # forces revalidation
+    finally:
+        await client.aclose()
+
+    # Initial fetch + two refresh-triggered conditional GETs.
+    assert len(calls) == 3
+    assert calls[1].headers.get("If-None-Match") == "v1"
+    assert calls[2].headers.get("If-None-Match") == "v1"
+
+
+@pytest.mark.asyncio
+async def test_http_error_propagates() -> None:
+    def handler(_: httpx.Request) -> httpx.Response:
+        return httpx.Response(500, text="boom")
+
+    source, client = _make_source(httpx.MockTransport(handler))
+    try:
+        with pytest.raises(httpx.HTTPStatusError):
+            await source.events(
+                datetime(2026, 6, 1, tzinfo=timezone.utc),
+                datetime(2026, 6, 2, tzinfo=timezone.utc),
+            )
+    finally:
+        await client.aclose()

webcal_mcp-0.1.1/tests/test_parser.py

@@ -0,0 +1,82 @@
+"""Tests for ICS parsing, normalization, recurrence expansion, master lookup."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from webcal_mcp.parser import expand_events, find_master, parse_calendar
+
+
+def test_normalizes_events(simple_ics: bytes) -> None:
+    cal = parse_calendar(simple_ics)
+    events = expand_events(
+        cal,
+        datetime(2026, 6, 1, tzinfo=timezone.utc),
+        datetime(2026, 6, 10, tzinfo=timezone.utc),
+    )
+    assert [e.uid for e in events] == ["evt-1@test", "evt-2@test", "evt-3@test"]
+
+    standup = events[0]
+    assert standup.summary == "Standup"
+    assert standup.location == "Zoom"
+    assert standup.all_day is False
+    assert standup.categories == ("work", "meetings")
+    assert standup.start.tzinfo is not None
+
+
+def test_all_day_event_flagged(simple_ics: bytes) -> None:
+    cal = parse_calendar(simple_ics)
+    events = expand_events(
+        cal,
+        datetime(2026, 6, 4, tzinfo=timezone.utc),
+        datetime(2026, 6, 7, tzinfo=timezone.utc),
+    )
+    [conf] = events
+    assert conf.uid == "evt-3@test"
+    assert conf.all_day is True
+
+
+def test_window_filters_events(simple_ics: bytes) -> None:
+    cal = parse_calendar(simple_ics)
+    events = expand_events(
+        cal,
+        datetime(2026, 6, 2, tzinfo=timezone.utc),
+        datetime(2026, 6, 3, tzinfo=timezone.utc),
+    )
+    assert [e.uid for e in events] == ["evt-2@test"]
+
+
+def test_recurrence_expansion(recurring_ics: bytes) -> None:
+    cal = parse_calendar(recurring_ics)
+    events = expand_events(
+        cal,
+        datetime(2026, 6, 1, tzinfo=timezone.utc),
+        datetime(2026, 7, 1, tzinfo=timezone.utc),
+    )
+    assert len(events) == 4
+    assert all(e.summary == "Weekly sync" for e in events)
+    # Each occurrence is exactly one week apart.
+    gaps = {(b.start - a.start).days for a, b in zip(events, events[1:])}
+    assert gaps == {7}
+
+
+def test_find_master(simple_ics: bytes) -> None:
+    cal = parse_calendar(simple_ics)
+    master = find_master(cal, "evt-2@test")
+    assert master is not None
+    assert master.summary == "Lunch with Alice"
+    assert find_master(cal, "nope") is None
+
+
+def test_as_markdown_includes_key_fields(simple_ics: bytes) -> None:
+    cal = parse_calendar(simple_ics)
+    [standup, *_] = expand_events(
+        cal,
+        datetime(2026, 6, 1, tzinfo=timezone.utc),
+        datetime(2026, 6, 2, tzinfo=timezone.utc),
+    )
+    md = standup.as_markdown()
+    assert "## Standup" in md
+    assert "Zoom" in md
+    assert "evt-1@test" in md
+    assert "Daily sync" in md

webcal_mcp-0.1.1/tests/test_server.py

@@ -0,0 +1,123 @@
+"""Tests for server helpers and tool registration."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+import pytest
+
+from webcal_mcp.config import CalendarConfig, Config
+from webcal_mcp.parser import Event
+from webcal_mcp.server import (
+    DEFAULT_WINDOW_DAYS,
+    CalendarRegistry,
+    _filter,
+    _resolve_window,
+    build_server,
+)
+
+
+def _ev(uid: str, **kw: object) -> Event:
+    base = {
+        "uid": uid,
+        "summary": "",
+        "start": datetime(2026, 6, 1, tzinfo=timezone.utc),
+        "end": datetime(2026, 6, 1, 1, tzinfo=timezone.utc),
+        "all_day": False,
+    }
+    base.update(kw)
+    return Event(**base)  # type: ignore[arg-type]
+
+
+def test_resolve_window_defaults_when_empty() -> None:
+    start, end = _resolve_window(None, None)
+    assert (end - start) == timedelta(days=DEFAULT_WINDOW_DAYS)
+
+
+def test_resolve_window_open_start() -> None:
+    start, end = _resolve_window(None, "2026-06-30")
+    assert (end - start).days >= DEFAULT_WINDOW_DAYS - 1
+
+
+def test_resolve_window_open_end() -> None:
+    start, end = _resolve_window("2026-06-01", None)
+    assert (end - start) == timedelta(days=DEFAULT_WINDOW_DAYS)
+
+
+def test_resolve_window_pushes_end_to_end_of_day() -> None:
+    _, end = _resolve_window("2026-06-01", "2026-06-02")
+    assert end.hour == 23 and end.minute == 59
+
+
+def test_filter_query_matches_summary_and_description() -> None:
+    events = [
+        _ev("a", summary="Standup"),
+        _ev("b", summary="Lunch", description="with Alice"),
+        _ev("c", summary="Other"),
+    ]
+    assert {e.uid for e in _filter(events, query="alice", categories=None, location=None)} == {"b"}
+    assert {e.uid for e in _filter(events, query="stand", categories=None, location=None)} == {"a"}
+
+
+def test_filter_categories_intersection() -> None:
+    events = [
+        _ev("a", categories=("work",)),
+        _ev("b", categories=("personal",)),
+        _ev("c", categories=("work", "urgent")),
+    ]
+    got = _filter(events, query=None, categories=["WORK"], location=None)
+    assert {e.uid for e in got} == {"a", "c"}
+
+
+def test_filter_location_substring() -> None:
+    events = [
+        _ev("a", location="Cafe Roma"),
+        _ev("b", location="Office"),
+    ]
+    got = _filter(events, query=None, categories=None, location="cafe")
+    assert {e.uid for e in got} == {"a"}
+
+
+def _registry(*names: str) -> CalendarRegistry:
+    cals = {n: CalendarConfig(name=n, url=f"https://x/{n}.ics") for n in names}
+    return CalendarRegistry(Config(calendars=cals))
+
+
+def test_resolve_requires_name_when_multiple() -> None:
+    reg = _registry("a", "b")
+    try:
+        with pytest.raises(ValueError, match="Multiple calendars"):
+            reg.resolve(None)
+        with pytest.raises(ValueError, match="Unknown calendar"):
+            reg.resolve("c")
+        assert reg.resolve("a").name == "a"
+    finally:
+        import asyncio
+
+        asyncio.run(reg.aclose())
+
+
+def test_resolve_defaults_to_only_calendar() -> None:
+    reg = _registry("solo")
+    try:
+        assert reg.resolve(None).name == "solo"
+    finally:
+        import asyncio
+
+        asyncio.run(reg.aclose())
+
+
+@pytest.mark.asyncio
+async def test_build_server_registers_expected_tools() -> None:
+    reg = _registry("solo")
+    try:
+        server = build_server(reg)
+        tools = await server.list_tools()
+        assert {t.name for t in tools} == {
+            "list_calendars",
+            "list_events",
+            "events_on",
+            "get_event",
+        }
+    finally:
+        await reg.aclose()