# OurGroceries MCP Server & CLI

A command-line tool and Model Context Protocol (MCP) server for managing grocery lists on
OurGroceries.com.

## Features

This package provides CLI commands and MCP tools to:

- Get visible shopping-list summaries without raw item arrays
- Get categories, settings, active items, and crossed-off item history
- Resolve natural-language item requests against the master catalog and shopping history
- Add items to lists
- Remove items from lists
- Update item details (name, category, notes, star rating)
- Cross off and uncross items

## Installation

The npm package is published as `@sergib/ourgroceries-mcp`. The installed executable remains
`ourgroceries-mcp`.

### Login to OurGroceries

Authenticate with your OurGroceries account:

```bash
npx -y @sergib/ourgroceries-mcp login
```

Enter your email and password when prompted.

The login command saves an OurGroceries auth cookie and team ID. It does not save your password.

## CLI Usage

Run commands directly with `npx`; no global install is required. Operational commands print JSON on
success and write errors to stderr with a nonzero exit code.

Start by listing your shopping lists, then use the returned list IDs for item commands:

```bash
npx -y @sergib/ourgroceries-mcp get-lists
npx -y @sergib/ourgroceries-mcp get-active-items --list-id LIST_ID
npx -y @sergib/ourgroceries-mcp get-crossed-off-items --list-id LIST_ID --search "milk" --limit 20
```

Use the resolver before adding item text. It can infer a likely target list from history, tell you
whether to add a new item, uncross an existing crossed-off item, or do nothing because the item is
already active:

```bash
npx -y @sergib/ourgroceries-mcp resolve-item-to-add --query "plátanos"
npx -y @sergib/ourgroceries-mcp resolve-item-to-add --query "add olives" --list-id LIST_ID
npx -y @sergib/ourgroceries-mcp add-item --list-id LIST_ID --value "olives"
npx -y @sergib/ourgroceries-mcp uncross-item --list-id LIST_ID --item-id ITEM_ID
```

Other useful commands:

```bash
npx -y @sergib/ourgroceries-mcp get-categories
npx -y @sergib/ourgroceries-mcp get-settings
npx -y @sergib/ourgroceries-mcp update-item --list-id LIST_ID --item-id ITEM_ID --new-value "whole milk"
npx -y @sergib/ourgroceries-mcp cross-off-item --list-id LIST_ID --item-id ITEM_ID
npx -y @sergib/ourgroceries-mcp remove-item --list-id LIST_ID --item-id ITEM_ID
```

For the full command list and options:

```bash
npx -y @sergib/ourgroceries-mcp --help
npx -y @sergib/ourgroceries-mcp get-crossed-off-items --help
```

## MCP Usage

Running the package without a subcommand starts the MCP server over stdio. Add it to an MCP client
after logging in.

### For Claude Code

```bash
claude mcp add ourgroceries npx -y @sergib/ourgroceries-mcp
```

### For Claude Desktop

