facebook-mcp-server 1.6.6

package/.env.example

@@ -0,0 +1,2 @@
+FACEBOOK_ACCESS_TOKEN=your_long_lived_facebook_page_token_here
+FACEBOOK_PAGE_ID=your_facebook_page_id_here

package/.github/dependabot.yml

@@ -0,0 +1,50 @@
+version: 2
+updates:
+  # npm dependencies
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      dev-dependencies:
+        patterns:
+          - "typescript"
+          - "tsx"
+          - "vitest"
+          - "@types/*"
+          - "prettier"
+        update-types:
+          - "minor"
+          - "patch"
+      runtime-dependencies:
+        patterns:
+          - "@modelcontextprotocol/*"
+          - "zod"
+        update-types:
+          - "patch"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 3
+    labels:
+      - "dependencies"
+      - "github-actions"
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"

package/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test-matrix:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: ["20", "22"]
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Format check with prettier
+        run: npx prettier --check .
+
+      - name: Type check with tsc
+        run: npx tsc --noEmit
+
+      - name: Run tests
+        run: npm test
+
+      - name: Build
+        run: npm run build
+
+  test:
+    needs: [test-matrix]
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Check test matrix status
+        run: |
+          if [ "${{ needs.test-matrix.result }}" != "success" ]; then
+            echo "Test matrix failed with result: ${{ needs.test-matrix.result }}"
+            exit 1
+          fi
+          echo "All tests passed!"

package/.github/workflows/release.yml

