chatgenius-mcp 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,9 +1,11 @@
1
1
  # chatgenius-mcp
2
2
 
3
- An MCP server for [ChatGenius](https://sumgenius.ai). Add it to Claude Desktop, Claude Code, Cursor, Zed, Gemini CLI or any client that speaks the Model Context Protocol and can run a local server, and your assistant can read and act on your Instagram, Facebook, WhatsApp and SMS inbox, contacts, appointments, flows, comment automation, Content Studio posts and knowledge base.
3
+ An MCP server for [ChatGenius](https://sumgenius.ai). Add it to Claude Desktop, Claude Code, Cursor, Zed, Gemini CLI or any client that speaks the Model Context Protocol, and your assistant can read and act on your Instagram, Facebook, WhatsApp and SMS inbox, contacts, appointments, flows, comment automation, Content Studio posts and knowledge base.
4
4
 
5
5
  It is a thin wrapper over the [ChatGenius REST API](https://sumgenius.ai/docs/rest-api). Every tool is one API call. Nothing is stored, nothing runs on our side, and your API key never leaves your machine.
6
6
 
7
+ Prefer not to run anything? The same tools are hosted at `https://sumgenius.ai/api/mcp` with a Connect button (OAuth): paste that URL into claude.ai, ChatGPT, Cursor or any client that takes a remote MCP server. Docs: https://sumgenius.ai/docs/mcp
8
+
7
9
  ## Install
8
10
 
9
11
  You need Node 18 or newer and a ChatGenius API key. Create the key in the portal under **Webhook + Send API, Credentials** (the Webhook & API add-on is required).
@@ -22,10 +24,11 @@ You need Node 18 or newer and a ChatGenius API key. Create the key in the portal
22
24
  }
23
25
  ```
24
26
 
25
- **Claude Code**:
27
+ **Claude Code** (plugin, prompts for the key):
26
28
 
27
29
  ```
28
- claude mcp add chatgenius -e CHATGENIUS_API_KEY=sgwh_... -- npx -y chatgenius-mcp
30
+ claude plugin marketplace add SumCodeAI/chatgenius-claude-plugin
31
+ claude plugin install chatgenius@sumgenius
29
32
  ```
30
33
 
31
34
  **Cursor**, **Zed**, **Windsurf** and the rest take the same command, args and env in their own MCP settings.
@@ -40,7 +43,7 @@ claude mcp add chatgenius -e CHATGENIUS_API_KEY=sgwh_... -- npx -y chatgenius-mc
40
43
 
41
44
  ## What it can do
42
45
 
43
- 50 tools in eight groups. Read tools are safe to run freely. Write tools create or edit records. Destructive tools reach a real person, publish content or change what runs live, and are marked so the client asks you first.
46
+ 61 tools in nine groups. Read tools are safe to run freely. Write tools create or edit records. Destructive tools reach a real person, publish content or change what runs live, and are marked so the client asks you first.
44
47
 
45
48
  | Group | Tools |
46
49
  |---|---|
@@ -51,6 +54,7 @@ claude mcp add chatgenius -e CHATGENIUS_API_KEY=sgwh_... -- npx -y chatgenius-mc
51
54
  | Flows | `list_flows`, `get_flow`, `get_flow_definition`, `get_flow_node_catalogue`, `validate_flow`, `create_flow`, `update_flow`, `publish_flow`, `activate_flow`, `pause_flow`, `get_flow_analytics`, `list_flow_sessions` |
52
55
  | Comments | `list_comment_triggers`, `get_comment_trigger_stats`, `list_recent_posts`, `list_handled_comments`, `approve_comment_reply`, `reject_comment_reply` |
53
56
  | Content Studio | `list_posts`, `get_post`, `get_posting_capabilities`, `create_post`, `update_post`, `schedule_post`, `publish_post` |
57
+ | Market Intel | `list_competitors`, `get_competitor`, `get_competitor_leaderboard`, `get_follower_history`, `get_wins_and_opportunities`, `get_audience_demographics`, `get_top_posts`, `get_account_insights`, `add_competitor`, `remove_competitor`, `refresh_market_intel` |
54
58
  | Knowledge base | `list_faqs`, `create_faq`, `update_faq`, `list_services`, `list_knowledge_gaps` |
55
59
 
56
60
  Things to try:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "chatgenius-mcp",
3
- "version": "0.1.4",
3
+ "version": "0.1.6",
4
4
  "description": "MCP server for ChatGenius: give Claude, Cursor, Gemini CLI or any MCP client tools over your Instagram, Facebook, WhatsApp and SMS inbox, contacts, appointments, flows, posts and knowledge base.",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/server.json CHANGED
@@ -3,13 +3,13 @@
3
3
  "name": "io.github.SumCodeAI/chatgenius",
4
4
  "description": "ChatGenius tools: Instagram, Facebook, WhatsApp and SMS inbox, contacts, bookings, flows, posts.",
5
5
  "websiteUrl": "https://sumgenius.ai/docs/mcp",
6
- "version": "0.1.4",
6
+ "version": "0.1.6",
7
7
  "packages": [
8
8
  {
9
9
  "registryType": "npm",
10
10
  "registryBaseUrl": "https://registry.npmjs.org",
11
11
  "identifier": "chatgenius-mcp",
12
- "version": "0.1.4",
12
+ "version": "0.1.6",
13
13
  "runtimeHint": "npx",
14
14
  "transport": {
15
15
  "type": "stdio"
@@ -30,5 +30,11 @@
30
30
  }
31
31
  ]
32
32
  }
33
+ ],
34
+ "remotes": [
35
+ {
36
+ "type": "streamable-http",
37
+ "url": "https://sumgenius.ai/api/mcp"
38
+ }
33
39
  ]
34
40
  }
package/src/tools.js CHANGED
@@ -71,6 +71,22 @@ export const TOOLS = [
71
71
  { name: 'schedule_post', op: 'schedule_a_post', kind: 'destructive' },
72
72
  { name: 'publish_post', op: 'publish_a_post_now', kind: 'destructive' },
73
73
 
74
+ // Market Intel (competitors and Instagram insights)
75
+ { name: 'list_competitors', op: 'list_tracked_competitors', kind: 'read' },
76
+ { name: 'get_competitor', op: 'compare_against_one_competitor', kind: 'read' },
77
+ { name: 'get_competitor_leaderboard', op: 'get_the_leaderboard', kind: 'read',
78
+ note: 'Your account and every competitor ranked together. Start here for any "how do I compare" question.' },
79
+ { name: 'get_follower_history', op: 'get_follower_history', kind: 'read' },
80
+ { name: 'get_wins_and_opportunities', op: 'get_wins_and_opportunities', kind: 'read' },
81
+ { name: 'get_audience_demographics', op: 'get_audience_demographics', kind: 'read',
82
+ note: 'Includes followers online by hour, which is what "when should I post" is answered from.' },
83
+ { name: 'get_top_posts', op: 'list_your_top_posts', kind: 'read' },
84
+ { name: 'get_account_insights', op: 'get_account_insights', kind: 'read' },
85
+ { name: 'add_competitor', op: 'track_a_competitor', kind: 'write' },
86
+ { name: 'remove_competitor', op: 'stop_tracking_a_competitor', kind: 'write' },
87
+ { name: 'refresh_market_intel', op: 'refresh_from_meta', kind: 'write',
88
+ note: 'Slow: one Meta call per tracked account. Only call it when the stored snapshot is stale.' },
89
+
74
90
  // Knowledge base
75
91
  { name: 'list_faqs', op: 'list_faqs', kind: 'read' },
76
92
  { name: 'create_faq', op: 'create_an_faq', kind: 'write' },
package/tools.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "spec_version": "1.15.1",
2
+ "spec_version": "1.17.0",
3
3
  "tools": [
4
4
  {
5
5
  "name": "get_account",
@@ -2884,6 +2884,295 @@
2884
2884
  "additionalProperties": false
2885
2885
  }
2886
2886
  },
2887
+ {
2888
+ "name": "list_competitors",
2889
+ "description": "List tracked competitors. Every account you track, with the numbers from its latest stored snapshot, plus how many slots your plan allows. Free 1, Creator 3, Pro 5, Business 10. Whole set in one page. last_snapshot_date is null until the first refresh.",
2890
+ "method": "GET",
2891
+ "path": "/competitors",
2892
+ "scope": "read",
2893
+ "kind": "read",
2894
+ "hasBody": false,
2895
+ "where": {
2896
+ "path": [],
2897
+ "query": [],
2898
+ "body": []
2899
+ },
2900
+ "inputSchema": {
2901
+ "type": "object",
2902
+ "properties": {},
2903
+ "additionalProperties": false
2904
+ }
2905
+ },
2906
+ {
2907
+ "name": "get_competitor",
2908
+ "description": "Compare against one competitor. That competitor and your own account side by side, with the per-metric differences the portal shows. Stored snapshots, no Meta call.",
2909
+ "method": "GET",
2910
+ "path": "/competitors/{id}",
2911
+ "scope": "read",
2912
+ "kind": "read",
2913
+ "hasBody": false,
2914
+ "where": {
2915
+ "path": [
2916
+ "id"
2917
+ ],
2918
+ "query": [],
2919
+ "body": []
2920
+ },
2921
+ "inputSchema": {
2922
+ "type": "object",
2923
+ "properties": {
2924
+ "id": {
2925
+ "type": "integer",
2926
+ "description": "Numeric id."
2927
+ }
2928
+ },
2929
+ "required": [
2930
+ "id"
2931
+ ],
2932
+ "additionalProperties": false
2933
+ }
2934
+ },
2935
+ {
2936
+ "name": "get_competitor_leaderboard",
2937
+ "description": "Get the leaderboard. Your account and every competitor ranked together: followers, engagement rate, posts per week, average likes and comments, follower growth per day and the content mix (reels, photos, carousels). This is the table behind the portal's Market Intel page. Stored snapshots, so it is instant and spends no Meta quota. Your account and every competitor ranked together. Start here for any \"how do I compare\" question.",
2938
+ "method": "GET",
2939
+ "path": "/market-intel/leaderboard",
2940
+ "scope": "read",
2941
+ "kind": "read",
2942
+ "hasBody": false,
2943
+ "where": {
2944
+ "path": [],
2945
+ "query": [
2946
+ "period"
2947
+ ],
2948
+ "body": []
2949
+ },
2950
+ "inputSchema": {
2951
+ "type": "object",
2952
+ "properties": {
2953
+ "period": {
2954
+ "type": "integer",
2955
+ "enum": [
2956
+ 7,
2957
+ 30,
2958
+ 90
2959
+ ],
2960
+ "default": 30,
2961
+ "description": "Window in days. Default 30."
2962
+ }
2963
+ },
2964
+ "additionalProperties": false
2965
+ }
2966
+ },
2967
+ {
2968
+ "name": "get_follower_history",
2969
+ "description": "Get follower history. Follower count and engagement rate over the window, one series per account including your own, oldest point first. One point per day that a snapshot was taken, so gaps mean nobody refreshed that day.",
2970
+ "method": "GET",
2971
+ "path": "/market-intel/history",
2972
+ "scope": "read",
2973
+ "kind": "read",
2974
+ "hasBody": false,
2975
+ "where": {
2976
+ "path": [],
2977
+ "query": [
2978
+ "period"
2979
+ ],
2980
+ "body": []
2981
+ },
2982
+ "inputSchema": {
2983
+ "type": "object",
2984
+ "properties": {
2985
+ "period": {
2986
+ "type": "integer",
2987
+ "enum": [
2988
+ 7,
2989
+ 30,
2990
+ 90
2991
+ ],
2992
+ "default": 30,
2993
+ "description": "Window in days. Default 30."
2994
+ }
2995
+ },
2996
+ "additionalProperties": false
2997
+ }
2998
+ },
2999
+ {
3000
+ "name": "get_wins_and_opportunities",
3001
+ "description": "Get wins and opportunities. The comparisons already computed against each competitor over the last 30 days: where you are ahead (wins) and where they are (opportunities), each with the metric and the size of the gap. Derived from stored snapshots, no AI involved.",
3002
+ "method": "GET",
3003
+ "path": "/market-intel/wins",
3004
+ "scope": "read",
3005
+ "kind": "read",
3006
+ "hasBody": false,
3007
+ "where": {
3008
+ "path": [],
3009
+ "query": [],
3010
+ "body": []
3011
+ },
3012
+ "inputSchema": {
3013
+ "type": "object",
3014
+ "properties": {},
3015
+ "additionalProperties": false
3016
+ }
3017
+ },
3018
+ {
3019
+ "name": "get_audience_demographics",
3020
+ "description": "Get audience demographics. The latest stored breakdown of your followers: gender and age as percentages, top countries and cities with counts, and followers online by hour when Instagram supplies it. 404 until the first refresh. Instagram withholds all of it for accounts under roughly 100 followers, which comes back as zeros rather than an error. Includes followers online by hour, which is what \"when should I post\" is answered from.",
3021
+ "method": "GET",
3022
+ "path": "/market-intel/audience",
3023
+ "scope": "read",
3024
+ "kind": "read",
3025
+ "hasBody": false,
3026
+ "where": {
3027
+ "path": [],
3028
+ "query": [],
3029
+ "body": []
3030
+ },
3031
+ "inputSchema": {
3032
+ "type": "object",
3033
+ "properties": {},
3034
+ "additionalProperties": false
3035
+ }
3036
+ },
3037
+ {
3038
+ "name": "get_top_posts",
3039
+ "description": "List your top posts. Your own recent posts with their stored performance: reach, impressions, likes, comments, saves, shares, video views, engagement rate and save rate. Newest first. Stored, so refresh first for current numbers.",
3040
+ "method": "GET",
3041
+ "path": "/market-intel/top-posts",
3042
+ "scope": "read",
3043
+ "kind": "read",
3044
+ "hasBody": false,
3045
+ "where": {
3046
+ "path": [],
3047
+ "query": [
3048
+ "limit"
3049
+ ],
3050
+ "body": []
3051
+ },
3052
+ "inputSchema": {
3053
+ "type": "object",
3054
+ "properties": {
3055
+ "limit": {
3056
+ "type": "integer",
3057
+ "minimum": 1,
3058
+ "maximum": 50,
3059
+ "default": 12,
3060
+ "description": "1 to 50. Default 12."
3061
+ }
3062
+ },
3063
+ "additionalProperties": false
3064
+ }
3065
+ },
3066
+ {
3067
+ "name": "get_account_insights",
3068
+ "description": "Get account insights. Reach, profile views, interactions, saves, shares and follows for your own account over the last 1, 7 or 30 days. This one calls Instagram live, so it takes a moment and counts against Meta's rate limit. 403 permission_required when the account was connected without the insights permission; reconnect it in the portal to fix that.",
3069
+ "method": "GET",
3070
+ "path": "/market-intel/insights",
3071
+ "scope": "read",
3072
+ "kind": "read",
3073
+ "hasBody": false,
3074
+ "where": {
3075
+ "path": [],
3076
+ "query": [
3077
+ "days"
3078
+ ],
3079
+ "body": []
3080
+ },
3081
+ "inputSchema": {
3082
+ "type": "object",
3083
+ "properties": {
3084
+ "days": {
3085
+ "type": "integer",
3086
+ "enum": [
3087
+ 1,
3088
+ 7,
3089
+ 30
3090
+ ],
3091
+ "default": 7,
3092
+ "description": "1, 7 or 30. Default 7."
3093
+ }
3094
+ },
3095
+ "additionalProperties": false
3096
+ }
3097
+ },
3098
+ {
3099
+ "name": "add_competitor",
3100
+ "description": "Track a competitor. Looks the handle up through Meta and starts tracking it. The account must be a public Instagram business or creator account; personal and private accounts cannot be read by anyone through the API (422 invalid_param). At the plan cap this is 403 plan_limit_reached, and an account you already track is 409 conflict. The first snapshot is taken immediately.",
3101
+ "method": "POST",
3102
+ "path": "/competitors",
3103
+ "scope": "write",
3104
+ "kind": "write",
3105
+ "hasBody": true,
3106
+ "where": {
3107
+ "path": [],
3108
+ "query": [],
3109
+ "body": [
3110
+ "username"
3111
+ ]
3112
+ },
3113
+ "inputSchema": {
3114
+ "type": "object",
3115
+ "properties": {
3116
+ "username": {
3117
+ "type": "string",
3118
+ "maxLength": 30,
3119
+ "description": "Instagram handle, with or without the leading @. Must be a public business or creator account."
3120
+ }
3121
+ },
3122
+ "required": [
3123
+ "username"
3124
+ ],
3125
+ "additionalProperties": false
3126
+ }
3127
+ },
3128
+ {
3129
+ "name": "remove_competitor",
3130
+ "description": "Stop tracking a competitor. Frees the slot. History is kept, so re-adding the same handle picks up where it left off.",
3131
+ "method": "DELETE",
3132
+ "path": "/competitors/{id}",
3133
+ "scope": "write",
3134
+ "kind": "write",
3135
+ "hasBody": false,
3136
+ "where": {
3137
+ "path": [
3138
+ "id"
3139
+ ],
3140
+ "query": [],
3141
+ "body": []
3142
+ },
3143
+ "inputSchema": {
3144
+ "type": "object",
3145
+ "properties": {
3146
+ "id": {
3147
+ "type": "integer",
3148
+ "description": "Numeric id."
3149
+ }
3150
+ },
3151
+ "required": [
3152
+ "id"
3153
+ ],
3154
+ "additionalProperties": false
3155
+ }
3156
+ },
3157
+ {
3158
+ "name": "refresh_market_intel",
3159
+ "description": "Refresh from Meta. Pulls current numbers from Meta for your account and every tracked competitor and writes today's snapshot, exactly like the portal's Refresh button. One Meta call per account, so it takes several seconds; every other Market Intel read serves the snapshots this writes. Five minutes are enforced between refreshes (429 too_soon carries retry_after_seconds). Send {} as the body. Slow: one Meta call per tracked account. Only call it when the stored snapshot is stale.",
3160
+ "method": "POST",
3161
+ "path": "/market-intel/refresh",
3162
+ "scope": "write",
3163
+ "kind": "write",
3164
+ "hasBody": false,
3165
+ "where": {
3166
+ "path": [],
3167
+ "query": [],
3168
+ "body": []
3169
+ },
3170
+ "inputSchema": {
3171
+ "type": "object",
3172
+ "properties": {},
3173
+ "additionalProperties": false
3174
+ }
3175
+ },
2887
3176
  {
2888
3177
  "name": "list_faqs",
2889
3178
  "description": "List FAQs. Question and answer pairs the AI answers from. Active only by default.",