@pegasusheavy/threads-mcp 1.0.0
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/.cursorrules/no-summaries.mdc +1 -0
- package/.cursorrules/update-website.mdc +8 -0
- package/.husky/README.md +37 -0
- package/.husky/commit-msg +3 -0
- package/.husky/pre-commit +12 -0
- package/.husky/pre-push +31 -0
- package/CHANGELOG.md +49 -0
- package/LICENSE +22 -0
- package/README.md +336 -0
- package/commitlint.config.js +27 -0
- package/dist/client/enhanced-threads-client.d.ts +49 -0
- package/dist/client/enhanced-threads-client.d.ts.map +1 -0
- package/dist/client/enhanced-threads-client.js +175 -0
- package/dist/client/enhanced-threads-client.js.map +1 -0
- package/dist/client/threads-client.d.ts +23 -0
- package/dist/client/threads-client.d.ts.map +1 -0
- package/dist/client/threads-client.js +208 -0
- package/dist/client/threads-client.js.map +1 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +41 -0
- package/dist/index.js.map +1 -0
- package/dist/server.d.ts +10 -0
- package/dist/server.d.ts.map +1 -0
- package/dist/server.js +382 -0
- package/dist/server.js.map +1 -0
- package/dist/types/threads.d.ts +298 -0
- package/dist/types/threads.d.ts.map +1 -0
- package/dist/types/threads.js +76 -0
- package/dist/types/threads.js.map +1 -0
- package/dist/utils/cache.d.ts +42 -0
- package/dist/utils/cache.d.ts.map +1 -0
- package/dist/utils/cache.js +147 -0
- package/dist/utils/cache.js.map +1 -0
- package/dist/utils/rate-limiter.d.ts +31 -0
- package/dist/utils/rate-limiter.d.ts.map +1 -0
- package/dist/utils/rate-limiter.js +99 -0
- package/dist/utils/rate-limiter.js.map +1 -0
- package/dist/utils/webhook.d.ts +67 -0
- package/dist/utils/webhook.d.ts.map +1 -0
- package/dist/utils/webhook.js +187 -0
- package/dist/utils/webhook.js.map +1 -0
- package/llms.txt +197 -0
- package/package.json +65 -0
|
@@ -0,0 +1 @@
|
|
|
1
|
+
Do not create summary documents, completion reports, or documentation files unless explicitly requested by the user.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
After completing any significant feature, update, or change to the project, update the relevant documentation on the GitHub Pages website (docs/ directory) to reflect the changes. This includes:
|
|
2
|
+
|
|
3
|
+
- Updating the main timeline (index.html) with new feature announcements as thread posts
|
|
4
|
+
- Adding new versions to changelog.html with detailed change notes
|
|
5
|
+
- Updating any affected documentation pages (API.md, EXAMPLES.md, etc.)
|
|
6
|
+
- Ensuring the website accurately represents the current state of the project
|
|
7
|
+
|
|
8
|
+
Always commit and push website updates along with the code changes.
|
package/.husky/README.md
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Husky Git Hooks
|
|
2
|
+
|
|
3
|
+
This directory contains Git hooks managed by [Husky](https://typicode.github.io/husky/).
|
|
4
|
+
|
|
5
|
+
## Available Hooks
|
|
6
|
+
|
|
7
|
+
- **pre-commit**: Runs before creating a commit
|
|
8
|
+
- Lint-staged (auto-fix staged files)
|
|
9
|
+
- TypeScript type checking
|
|
10
|
+
- **pre-push**: Runs before pushing to remote
|
|
11
|
+
- Full test suite
|
|
12
|
+
- Coverage verification
|
|
13
|
+
- Linting
|
|
14
|
+
- Build verification
|
|
15
|
+
- **commit-msg**: Validates commit message format
|
|
16
|
+
- Enforces conventional commits
|
|
17
|
+
|
|
18
|
+
## Documentation
|
|
19
|
+
|
|
20
|
+
See [../docs/GIT_HOOKS.md](../docs/GIT_HOOKS.md) for complete documentation.
|
|
21
|
+
|
|
22
|
+
## Quick Commands
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
# Bypass pre-commit (emergency only)
|
|
26
|
+
git commit --no-verify -m "your message"
|
|
27
|
+
|
|
28
|
+
# Bypass pre-push (emergency only)
|
|
29
|
+
git push --no-verify
|
|
30
|
+
|
|
31
|
+
# Test a hook manually
|
|
32
|
+
pnpm exec husky .husky/pre-commit
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Note
|
|
36
|
+
|
|
37
|
+
These hooks are automatically installed when you run `pnpm install`.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Run lint-staged to check and fix files
|
|
2
|
+
echo "🔍 Running lint-staged..."
|
|
3
|
+
pnpm exec lint-staged
|
|
4
|
+
|
|
5
|
+
# Run type checking
|
|
6
|
+
echo "🔍 Running TypeScript type checking..."
|
|
7
|
+
pnpm exec tsc --noEmit || {
|
|
8
|
+
echo "❌ Type checking failed. Please fix the errors before committing."
|
|
9
|
+
exit 1
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
echo "✅ Pre-commit checks passed!"
|
package/.husky/pre-push
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
echo "🧪 Running tests before push..."
|
|
2
|
+
|
|
3
|
+
# Run all tests
|
|
4
|
+
pnpm test || {
|
|
5
|
+
echo "❌ Tests failed. Please fix the failing tests before pushing."
|
|
6
|
+
exit 1
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
# Run coverage check
|
|
10
|
+
echo "📊 Checking test coverage..."
|
|
11
|
+
pnpm run test:coverage || {
|
|
12
|
+
echo "❌ Coverage check failed. Please ensure adequate test coverage."
|
|
13
|
+
exit 1
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
# Run linting
|
|
17
|
+
echo "🔍 Running linter..."
|
|
18
|
+
pnpm run lint || {
|
|
19
|
+
echo "❌ Linting failed. Please fix the linting errors before pushing."
|
|
20
|
+
exit 1
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
# Build check
|
|
24
|
+
echo "🏗️ Verifying build..."
|
|
25
|
+
pnpm run build || {
|
|
26
|
+
echo "❌ Build failed. Please fix the build errors before pushing."
|
|
27
|
+
exit 1
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
echo "✅ All pre-push checks passed!"
|
|
31
|
+
|
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [1.0.0] - 2025-12-15
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- Initial release of Threads MCP Server
|
|
13
|
+
- Complete Threads API v1.0 integration
|
|
14
|
+
- MCP protocol implementation with 8 powerful tools:
|
|
15
|
+
- `threads_get_profile` - Get user profile information
|
|
16
|
+
- `threads_get_threads` - List user's threads with pagination
|
|
17
|
+
- `threads_get_thread` - Get specific thread details
|
|
18
|
+
- `threads_create_thread` - Create new threads with text/image/video
|
|
19
|
+
- `threads_get_insights` - Get analytics and metrics
|
|
20
|
+
- `threads_get_replies` - Get replies to threads
|
|
21
|
+
- `threads_get_conversation` - Get full conversation threads
|
|
22
|
+
- `threads_reply_to_thread` - Reply to existing threads
|
|
23
|
+
- ThreadsClient class for direct API access
|
|
24
|
+
- Type-safe API with Zod schema validation
|
|
25
|
+
- Comprehensive error handling with ThreadsAPIError
|
|
26
|
+
- Full TypeScript support
|
|
27
|
+
- >90% test coverage with Vitest
|
|
28
|
+
- Detailed documentation and examples
|
|
29
|
+
- MIT License
|
|
30
|
+
|
|
31
|
+
### Technical Details
|
|
32
|
+
|
|
33
|
+
- Built with @modelcontextprotocol/sdk v1.0.4
|
|
34
|
+
- Uses axios v1.7.9 for HTTP requests
|
|
35
|
+
- Zod v3.24.1 for runtime type validation
|
|
36
|
+
- TypeScript 5.7.2
|
|
37
|
+
- Node.js 18+ required
|
|
38
|
+
- pnpm package manager
|
|
39
|
+
|
|
40
|
+
### Development
|
|
41
|
+
|
|
42
|
+
- ESLint configuration for code quality
|
|
43
|
+
- Prettier configuration for code formatting
|
|
44
|
+
- Vitest for testing with coverage reporting
|
|
45
|
+
- GitHub Actions CI/CD ready (to be configured)
|
|
46
|
+
- Conventional commits structure
|
|
47
|
+
|
|
48
|
+
[1.0.0]: https://github.com/PegasusHeavyIndustries/threads-mcp/releases/tag/v1.0.0
|
|
49
|
+
|
package/LICENSE
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Pegasus Heavy Industries LLC
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
package/README.md
ADDED
|
@@ -0,0 +1,336 @@
|
|
|
1
|
+
# Threads MCP Server
|
|
2
|
+
|
|
3
|
+
A powerful Model Context Protocol (MCP) server for integrating with the Threads.com API. This server provides comprehensive tools for creating, reading, and managing Threads content programmatically.
|
|
4
|
+
|
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
|
6
|
+
[](https://www.typescriptlang.org/)
|
|
7
|
+
[](https://nodejs.org/)
|
|
8
|
+
[](https://vitest.dev/)
|
|
9
|
+
|
|
10
|
+
🌐 **[Visit the Website](https://pegasusheavyindustries.github.io/threads-mcp/)** for a better reading experience!
|
|
11
|
+
|
|
12
|
+
## Features
|
|
13
|
+
|
|
14
|
+
- 🚀 **Complete Threads API Integration** - Full support for Threads.com API v1.0
|
|
15
|
+
- 🔧 **MCP Protocol** - Standard Model Context Protocol implementation
|
|
16
|
+
- 📊 **Analytics & Insights** - Access engagement metrics and analytics
|
|
17
|
+
- 💬 **Conversation Management** - Create threads, replies, and manage conversations
|
|
18
|
+
- 🎯 **Type-Safe** - Full TypeScript support with Zod schema validation
|
|
19
|
+
- ⚡ **Rate Limiting** - Token bucket algorithm to prevent API rate limit violations
|
|
20
|
+
- 💾 **Caching Layer** - In-memory caching with TTL and LRU eviction
|
|
21
|
+
- 🔔 **Webhook Support** - Event-based webhooks with automatic retries and signature verification
|
|
22
|
+
- ✅ **Well Tested** - >90% test coverage with Vitest
|
|
23
|
+
- 🔄 **Modern Stack** - Built with latest npm packages and best practices
|
|
24
|
+
|
|
25
|
+
## Available Tools
|
|
26
|
+
|
|
27
|
+
The server provides the following MCP tools:
|
|
28
|
+
|
|
29
|
+
### Profile & Content Management
|
|
30
|
+
|
|
31
|
+
- **`threads_get_profile`** - Get authenticated user's profile information
|
|
32
|
+
- **`threads_get_threads`** - Retrieve user's threads (posts) with pagination
|
|
33
|
+
- **`threads_get_thread`** - Get a specific thread by ID
|
|
34
|
+
- **`threads_create_thread`** - Create new threads with text, images, or videos
|
|
35
|
+
- **`threads_reply_to_thread`** - Reply to existing threads
|
|
36
|
+
|
|
37
|
+
### Engagement & Analytics
|
|
38
|
+
|
|
39
|
+
- **`threads_get_insights`** - Get analytics for threads or user account
|
|
40
|
+
- **`threads_get_replies`** - Retrieve replies to a specific thread
|
|
41
|
+
- **`threads_get_conversation`** - Get full conversation threads
|
|
42
|
+
|
|
43
|
+
## Prerequisites
|
|
44
|
+
|
|
45
|
+
Before you begin, you'll need:
|
|
46
|
+
|
|
47
|
+
1. **Node.js 18+** - [Download here](https://nodejs.org/)
|
|
48
|
+
2. **pnpm** - Install with `npm install -g pnpm`
|
|
49
|
+
3. **Threads API Access Token** - Get from [Meta for Developers](https://developers.facebook.com/docs/threads)
|
|
50
|
+
4. **Threads User ID** - Your Threads user account ID
|
|
51
|
+
|
|
52
|
+
### Getting Your Threads API Credentials
|
|
53
|
+
|
|
54
|
+
1. Visit [Meta for Developers](https://developers.facebook.com/)
|
|
55
|
+
2. Create or select an app
|
|
56
|
+
3. Add the Threads API to your app
|
|
57
|
+
4. Generate an access token with required permissions
|
|
58
|
+
5. Note your User ID from your Threads profile
|
|
59
|
+
|
|
60
|
+
## Installation
|
|
61
|
+
|
|
62
|
+
### From npm (when published)
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
pnpm install -g threads-mcp
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### From Source
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
# Clone the repository
|
|
72
|
+
git clone https://github.com/PegasusHeavyIndustries/threads-mcp.git
|
|
73
|
+
cd threads-mcp
|
|
74
|
+
|
|
75
|
+
# Install dependencies
|
|
76
|
+
pnpm install
|
|
77
|
+
|
|
78
|
+
# Build the project
|
|
79
|
+
pnpm run build
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Configuration
|
|
83
|
+
|
|
84
|
+
Set your Threads API credentials as environment variables:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
export THREADS_ACCESS_TOKEN="your-access-token-here"
|
|
88
|
+
export THREADS_USER_ID="your-user-id-here"
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
For persistent configuration, add these to your `~/.bashrc`, `~/.zshrc`, or equivalent:
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
echo 'export THREADS_ACCESS_TOKEN="your-access-token-here"' >> ~/.bashrc
|
|
95
|
+
echo 'export THREADS_USER_ID="your-user-id-here"' >> ~/.bashrc
|
|
96
|
+
source ~/.bashrc
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## Usage
|
|
100
|
+
|
|
101
|
+
### Running the Server
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
# If installed globally
|
|
105
|
+
threads-mcp
|
|
106
|
+
|
|
107
|
+
# If running from source
|
|
108
|
+
pnpm run dev
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### Using with MCP Clients
|
|
112
|
+
|
|
113
|
+
Configure your MCP client (like Claude Desktop) to use this server:
|
|
114
|
+
|
|
115
|
+
```json
|
|
116
|
+
{
|
|
117
|
+
"mcpServers": {
|
|
118
|
+
"threads": {
|
|
119
|
+
"command": "threads-mcp",
|
|
120
|
+
"env": {
|
|
121
|
+
"THREADS_ACCESS_TOKEN": "your-access-token",
|
|
122
|
+
"THREADS_USER_ID": "your-user-id"
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### Example Tool Calls
|
|
130
|
+
|
|
131
|
+
#### Get Your Profile
|
|
132
|
+
|
|
133
|
+
```json
|
|
134
|
+
{
|
|
135
|
+
"name": "threads_get_profile",
|
|
136
|
+
"arguments": {}
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
#### Create a Thread
|
|
141
|
+
|
|
142
|
+
```json
|
|
143
|
+
{
|
|
144
|
+
"name": "threads_create_thread",
|
|
145
|
+
"arguments": {
|
|
146
|
+
"text": "Hello from the Threads MCP Server! 🚀",
|
|
147
|
+
"replyControl": "everyone"
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
#### Get Thread Insights
|
|
153
|
+
|
|
154
|
+
```json
|
|
155
|
+
{
|
|
156
|
+
"name": "threads_get_insights",
|
|
157
|
+
"arguments": {
|
|
158
|
+
"threadId": "thread-id-here",
|
|
159
|
+
"metrics": ["views", "likes", "replies", "reposts"]
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
#### Reply to a Thread
|
|
165
|
+
|
|
166
|
+
```json
|
|
167
|
+
{
|
|
168
|
+
"name": "threads_reply_to_thread",
|
|
169
|
+
"arguments": {
|
|
170
|
+
"threadId": "thread-id-to-reply-to",
|
|
171
|
+
"text": "Great post!",
|
|
172
|
+
"replyControl": "accounts_you_follow"
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
## Development
|
|
178
|
+
|
|
179
|
+
### Project Structure
|
|
180
|
+
|
|
181
|
+
```
|
|
182
|
+
threads-mcp/
|
|
183
|
+
├── src/
|
|
184
|
+
│ ├── client/ # Threads API client
|
|
185
|
+
│ │ ├── __tests__/ # Client tests
|
|
186
|
+
│ │ └── threads-client.ts
|
|
187
|
+
│ ├── server/ # MCP server implementation
|
|
188
|
+
│ │ ├── __tests__/ # Server tests
|
|
189
|
+
│ │ └── server.ts
|
|
190
|
+
│ ├── types/ # TypeScript types & Zod schemas
|
|
191
|
+
│ │ ├── __tests__/ # Type tests
|
|
192
|
+
│ │ └── threads.ts
|
|
193
|
+
│ └── index.ts # Entry point
|
|
194
|
+
├── dist/ # Compiled output
|
|
195
|
+
├── coverage/ # Test coverage reports
|
|
196
|
+
└── tests/ # Integration tests
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
### Available Scripts
|
|
200
|
+
|
|
201
|
+
```bash
|
|
202
|
+
# Development
|
|
203
|
+
pnpm run dev # Run in development mode with tsx
|
|
204
|
+
pnpm run build # Compile TypeScript to JavaScript
|
|
205
|
+
|
|
206
|
+
# Testing
|
|
207
|
+
pnpm test # Run tests once
|
|
208
|
+
pnpm test:watch # Run tests in watch mode
|
|
209
|
+
pnpm test:coverage # Generate coverage report
|
|
210
|
+
|
|
211
|
+
# Code Quality
|
|
212
|
+
pnpm run lint # Lint code with ESLint
|
|
213
|
+
pnpm run format # Format code with Prettier
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
### Running Tests
|
|
217
|
+
|
|
218
|
+
The project has comprehensive test coverage (>90%):
|
|
219
|
+
|
|
220
|
+
```bash
|
|
221
|
+
# Run all tests
|
|
222
|
+
pnpm test
|
|
223
|
+
|
|
224
|
+
# Run with coverage
|
|
225
|
+
pnpm test:coverage
|
|
226
|
+
|
|
227
|
+
# Watch mode for development
|
|
228
|
+
pnpm test:watch
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
### Code Quality
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
# Lint your code
|
|
235
|
+
pnpm run lint
|
|
236
|
+
|
|
237
|
+
# Format code
|
|
238
|
+
pnpm run format
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
## API Reference
|
|
242
|
+
|
|
243
|
+
### ThreadsClient
|
|
244
|
+
|
|
245
|
+
The core client for interacting with the Threads API.
|
|
246
|
+
|
|
247
|
+
#### Constructor
|
|
248
|
+
|
|
249
|
+
```typescript
|
|
250
|
+
const client = new ThreadsClient({
|
|
251
|
+
accessToken: string;
|
|
252
|
+
userId: string;
|
|
253
|
+
apiVersion?: string; // Optional, defaults to 'v1.0'
|
|
254
|
+
});
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
#### Methods
|
|
258
|
+
|
|
259
|
+
- `getProfile(fields?: string[]): Promise<ThreadsUser>`
|
|
260
|
+
- `getThreads(params?: GetMediaParams): Promise<ThreadsMedia[]>`
|
|
261
|
+
- `getThread(threadId: string, fields?: string[]): Promise<ThreadsMedia>`
|
|
262
|
+
- `createThread(params: CreateThreadParams): Promise<CreateThreadResponse>`
|
|
263
|
+
- `getThreadInsights(threadId: string, params: GetInsightsParams): Promise<ThreadsInsights[]>`
|
|
264
|
+
- `getUserInsights(params: GetInsightsParams): Promise<ThreadsInsights[]>`
|
|
265
|
+
- `getReplies(threadId: string, params?: GetRepliesParams): Promise<ThreadsReplies>`
|
|
266
|
+
- `getConversation(threadId: string, params?: GetRepliesParams): Promise<ThreadsConversation>`
|
|
267
|
+
- `replyToThread(threadId: string, text: string, replyControl?: string): Promise<CreateThreadResponse>`
|
|
268
|
+
- `validateToken(): Promise<boolean>`
|
|
269
|
+
|
|
270
|
+
## Error Handling
|
|
271
|
+
|
|
272
|
+
The client includes comprehensive error handling:
|
|
273
|
+
|
|
274
|
+
```typescript
|
|
275
|
+
import { ThreadsAPIError } from 'threads-mcp';
|
|
276
|
+
|
|
277
|
+
try {
|
|
278
|
+
await client.createThread({ text: 'Hello!' });
|
|
279
|
+
} catch (error) {
|
|
280
|
+
if (error instanceof ThreadsAPIError) {
|
|
281
|
+
console.error('API Error:', error.message);
|
|
282
|
+
console.error('Status Code:', error.statusCode);
|
|
283
|
+
console.error('Response:', error.response);
|
|
284
|
+
}
|
|
285
|
+
}
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
## Contributing
|
|
289
|
+
|
|
290
|
+
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
291
|
+
|
|
292
|
+
1. Fork the repository
|
|
293
|
+
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
|
|
294
|
+
3. Commit your changes (`git commit -m 'feat: add some amazing feature'`)
|
|
295
|
+
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
296
|
+
5. Open a Pull Request
|
|
297
|
+
|
|
298
|
+
### Development Guidelines
|
|
299
|
+
|
|
300
|
+
- Write tests for new features (maintain >90% coverage)
|
|
301
|
+
- Follow the existing code style
|
|
302
|
+
- Update documentation as needed
|
|
303
|
+
- Use conventional commits (enforced by Git hooks)
|
|
304
|
+
|
|
305
|
+
### Git Hooks
|
|
306
|
+
|
|
307
|
+
This project uses Husky to enforce code quality:
|
|
308
|
+
|
|
309
|
+
- **pre-commit**: Runs linting, formatting, and type checking
|
|
310
|
+
- **pre-push**: Runs full test suite, coverage check, and build verification
|
|
311
|
+
- **commit-msg**: Validates commit message format (conventional commits)
|
|
312
|
+
|
|
313
|
+
See [docs/GIT_HOOKS.md](docs/GIT_HOOKS.md) for detailed information about Git hooks.
|
|
314
|
+
|
|
315
|
+
## License
|
|
316
|
+
|
|
317
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
318
|
+
|
|
319
|
+
Copyright (c) 2025 Pegasus Heavy Industries LLC
|
|
320
|
+
|
|
321
|
+
## Support
|
|
322
|
+
|
|
323
|
+
- 📚 [Threads API Documentation](https://developers.facebook.com/docs/threads)
|
|
324
|
+
- 🐛 [Report Issues](https://github.com/PegasusHeavyIndustries/threads-mcp/issues)
|
|
325
|
+
- 💬 [MCP Protocol Documentation](https://modelcontextprotocol.io/)
|
|
326
|
+
|
|
327
|
+
## Acknowledgments
|
|
328
|
+
|
|
329
|
+
- Built with [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)
|
|
330
|
+
- Powered by [Threads API](https://developers.facebook.com/docs/threads)
|
|
331
|
+
- Type validation with [Zod](https://github.com/colinhacks/zod)
|
|
332
|
+
- Testing with [Vitest](https://vitest.dev/)
|
|
333
|
+
|
|
334
|
+
---
|
|
335
|
+
|
|
336
|
+
Made with ❤️ by Pegasus Heavy Industries LLC
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
export default {
|
|
2
|
+
extends: ['@commitlint/config-conventional'],
|
|
3
|
+
rules: {
|
|
4
|
+
'type-enum': [
|
|
5
|
+
2,
|
|
6
|
+
'always',
|
|
7
|
+
[
|
|
8
|
+
'feat', // New feature
|
|
9
|
+
'fix', // Bug fix
|
|
10
|
+
'docs', // Documentation only changes
|
|
11
|
+
'style', // Changes that don't affect meaning (white-space, formatting, etc)
|
|
12
|
+
'refactor', // Code change that neither fixes a bug nor adds a feature
|
|
13
|
+
'perf', // Performance improvement
|
|
14
|
+
'test', // Adding missing tests or correcting existing tests
|
|
15
|
+
'build', // Changes that affect the build system or external dependencies
|
|
16
|
+
'ci', // Changes to CI configuration files and scripts
|
|
17
|
+
'chore', // Other changes that don't modify src or test files
|
|
18
|
+
'revert', // Reverts a previous commit
|
|
19
|
+
],
|
|
20
|
+
],
|
|
21
|
+
'subject-case': [0], // Allow any case for subject
|
|
22
|
+
'subject-full-stop': [0], // Allow full stop at end of subject
|
|
23
|
+
'body-max-line-length': [0], // No limit on body line length
|
|
24
|
+
'footer-max-line-length': [0], // No limit on footer line length
|
|
25
|
+
},
|
|
26
|
+
};
|
|
27
|
+
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import { ThreadsClient } from './threads-client.js';
|
|
2
|
+
import type { ThreadsConfig } from '../types/threads.js';
|
|
3
|
+
import { RateLimiter } from '../utils/rate-limiter.js';
|
|
4
|
+
import { AutoCleanCache } from '../utils/cache.js';
|
|
5
|
+
import { WebhookManager } from '../utils/webhook.js';
|
|
6
|
+
import type { ThreadsUser, ThreadsMedia, ThreadsInsights, ThreadsReplies, ThreadsConversation, CreateThreadResponse, CreateThreadParams, GetMediaParams, GetInsightsParams, GetRepliesParams } from '../types/threads.js';
|
|
7
|
+
export interface EnhancedThreadsConfig extends ThreadsConfig {
|
|
8
|
+
enableRateLimiting?: boolean;
|
|
9
|
+
enableCaching?: boolean;
|
|
10
|
+
enableWebhooks?: boolean;
|
|
11
|
+
rateLimitOptions?: {
|
|
12
|
+
maxTokens?: number;
|
|
13
|
+
refillRate?: number;
|
|
14
|
+
};
|
|
15
|
+
cacheOptions?: {
|
|
16
|
+
ttl?: number;
|
|
17
|
+
maxSize?: number;
|
|
18
|
+
};
|
|
19
|
+
}
|
|
20
|
+
export declare class EnhancedThreadsClient extends ThreadsClient {
|
|
21
|
+
private rateLimiter?;
|
|
22
|
+
private cache?;
|
|
23
|
+
private webhookManager?;
|
|
24
|
+
constructor(config: EnhancedThreadsConfig);
|
|
25
|
+
getProfile(fields?: string[]): Promise<ThreadsUser>;
|
|
26
|
+
getThreads(params?: GetMediaParams): Promise<ThreadsMedia[]>;
|
|
27
|
+
getThread(threadId: string, fields?: string[]): Promise<ThreadsMedia>;
|
|
28
|
+
createThread(params: CreateThreadParams): Promise<CreateThreadResponse>;
|
|
29
|
+
getThreadInsights(threadId: string, params: GetInsightsParams): Promise<ThreadsInsights[]>;
|
|
30
|
+
getUserInsights(params: GetInsightsParams): Promise<ThreadsInsights[]>;
|
|
31
|
+
getReplies(threadId: string, params?: GetRepliesParams): Promise<ThreadsReplies>;
|
|
32
|
+
getConversation(threadId: string, params?: GetRepliesParams): Promise<ThreadsConversation>;
|
|
33
|
+
replyToThread(threadId: string, text: string, replyControl?: CreateThreadParams['replyControl']): Promise<CreateThreadResponse>;
|
|
34
|
+
private checkRateLimit;
|
|
35
|
+
private invalidateCache;
|
|
36
|
+
getWebhookManager(): WebhookManager | undefined;
|
|
37
|
+
getCache(): AutoCleanCache | undefined;
|
|
38
|
+
getRateLimiter(): RateLimiter | undefined;
|
|
39
|
+
clearCache(): void;
|
|
40
|
+
resetRateLimit(): void;
|
|
41
|
+
getStats(): {
|
|
42
|
+
cache?: ReturnType<AutoCleanCache['stats']>;
|
|
43
|
+
rateLimiter?: {
|
|
44
|
+
tokens: number;
|
|
45
|
+
};
|
|
46
|
+
webhooks?: ReturnType<WebhookManager['stats']>;
|
|
47
|
+
};
|
|
48
|
+
}
|
|
49
|
+
//# sourceMappingURL=enhanced-threads-client.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"enhanced-threads-client.d.ts","sourceRoot":"","sources":["../../src/client/enhanced-threads-client.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,qBAAsB,SAAQ,aAAa;IAC1D,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,gBAAgB,CAAC,EAAE;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,YAAY,CAAC,EAAE;QACb,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED,qBAAa,qBAAsB,SAAQ,aAAa;IACtD,OAAO,CAAC,WAAW,CAAC,CAAc;IAClC,OAAO,CAAC,KAAK,CAAC,CAAiB;IAC/B,OAAO,CAAC,cAAc,CAAC,CAAiB;gBAE5B,MAAM,EAAE,qBAAqB;IAiC1B,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAkBnD,UAAU,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAkB5D,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IAkBrE,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAsBvE,iBAAiB,CAC9B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,eAAe,EAAE,CAAC;IAkBd,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAkBtE,UAAU,CACvB,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,gBAAgB,GACxB,OAAO,CAAC,cAAc,CAAC;IAkBX,eAAe,CAC5B,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,gBAAgB,GACxB,OAAO,CAAC,mBAAmB,CAAC;IAkBhB,aAAa,CAC1B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,YAAY,CAAC,EAAE,kBAAkB,CAAC,cAAc,CAAC,GAChD,OAAO,CAAC,oBAAoB,CAAC;YAwBlB,cAAc;IAS5B,OAAO,CAAC,eAAe;IAcvB,iBAAiB,IAAI,cAAc,GAAG,SAAS;IAO/C,QAAQ,IAAI,cAAc,GAAG,SAAS;IAOtC,cAAc,IAAI,WAAW,GAAG,SAAS;IAOzC,UAAU,IAAI,IAAI;IAOlB,cAAc,IAAI,IAAI;IAOtB,QAAQ,IAAI;QACV,KAAK,CAAC,EAAE,UAAU,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;QAC5C,WAAW,CAAC,EAAE;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;QACjC,QAAQ,CAAC,EAAE,UAAU,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;KAChD;CASF"}
|