@@ -0,0 +1,200 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_TOKEN }}
+
+      - name: Check for skip-release marker
+        id: check_skip
+        run: |
+          SUBJECT=$(git log -1 --pretty=%s)
+          if echo "$SUBJECT" | grep -q '\[skip-release\]'; then
+            echo "skip=true" >> $GITHUB_OUTPUT
+            echo "Skipping release: $SUBJECT"
+          else
+            echo "skip=false" >> $GITHUB_OUTPUT
+            echo "Proceeding with release check: $SUBJECT"
+          fi
+
+      - name: Set up Node.js
+        if: steps.check_skip.outputs.skip != 'true'
+        uses: actions/setup-node@v6
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+          cache: "npm"
+
+      - name: Install dependencies
+        if: steps.check_skip.outputs.skip != 'true'
+        run: npm ci
+
+      - name: Run tests
+        if: steps.check_skip.outputs.skip != 'true'
+        run: npm test
+
+      - name: Build
+        if: steps.check_skip.outputs.skip != 'true'
+        run: npm run build
+
+      - name: Configure Git
+        if: steps.check_skip.outputs.skip != 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Determine next version
+        id: version
+        if: steps.check_skip.outputs.skip != 'true'
+        run: |
+          CURRENT_VERSION=$(node -p "require('./package.json').version")
+          LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+
+          echo "current_version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+
+          if [ -z "$LAST_TAG" ]; then
+            echo "new_release=true" >> $GITHUB_OUTPUT
+            echo "new_version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+            echo "bump=initial" >> $GITHUB_OUTPUT
+            echo "First release: $CURRENT_VERSION"
+            exit 0
+          fi
+
+          COMMITS=$(git log "$LAST_TAG"..HEAD --pretty=%s)
+
+          if [ -z "$COMMITS" ]; then
+            echo "No new commits since $LAST_TAG"
+            echo "new_release=false" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          BUMP=""
+          if echo "$COMMITS" | grep -qiE '^[a-z]+(\(.+\))?!:|BREAKING CHANGE'; then
+            BUMP="major"
+          elif echo "$COMMITS" | grep -qiE '^feat(\(.+\))?:'; then
+            BUMP="minor"
+          elif echo "$COMMITS" | grep -qiE '^(fix|perf|refactor)(\(.+\))?:'; then
+            BUMP="patch"
+          fi
+
+          if [ -z "$BUMP" ]; then
+            echo "No release-worthy commits (feat/fix/perf/refactor) since $LAST_TAG"
+            echo "new_release=false" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT_VERSION"
+          case "$BUMP" in
+            major) MAJOR=$((MAJOR + 1)); MINOR=0; PATCH=0 ;;
+            minor) MINOR=$((MINOR + 1)); PATCH=0 ;;
+            patch) PATCH=$((PATCH + 1)) ;;
+          esac
+          NEW_VERSION="$MAJOR.$MINOR.$PATCH"
+
+          echo "new_release=true" >> $GITHUB_OUTPUT
+          echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
+          echo "bump=$BUMP" >> $GITHUB_OUTPUT
+          echo "Detected $BUMP bump: $CURRENT_VERSION → $NEW_VERSION"
+
+      - name: Bump version in package.json
+        if: steps.version.outputs.new_release == 'true'
+        run: |
+          if [ "${{ steps.version.outputs.bump }}" = "initial" ]; then
+            git tag -a "v${{ steps.version.outputs.new_version }}" -m "Release v${{ steps.version.outputs.new_version }}"
+          else
+            npm version ${{ steps.version.outputs.new_version }} --no-git-tag-version
+            git add package.json package-lock.json
+            git commit -m "chore(release): ${{ steps.version.outputs.new_version }} [skip-release]"
+            git tag -a "v${{ steps.version.outputs.new_version }}" -m "Release v${{ steps.version.outputs.new_version }}"
+          fi
+
+      - name: Push version commit and tag
+        if: steps.version.outputs.new_release == 'true'
+        run: |
+          git push origin main --follow-tags
+
+      - name: Generate release notes
+        id: notes
+        if: steps.version.outputs.new_release == 'true'
+        run: |
+          LAST_TAG=$(git describe --tags --abbrev=0 HEAD~1 2>/dev/null || echo "")
+          NEW_VERSION="v${{ steps.version.outputs.new_version }}"
+
+          {
+            echo "notes<<RELEASE_NOTES_EOF"
+
+            if [ -n "$LAST_TAG" ]; then
+              echo "## What's Changed"
+              echo ""
+
+              FEATS=$(git log "$LAST_TAG"..HEAD~1 --pretty="- %s" | grep -iE '^\- feat' || true)
+              FIXES=$(git log "$LAST_TAG"..HEAD~1 --pretty="- %s" | grep -iE '^\- fix' || true)
+              OTHERS=$(git log "$LAST_TAG"..HEAD~1 --pretty="- %s" | grep -viE '^\- (feat|fix|chore\(release\))' || true)
+
+              if [ -n "$FEATS" ]; then
+                echo "### Features"
+                echo "$FEATS"
+                echo ""
+              fi
+              if [ -n "$FIXES" ]; then
+                echo "### Bug Fixes"
+                echo "$FIXES"
+                echo ""
+              fi
+              if [ -n "$OTHERS" ]; then
+                echo "### Other Changes"
+                echo "$OTHERS"
+                echo ""
+              fi
+
+              echo "**Full Changelog**: https://github.com/${{ github.repository }}/compare/$LAST_TAG...$NEW_VERSION"
+            else
+              echo "Initial release"
+            fi
+
+            echo "RELEASE_NOTES_EOF"
+          } >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        if: steps.version.outputs.new_release == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          gh release create "v${{ steps.version.outputs.new_version }}" \
+            --title "v${{ steps.version.outputs.new_version }}" \
+            --notes "${{ steps.notes.outputs.notes }}" \
+            --latest
+
+      - name: Publish to npm
+        if: steps.version.outputs.new_release == 'true'
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          npm publish
+
+      - name: Release summary
+        if: steps.version.outputs.new_release == 'true'
+        run: |
+          echo "## Release Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Released version: **v${{ steps.version.outputs.new_version }}** (${{ steps.version.outputs.bump }} bump)" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Published to:" >> $GITHUB_STEP_SUMMARY
+          echo "- GitHub Releases" >> $GITHUB_STEP_SUMMARY
+          echo "- npm (npx installable)" >> $GITHUB_STEP_SUMMARY

package/CONTRIBUTING.md

