# fb-organic-mcp

Dependency-free [MCP](https://modelcontextprotocol.io) stdio server for **organic
Facebook Page content** — create/schedule posts, photo posts, read posts and
comments, page insights, delete posts.

It complements `@mikusnuz/meta-ads-mcp` (ads) and `@mikusnuz/meta-mcp`
(Instagram/Threads): neither covers organic Facebook Page publishing, this
server does only that. Single file, no dependencies, Node ≥ 18.

## Run

```bash
META_ADS_ACCESS_TOKEN=... npx -y github:Green-pep/fb-organic-mcp#v1.0.0
```

Always pin a tag (`#v1.0.0`) — unpinned git refs drift silently.

## Environment

| Variable | Required | Purpose |
|---|---|---|
| `META_ADS_ACCESS_TOKEN` | yes | Meta user/system token. The server exchanges it per page for a Page access token (`?fields=access_token`). |
| `FB_PAGE_ID` | no | Default page id when a tool call omits `page_id`. |

Token scopes: read tools work with `pages_show_list` + `pages_read_engagement`;
write tools (`create_page_post`, `create_page_photo_post`, `delete_page_post`)
require `pages_manage_posts`.

## Tools (9)

| Tool | What it does |
|---|---|
| `list_pages` | Pages the token manages (id, name, category). |
| `get_page` | Page profile: name, about, category, fan_count, link. |
| `list_page_posts` | Posts newest-first; `include_scheduled` adds unpublished scheduled posts. |
| `create_page_post` | Organic text/link post; `published=false` + `scheduled_publish_time` (unix s, 10 min–75 days ahead) schedules it. Verify-reads the created post. |
| `create_page_photo_post` | Photo post by public URL, optional caption/scheduling. |
| `get_post` | Read one post incl. reactions/comments/shares summary. |
| `list_post_comments` | Comments on a post (read-only). |
| `delete_page_post` | Delete a post. Destructive — confirm with the operator first. |
| `get_page_insights` | Page impressions / engagements / fans / views for day, week or days_28. |

## HuMind dashboard catalog definition

| Field | Value |
|---|---|
| `slug` | `fb-organic` |
| `command` | `npx` |
| `args` | `["-y", "github:Green-pep/fb-organic-mcp#v1.0.0"]` |
| `env_keys` | `[{"name": "META_ADS_ACCESS_TOKEN", "required": true}, {"name": "FB_PAGE_ID", "required": false}]` |

## Releasing a change

1. Edit `fb-organic-mcp.mjs`; bump `version` in `package.json` **and** in the
   `initialize` handler's `serverInfo`.
2. Commit, tag (`git tag v1.x.y && git push --tags`).
3. Update the catalog `args` pin to the new tag. Sessions pick it up on their
   next launch; the first launch per container re-downloads once (npx cache).

## Smoke test

```bash
printf '%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | node fb-organic-mcp.mjs
```

Expect an `initialize` reply and a 9-tool list. Tool calls without
`META_ADS_ACCESS_TOKEN` return an in-band error, never crash.