marcus
bdf9e3c59e
- Move integration tests to tests/; fix .gitignore to scope root-only
- Remove tracked debug artefacts (probe2_stderr/stdout.txt)
- __init__.py: version via importlib.metadata; export create_server in __all__
- server.py: unified JSON error format {"error":"..."} for all tools
- server.py: date validation (YYYY-MM-DD) for all meal-plan tools
- server.py: clear_list reports partial failures (failed_count, failed_ids)
- server.py: -> str annotations on get_circles, get_tasks, get_activities
- server.py: document TODO:94 as known limitation (no name in sortingIndexByTaskList)
- server.py: date validation also added to get_meal_plan
- Add LICENSE (MIT, Marcus van Elst)
- Add CHANGELOG.md (Keep a Changelog, v0.1.0–v1.0.0)
- README.md: restructured by use case; 🔒 marks write tools
- CLAUDE.md: update to v1.0.0 state; condense roadmap history
- SPEC.md: add version stamp
- pyproject.toml: version 1.0.0 (single source of truth)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
127 lines
4.2 KiB
Markdown
127 lines
4.2 KiB
Markdown
# mcp-familywall
|
|
|
|
MCP server for [Family Wall](https://www.familywall.com) — manage your family's circles, lists, tasks, recipes, and meal plan directly from Claude.
|
|
|
|
## Tools (v1.0.0)
|
|
|
|
### Circles & Members
|
|
|
|
| Tool | Description |
|
|
|---|---|
|
|
| `get_circles` | List all family circles |
|
|
| `get_members` | List members of a circle (or all circles) |
|
|
| `create_circle` 🔒 | Create a new Family Wall circle |
|
|
| `update_circle` 🔒 | Rename a circle (primary circle protected) |
|
|
| `add_member_to_circle` 🔒 | Invite a person to a circle by e-mail |
|
|
| `delete_circle` 🔒 | Permanently delete a circle and all its content |
|
|
|
|
### Lists & Tasks
|
|
|
|
| Tool | Description |
|
|
|---|---|
|
|
| `get_lists` | List all task lists (emoji, color, circle; optional `scope` filter) |
|
|
| `get_tasks` | List tasks in a list (category, due date, assignees, recurrency, reminder) |
|
|
| `get_categories` | List categories for a list (locale-filtered; custom categories always shown) |
|
|
| `get_activities` | List recent wall activities (author resolved to display name) |
|
|
| `create_list` 🔒 | Create a task list (`SHOPPING_LIST`, `TODOS`, or `OTHER`; optional emoji, color, circle) |
|
|
| `update_list` 🔒 | Rename a list or change its emoji/color (partial update; system lists protected) |
|
|
| `delete_list` 🔒 | Permanently delete a list and all its tasks (system lists protected) |
|
|
| `create_category` 🔒 | Create a custom category (with optional icon) |
|
|
| `delete_category` 🔒 | Delete a custom category (system categories protected) |
|
|
| `create_task` 🔒 | Create a task (supports category, due date, assignees; use `"Äpfel (5x)"` for quantities) |
|
|
| `update_task` 🔒 | Update text, category, due date, assignees, or move to a different list |
|
|
| `toggle_task` 🔒 | Mark a task complete or reopen it |
|
|
| `delete_task` 🔒 | Permanently delete a task |
|
|
| `clear_list` 🔒 | Bulk-delete all tasks in a list (optional `only_open=True` keeps completed tasks) |
|
|
| `like_post` 🔒 | Like a wall post/activity |
|
|
|
|
### Recipe Box
|
|
|
|
| Tool | Description |
|
|
|---|---|
|
|
| `get_recipe_categories` | List all recipe categories |
|
|
| `get_recipe_box` | List real recipes only (excludes free-text meal stubs) |
|
|
| `get_recipes` | List all recipe entries including stubs (compact summary) |
|
|
| `get_recipe` | Get a single recipe in full detail (ingredients, instructions, parsed ingredients) |
|
|
| `create_recipe` 🔒 | Create a new recipe (name, ingredients, instructions, prep/cook time, serves, url, categories) |
|
|
| `update_recipe` 🔒 | Update any field of a recipe (partial update; supports category_ids) |
|
|
| `delete_recipe` 🔒 | Permanently delete a recipe |
|
|
|
|
### Meal Planner (Premium)
|
|
|
|
| Tool | Description |
|
|
|---|---|
|
|
| `get_meal_plan` | Get meal plan entries for a date range (dish + meal entries, sorted by date + slot) |
|
|
| `add_recipe_to_meal_plan` 🔒 | Add a recipe-box recipe to a meal slot (BREAKFAST/LUNCH/SNACK/DINNER) |
|
|
| `add_meal_to_meal_plan` 🔒 | Add a free-text meal entry to a meal slot |
|
|
| `add_meal_note` 🔒 | Add a note and/or serving count to a meal slot |
|
|
| `delete_meal_plan_entry` 🔒 | Delete a meal plan entry (`dish/…` or `meal/…`) |
|
|
|
|
🔒 = requires user confirmation before calling
|
|
|
|
## Requirements
|
|
|
|
- Python 3.12+
|
|
- [uv](https://docs.astral.sh/uv/)
|
|
- A Family Wall account
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
uv tool install mcp-familywall
|
|
```
|
|
|
|
## Setup
|
|
|
|
Run the interactive setup wizard once to store your credentials securely in the OS keyring:
|
|
|
|
```bash
|
|
mcp-familywall setup
|
|
```
|
|
|
|
This will:
|
|
1. Prompt for your Family Wall email and password
|
|
2. Verify the credentials against the API
|
|
3. Store them in the OS keyring
|
|
4. Print a Claude Desktop configuration snippet
|
|
|
|
## Claude Desktop configuration
|
|
|
|
Add the printed snippet to your `claude_desktop_config.json`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"familywall": {
|
|
"command": "uvx",
|
|
"args": ["mcp-familywall", "serve"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Verify
|
|
|
|
```bash
|
|
mcp-familywall check
|
|
```
|
|
|
|
## Debug logging
|
|
|
|
Set `FW_DEBUG=1` to log full request/response bodies to stderr (passwords are masked):
|
|
|
|
```bash
|
|
FW_DEBUG=1 mcp-familywall check
|
|
```
|
|
|
|
## Credentials
|
|
|
|
Credentials are resolved in this order:
|
|
|
|
1. Environment variables `FW_EMAIL` and `FW_PASSWORD`
|
|
2. OS keyring (set by `mcp-familywall setup`)
|
|
|
|
## License
|
|
|
|
[MIT](LICENSE) — © 2026 Marcus van Elst
|