@@ -0,0 +1,112 @@
+# Contributing to Facebook MCP Server
+
+Thank you for your interest in contributing! This guide will help you get started.
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js 18+
+- Git
+
+### Installation
+
+```bash
+git clone https://github.com/luminarylane/facebook-mcp-server.git
+cd facebook-mcp-server
+npm install
+```
+
+### Environment Setup
+
+```bash
+cp .env.example .env
+# Add your Facebook Page credentials to .env
+```
+
+## Development Workflow
+
+### 1. Create a Branch
+
+```bash
+git checkout -b feature/your-description
+```
+
+### 2. Make Changes
+
+Follow the existing code style and conventions.
+
+### 3. Test
+
+```bash
+npm test
+```
+
+### 4. Build
+
+```bash
+npm run build
+```
+
+### 5. Push and Create PR
+
+```bash
+git push origin your-branch-name
+gh pr create --title "Description" --body "Details..."
+```
+
+## Code Style
+
+- TypeScript strict mode
+- Prettier for formatting
+- Vitest for testing
+- No external SDK dependencies — raw `fetch` against the Graph API
+
+## Testing
+
+```bash
+# Run all tests
+npm test
+
+# Type check
+npx tsc --noEmit
+```
+
+### Writing Tests
+
+- Place tests alongside source files as `*.test.ts`
+- Use `vi.stubGlobal("fetch", ...)` to stub network calls
+- Every tool handler should have happy-path and error-path coverage
+
+## Project Structure
+
+```
+facebook-mcp-server/
+├── src/
+│   ├── index.ts          # MCP server + tool registration
+│   ├── client.ts         # Graph API HTTP client
+│   ├── create-post.ts    # Post creation validation
+│   ├── errors.ts         # Error mapping + agent action hints
+│   ├── rate-limiter.ts   # Token-bucket rate limiter
+│   ├── response.ts       # MCP response helpers
+│   ├── sanitize.ts       # Prompt injection protection
+│   ├── lib/
+│   │   ├── index.ts      # Public API surface
+│   │   └── insights.ts   # SENSE/insights functions
+│   └── *.test.ts         # Tests alongside source
+├── .env.example
+├── package.json
+├── tsconfig.json
+└── vitest.config.ts
+```
+
+## Pull Request Process
+
+1. Ensure tests pass: `npm test`
+2. Ensure types check: `npx tsc --noEmit`
+3. Write a clear PR description
+4. Link to related issues
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Luminary Lane
+
+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.

package/README.md