Add to your configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ourgroceries": {
      "command": "npx",
      "args": ["-y", "@sergib/ourgroceries-mcp"]
    }
  }
}
```

Then restart Claude Desktop.

## Codex Skill

This repository and npm package include a Codex skill at
`skills/ourgroceries-cli`. Use `$ourgroceries-cli` when you want Codex to operate
OurGroceries through the CLI instead of through MCP.

## Credentials

By default, credentials are stored in a local config file:

- macOS/Linux: `~/.config/ourgroceries-mcp/config.json`
- Windows: `%APPDATA%\ourgroceries-mcp\config.json`

On macOS and Linux, the config file is written with owner-only `0600` permissions where supported.

To remove saved credentials:

```bash
npx -y @sergib/ourgroceries-mcp logout
```

`logout` removes the saved config file only. It does not modify environment variables.

### Environment-variable fallback

If there is no usable config file, the server can read credentials from environment variables:

- `OURGROCERIES_AUTH_COOKIE`
- `OURGROCERIES_TEAM_ID`

Both variables must be set. A saved config file takes priority over environment variables. If the
saved config file is invalid and both environment variables are set, the server warns and uses the
environment variables.

### Troubleshooting Credentials

If the CLI or MCP server reports missing or invalid credentials, run:

```bash
npx -y @sergib/ourgroceries-mcp login
```

Then retry your CLI command or restart your MCP client. If you use environment variables instead of
the config file, refresh both variables. Login debug output from
`npx -y @sergib/ourgroceries-mcp login --debug` redacts passwords, auth cookies, and cookie headers.

## What You Can Do

- **View your lists:** See shopping-list IDs and item counts without dumping every item
- **Read items:** Get active items or filtered crossed-off history for one list
- **Resolve item names:** Turn natural-language or partial item text into known values and likely target lists
- **Add items:** Add deterministic item values to any list with optional notes
- **Remove items:** Delete items from your lists
- **Update items:** Change item names, categories, notes, or star ratings
- **Check off items:** Cross items off or uncross previously crossed-off items

## Recommended Add Flow

For item add requests, use the resolver before mutating a list, even when the user gives only an item
name or partial name:

1. Call `resolve_item_to_add` with the user's text and, when known, `listId`.
2. Review the top candidate, `suggestedTargets`, and `recommendedAction`.
3. Follow `recommendedAction` when it is list-specific, even if the resolver inferred the list.
4. Call `add_item` only when the recommendation is `add_item`.
5. Call `uncross_item` when the recommendation is `uncross_item`.
6. Do not mutate when the recommendation is `already_active`.
7. Ask for a list only when the recommendation is `choose_list` and `suggestedTargets` are missing
   or ambiguous.

## MCP Example Prompts

Once configured, you can ask Claude:

- "What's on my grocery list?"
- "Add milk to my shopping list"
- "Mark eggs as crossed off"
- "Remove bread from the list"
- "Update the note on bananas to say 'organic'"

## License

MIT

## Developer CLI Usage

Build first, then run the local binary directly:

```bash
npm ci
npm run build
node build/cli.js
```

Running `node build/cli.js` with no subcommand starts the MCP server over stdio, matching the
package's `ourgroceries-mcp` binary behavior.

For local CLI testing with your own OurGroceries account, authenticate once:

```bash
node build/cli.js login
```

The CLI uses the same credentials as MCP mode: saved config file first, then the
`OURGROCERIES_AUTH_COOKIE` and `OURGROCERIES_TEAM_ID` environment-variable fallback. `logout`
removes only the saved config file:

```bash
node build/cli.js logout
```

Operational commands print JSON on success and write errors to stderr with a nonzero exit code.
They use explicit IDs for mutations. Use focused reads and the resolver before mutating items:

```bash
node build/cli.js get-lists
node build/cli.js get-categories
node build/cli.js get-settings
node build/cli.js get-active-items --list-id LIST_ID
node build/cli.js get-crossed-off-items --list-id LIST_ID --search "milk" --limit 20
node build/cli.js resolve-item-to-add --query "add olives" --list-id LIST_ID
node build/cli.js add-item --list-id LIST_ID --value "milk" --note "2%"
node build/cli.js remove-item --list-id LIST_ID --item-id ITEM_ID
node build/cli.js update-item --list-id LIST_ID --item-id ITEM_ID --new-value "whole milk" --star 1
node build/cli.js cross-off-item --list-id LIST_ID --item-id ITEM_ID
node build/cli.js uncross-item --list-id LIST_ID --item-id ITEM_ID
```

Reference docs for maintainers live in `docs/`.

Before sending CLI changes, run:

```bash
npm run check
npm audit --audit-level=moderate
```

### Publishing to npm

When publishing a new package version, refresh npm authentication and verify the account first:

```bash
npm login
npm whoami
npm publish --access public
```