plurk-mcp

plurk-mcp is a guarded Plurk MCP execution layer for OpenClaw.

It is designed for a single Plurk account and gives an agent a narrow, controlled tool surface for:

• reading account, alert, mention, and thread context
• creating new plurks
• replying only to eligible interactions
• enforcing posting guardrails in the execution layer instead of trusting prompt behavior

This repository does not implement editorial strategy, scheduling logic, or campaign decisions. OpenClaw decides what to post and when to post it. plurk-mcp only reads context, executes approved actions, applies safeguards, and records local audit logs.

Features

• npm-installable CLI package with dedicated MCP and debug entrypoints
• Plurk OAuth 1.0a request signing
• approved v1 tool surface only:
  • plurk_get_me
  • plurk_get_alerts
  • plurk_get_mentions_context
  • plurk_get_thread_context
  • plurk_post
  • plurk_reply
• server-side guardrails:
  • daily new-post limit
  • per-thread reply cooldown
  • reply eligibility checks
• local JSONL audit logs
• local-only web debug console

Safety Model

This project is intentionally restrictive.

Allowed in v1:

• read profile, alerts, mentions context, and thread context
• create a new plurk
• reply to an explicit mention or a reply on a plurk authored by the operator account

Not exposed in v1:

• edit plurk
• delete plurk
• follow user
• fan-management actions
• unrelated public-thread participation

Requirements

• Node.js >= 22
• a Plurk application key and secret
• a Plurk access token and access token secret for the target account

Install

If the package is published to npm:

npm install plurk-mcp

For local verification from this repository:

npm install
npm run build

CLI Usage

Run MCP mode:

npx plurk-mcp

Run debug mode:

npx plurk-mcp-debug

You can also use the main binary with the debug subcommand:

npx plurk-mcp debug

Environment Variables

Required:

export PLURK_APP_KEY="..."
export PLURK_APP_SECRET="..."
export PLURK_ACCESS_TOKEN="..."
export PLURK_ACCESS_TOKEN_SECRET="..."

Optional:

export PLURK_MCP_TIMEZONE="UTC"
export PLURK_MCP_DAILY_POST_LIMIT="10"
export PLURK_MCP_REPLY_COOLDOWN_MINUTES="15"
export PLURK_MCP_DEBUG_HOST="127.0.0.1"
export PLURK_MCP_DEBUG_PORT="3939"
export PLURK_MCP_DATA_DIR="./data"

Meaning of the optional values:

• PLURK_MCP_TIMEZONE Used for daily quota rollover and audit file partitioning.
• PLURK_MCP_DAILY_POST_LIMIT Maximum number of new plurks per local day. Replies do not consume this budget.
• PLURK_MCP_REPLY_COOLDOWN_MINUTES Minimum cooldown between automatic replies in the same thread.
• PLURK_MCP_DEBUG_HOST Debug server bind host. Defaults to 127.0.0.1.
• PLURK_MCP_DEBUG_PORT Debug server port. Must be a positive integer.
• PLURK_MCP_DATA_DIR Root directory for audit logs and policy state.

MCP Tools

plurk_get_me

Returns the authenticated account profile used by this server.

plurk_get_alerts

Returns recent normalized alerts for operator review.

plurk_get_mentions_context

Returns recent mention-driven interactions suitable for summarization or reply planning.

plurk_get_thread_context

Returns the parent plurk plus normalized replies for a specific thread.

plurk_post

Creates a new plurk and consumes daily new-post quota.

plurk_reply

Creates a reply only when:

• the thread belongs to a plurk authored by the operator account, or
• the interaction explicitly mentions the operator account

Replies outside that boundary are rejected before the server calls Plurk.

Guardrails

The server enforces these rules regardless of what the agent asks it to do:

• new posts are limited to 10 per local day by default
• replies do not consume the daily post budget
• replies in the same thread are rate-limited with a default 15 minute cooldown
• unsupported high-risk actions are not registered as tools
• policy denials and upstream failures are logged locally

Debug Console

The debug console is local-only by default and is intended for operator testing, not public access.

It provides:

• sanitized runtime configuration summary
• buttons and forms for approved v1 actions only
• normalized JSON responses
• policy-denial visibility
• recent audit log inspection

Default URL:

http://127.0.0.1:3939

Data Files

By default the server writes:

• data/audit/YYYY-MM-DD.jsonl
• data/policy-state.json

The audit log records:

• successful reads
• successful writes
• policy denials
• upstream failures

Secrets are intentionally excluded from the logged metadata.

OpenClaw MCP Host Example

{
  "mcpServers": {
    "plurk": {
      "command": "npx",
      "args": ["plurk-mcp"],
      "env": {
        "PLURK_APP_KEY": "your-app-key",
        "PLURK_APP_SECRET": "your-app-secret",
        "PLURK_ACCESS_TOKEN": "your-access-token",
        "PLURK_ACCESS_TOKEN_SECRET": "your-access-token-secret",
        "PLURK_MCP_TIMEZONE": "UTC",
        "PLURK_MCP_DAILY_POST_LIMIT": "10",
        "PLURK_MCP_REPLY_COOLDOWN_MINUTES": "15"
      }
    }
  }
}

Development

Install dependencies:

npm install

Build:

npm run build

Type-check:

npm run lint

Run tests:

npm test

Create a tarball for local install verification:

npm pack

Project Structure

src/
  bin/                  CLI entrypoints
  config/               environment parsing and runtime config
  domain/               shared types and error helpers
  integrations/plurk/   OAuth signing, API calls, normalization
  services/             policy and application services
  storage/              audit and policy-state persistence
  transports/mcp/       MCP tool registration
  transports/debug/     local web debug console
test/                   automated tests

Current Status

The package, CLI entrypoints, tests, and npm artifact verification are in place.

What still depends on your real environment:

• end-to-end verification against live Plurk credentials
• any tuning of rate limits or upstream response handling discovered during real usage