@@ -0,0 +1,128 @@
+# Facebook Pages MCP Server
+
+[![MCP](https://img.shields.io/badge/MCP-1.0-blue)](https://modelcontextprotocol.io)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)
+
+A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for the Facebook Graph API (Pages). Enables Claude Desktop and other MCP clients to read insights, create posts, manage comments, and more — all through the Facebook Pages API.
+
+## Features
+
+### SENSE Tools (Read)
+
+| Tool                   | Description                                                         |
+| ---------------------- | ------------------------------------------------------------------- |
+| `fb_get_page_insights` | Page-level metrics: impressions, reach, engagements, follower count |
+| `fb_get_post_insights` | Post-level metrics: impressions, clicks, reactions                  |
+| `fb_get_comments`      | Comments on a post with author info, likes, replies                 |
+| `fb_get_page_feed`     | Your published posts with permalinks, shares, timestamps            |
+
+### ACT Tools (Write)
+
+| Tool               | Description                                                               |
+| ------------------ | ------------------------------------------------------------------------- |
+| `fb_create_post`   | Create text, link, photo, or video posts. Supports first-comment for CTAs |
+| `fb_reply_comment` | Reply to a comment on a post                                              |
+| `fb_delete_post`   | Delete a post you published                                               |
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 18+
+- A Facebook Page Access Token ([how to get one](https://developers.facebook.com/docs/pages/access-tokens))
+- Your Facebook Page ID
+
+### Install
+
+```bash
+git clone https://github.com/luminarylane/facebook-mcp-server.git
+cd facebook-mcp-server
+npm install
+npm run build
+```
+
+### Configure
+
+```bash
+cp .env.example .env
+# Edit .env with your credentials:
+#   FACEBOOK_ACCESS_TOKEN=your_long_lived_facebook_page_token_here
+#   FACEBOOK_PAGE_ID=your_facebook_page_id_here
+```
+
+### Run
+
+```bash
+# Development
+npm run dev
+
+# Production
+npm start
+```
+
+### Claude Desktop Configuration
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "facebook": {
+      "command": "node",
+      "args": ["/path/to/facebook-mcp-server/dist/index.js"],
+      "env": {
+        "FACEBOOK_ACCESS_TOKEN": "your_token_here",
+        "FACEBOOK_PAGE_ID": "your_page_id_here"
+      }
+    }
+  }
+}
+```
+
+## Architecture
+
+- **Transport**: stdio (standard MCP protocol)
+- **API**: Facebook Graph API v21.0
+- **Rate Limiting**: Built-in token-bucket rate limiter (200 calls/hour global, 25 publishes/day) with per-tenant isolation
+- **Retry**: Automatic exponential backoff on 429s (up to 3 retries)
+- **Security**: Input sanitization against prompt injection (zero-width chars, whitespace abuse, context flooding)
+- **Error Handling**: Structured errors with actionable `action` hints for agents
+
+## Development
+
+```bash
+# Run tests
+npm test
+
+# Development server (auto-reload)
+npm run dev
+
+# Type check
+npx tsc --noEmit
+
+# Build
+npm run build
+```
+
+## Testing
+
+The test suite covers:
+
+- **client.test.ts** — Graph API HTTP client, URL construction, error parsing
+- **create-post.test.ts** — Post creation validation and endpoint routing
+- **errors.test.ts** — Error mapping and agent-action hint strings
+- **first-comment.test.ts** — First-comment partial-success contract
+- **handlers.test.ts** — Full tool handler integration tests
+- **rate-limiter.test.ts** — Token bucket, per-tenant isolation, retry logic
+- **response.test.ts** — MCP response formatting
+- **sanitize.test.ts** — Prompt injection protection
+- **tools.test.ts** — safeHandler and credential resolution
+
+```bash
+npm test
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/client.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Facebook Graph API client.
+ *
+ * Raw fetch wrapper against https://graph.facebook.com/v21.0/.
+ * No SDK — keeps dependencies minimal (Occam's Razor).
+ * Client instances are cached by credential hash.
+ */
+export interface Credentials {
+    accessToken: string;
+    pageId: string;
+}
+/**
+ * Get or create a cached Facebook client.
+ */
+export declare function createClient(creds: Credentials): FacebookClient;
+/**
+ * Graph API error format from Facebook.
+ */
+export interface GraphApiError {
+    error: {
+        message: string;
+        type: string;
+        code: number;
+        error_subcode?: number;
+        fbtrace_id?: string;
+    };
+}
+/**
+ * Error thrown for Graph API failures. Carries structured error data
+ * for suggestAction() to inspect.
+ */
+export declare class FacebookApiError extends Error {
+    readonly status: number;
+    readonly code: number;
+    readonly errorSubcode?: number;
+    readonly errorType: string;
+    readonly retryAfter?: number;
+    constructor(status: number, apiError: GraphApiError["error"], retryAfter?: number);
+}
+export declare class FacebookClient {
+    readonly accessToken: string;
+    readonly pageId: string;
+    constructor(creds: Credentials);
+    /**
+     * Make a GET request to the Graph API.
+     */
+    get<T = unknown>(path: string, params?: Record<string, string>): Promise<T>;
+    /**
+     * Make a POST request to the Graph API.
+     */
+    post<T = unknown>(path: string, body?: Record<string, unknown>): Promise<T>;
+    /**
+     * Make a DELETE request to the Graph API.
+     */
+    delete<T = unknown>(path: string): Promise<T>;
+    private handleResponse;
+}