Skip to content
Back to search

systemprompt-mcp-server

[DEPRECATED] Superseded by systempromptio/systemprompt-template and systempromptio/systemprompt-core. Reference MCP server implementation (OAuth 2.1, tools, prompts, resources, sampling, notifications).

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/systempromptio--systemprompt-mcp-server/badge.svg)](/listings/systempromptio--systemprompt-mcp-server)

HTML

<a href="/listings/systempromptio--systemprompt-mcp-server"><img src="/api/listings/systempromptio--systemprompt-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

🐳 Simplest Installation (Docker with npx)

Run the server instantly with Docker - no installation required:

Step 1: Create Reddit App & Initial Config

1. Create a Reddit app at [reddit.com/prefs/apps](https://reddit.com/prefs/apps) - Choose "script" type - Set redirect URI: `http://localhost:3000/oauth/reddit/callback`

2. Create initial `.env` file:

cat > .env << EOF
REDDIT_CLIENT_ID=your_reddit_client_id
REDDIT_CLIENT_SECRET=your_reddit_client_secret
JWT_SECRET=any_random_string_here
EOF

Step 2: Run the Server

# Run with Docker (pulls image automatically)
docker run -it --rm \
  -p 3000:3000 \
  --env-file .env \
  --name mcp-reddit \
  node:20-slim \
  npx @systemprompt/systemprompt-mcp-server

Step 3: Complete OAuth Authentication

1. In your MCP client, connect to `http://localhost:3000` 2. The OAuth flow will start automatically 3. Authorize the app in your browser 4. Copy the returned OAuth token

Step 4: Update Environment with Token

# Stop the container (Ctrl+C)

# Add the OAuth token to your .env file
echo "OAUTH_ACCESS_TOKEN=your_oauth_token_here" >> .env

# Restart with the token
docker run -it --rm \
  -p 3000:3000 \
  --env-file .env \
  node:20-slim \
  npx @systemprompt/systemprompt-mcp-server

Now you can use all Reddit tools with your authenticated session!

Installation

# Via npm
npm install -g @systemprompt/systemprompt-mcp-server

# Via npx (no installation)
npx @systemprompt/systemprompt-mcp-server

# Clone for development
git clone https://github.com/systempromptio/systemprompt-mcp-server.git
cd systemprompt-mcp-server
npm install
npm run build

Configuration

1. **Create Reddit App**: [reddit.com/prefs/apps](https://reddit.com/prefs/apps) - Choose "script" type - Set redirect URI: `http://localhost:3000/oauth/reddit/callback`

2. **Set Environment Variables**:

Create a `.env` file in the project root:

# Required for Reddit API
REDDIT_CLIENT_ID=your_reddit_client_id
REDDIT_CLIENT_SECRET=your_reddit_client_secret
JWT_SECRET=your_jwt_secret       # Secret for JWT signing

# Optional
PORT=3000                        # Server port (default: 3000)
OAUTH_ISSUER=http://localhost:3000  # OAuth issuer URL
REDIRECT_URL=http://localhost:3000/oauth/reddit/callback  # OAuth redirect
REDDIT_USER_AGENT=linux:systemprompt-mcp-reddit:v2.0.0   # Reddit user agent
REDDIT_USERNAME=your_reddit_username  # Your Reddit username (optional)
LOG_LEVEL=debug                  # Logging level (debug, info, warn, error)

**Note**: Environment variables are required for both local development and Docker deployment.

Running the Server

# Build the TypeScript code
npm run build

# Run the built server
node build/index.js

# Development with watch mode
npm run watch
# In another terminal:
node build/index.js

# With Docker
npm run docker

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 848 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. > ## ⚠️ Deprecated β€” no longer maintained
  2. >
  3. > This repository has been superseded. All new development and support lives in:
  4. >
  5. > - **[systempromptio/systemprompt-template](https://github.com/systempromptio/systemprompt-template)** β€” start here. Self-hosted evaluation of the full systemprompt.io AI governance infrastructure.
  6. > - **[systempromptio/systemprompt-core](https://github.com/systempromptio/systemprompt-core)** β€” the underlying Rust library (MCP, A2A, OAuth 2.1, audit, compile-time extensions).
  7. >
  8. > Learn more at [systemprompt.io](https://systemprompt.io).
  9. >
  10. > _The original README is preserved below for historical reference._
  11. ---
  12. # systemprompt-mcp-server
  13. [![npm version](https://img.shields.io/npm/v/@systemprompt/systemprompt-mcp-server.svg)](https://www.npmjs.com/package/@systemprompt/systemprompt-mcp-server)
  14. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  15. [![Twitter Follow](https://img.shields.io/twitter/follow/tyingshoelaces_?style=social)](https://twitter.com/tyingshoelaces_)
  16. [![Discord](https://img.shields.io/discord/1255160891062620252?color=7289da&label=discord)](https://discord.com/invite/wkAbSuPWpr)
  17. [Website](https://systemprompt.io) | [Documentation](https://systemprompt.io/mcp-server)
  18. ## Sponsored by systemprompt.io
  19. This MCP server implementation is **sponsored by [systemprompt.io](https://systemprompt.io)** β€” creators of the **world's first native mobile MCP client for iOS and Android** β€” and provided completely **free and open source** to the community.
  20. **If you find this project useful, we'd appreciate:**
  21. - ⭐ **A star on this repository**
  22. - πŸ‘ **A like/follow on our social channels**
  23. - πŸ”— **Sharing with your network**
  24. Your support helps us continue creating valuable open source tools for the AI community!
  25. > πŸš€ **Learn More**: For an interactive walkthrough of this implementation with live SDK testing, visit [systemprompt.io/mcp-server](https://systemprompt.io/mcp-server)
  26. A production-ready Model Context Protocol (MCP) server that demonstrates the **complete MCP specification** including OAuth 2.1, sampling, elicitation, structured data validation, and real-time notifications.
  27. **This implementation uses Reddit as a real-world example to demonstrate OAuth 2.1 flow and advanced MCP features**, but the architecture is designed to be easily adapted for any API that requires OAuth authentication.
  28. This server works with any MCP-compliant client that supports advanced features like sampling and notifications.
  29. ### πŸ” MCP Inspector Compatible
  30. This server is **fully compatible** with the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector), providing perfect support for:
  31. - βœ… **OAuth 2.1 Authentication** - Complete flow with PKCE
  32. - βœ… **Tools** - All Reddit interaction capabilities
  33. - βœ… **Prompts** - Dynamic content generation prompts
  34. - βœ… **Sampling** - AI-assisted content with human approval
  35. - βœ… **Notifications** - Real-time progress updates
  36. Test it yourself: `npm run inspector`
  37. ## 🌟 Why This Implementation Matters
  38. ### OAuth 2.1 Demonstration with Reddit
  39. This implementation uses **Reddit's API as a real-world example** to demonstrate how to build a complete OAuth 2.1 flow in an MCP server. Reddit was chosen because:
  40. - It requires OAuth authentication for most operations
  41. - It provides a rich API for demonstrating various MCP features
  42. - It's a well-documented, publicly accessible API
  43. - It showcases real-world authentication challenges and solutions
  44. **Note**: While this server uses Reddit, the OAuth implementation and architecture patterns are designed to be easily adapted for any OAuth-based API (GitHub, Google, Slack, etc.).
  45. ### Key Features Demonstrated
  46. This repository serves as the **gold standard** for MCP server implementations, showcasing:
  47. - **Complete MCP Spec Coverage**: Every feature from OAuth to sampling is implemented
  48. - **Production Architecture**: Multi-user sessions, security, and scalability built-in
  49. - **Developer Experience**: Clean code structure perfect for learning or forking
  50. - **Real-World OAuth Integration**: Full OAuth 2.1 flow with PKCE, JWT tokens, and session management
  51. - **AI-Native Design**: Deep integration with LLMs for content generation and analysis
  52. ## πŸ“š Table of Contents
  53. - [Features](#-features)
  54. - [Quick Start](#-quick-start)
  55. - [Architecture](#-architecture)
  56. - [OAuth Implementation](#-oauth-implementation)
  57. - [Tool Reference](#-tool-reference)
  58. - [Advanced Features](#-advanced-features)
  59. - [Using as a Template](#-using-as-a-template)
  60. - [Development](#-development)
  61. - [Code Structure](#-code-structure)
  62. - [Contributing](#-contributing)
  63. - [Related Projects](#-related-projects)
  64. ## ✨ Features
  65. ### Core MCP Implementation
  66. - **πŸ” OAuth 2.1 Flow**: Complete 8-step implementation with PKCE and JWT
  67. - **πŸ› οΈ Tool System**: Comprehensive tools for Reddit interaction
  68. - **πŸ“š Resources & Prompts**: Dynamic prompt generation and resource management
  69. - **πŸ€– Sampling**: AI-assisted content generation with human oversight
  70. - **πŸ’¬ Elicitation**: Dynamic user input gathering during tool execution
  71. - **βœ… Structured Data**: JSON Schema validation for all inputs/outputs
  72. - **πŸ“‘ Notifications**: Real-time progress updates and status notifications
  73. - **πŸ”„ Session Management**: Multi-user support with automatic cleanup
  74. ### Reddit Integration Features
  75. - **Content Discovery**: Search and analyze Reddit content
  76. - **User Interactions**: View messages, notifications, and manage account
  77. - **Subreddit Information**: Retrieve subreddit details and posts
  78. - **Comment Threads**: Navigate and analyze Reddit discussions
  79. ### Developer Features
  80. - **TypeScript**: Full type safety with comprehensive interfaces
  81. - **Modular Architecture**: Clean separation of concerns
  82. - **Error Handling**: Robust error management with custom error types
  83. - **Docker Support**: Ready for containerized deployment
  84. - **Testing**: Example test implementations included
  85. - **Documentation**: Extensive inline documentation and examples
  86. ## πŸš€ Quick Start
  87. ### 🐳 Simplest Installation (Docker with npx)
  88. Run the server instantly with Docker - no installation required:
  89. #### Step 1: Create Reddit App & Initial Config
  90. 1. Create a Reddit app at [reddit.com/prefs/apps](https://reddit.com/prefs/apps)
  91. - Choose "script" type
  92. - Set redirect URI: `http://localhost:3000/oauth/reddit/callback`
  93. 2. Create initial `.env` file:
  94. ```bash
  95. cat > .env << EOF
  96. REDDIT_CLIENT_ID=your_reddit_client_id
  97. REDDIT_CLIENT_SECRET=your_reddit_client_secret
  98. JWT_SECRET=any_random_string_here
  99. EOF
  100. ```
  101. #### Step 2: Run the Server
  102. ```bash
  103. # Run with Docker (pulls image automatically)
  104. docker run -it --rm \
  105. -p 3000:3000 \
  106. --env-file .env \
  107. --name mcp-reddit \
  108. node:20-slim \
  109. npx @systemprompt/systemprompt-mcp-server
  110. ```
  111. #### Step 3: Complete OAuth Authentication
  112. 1. In your MCP client, connect to `http://localhost:3000`
  113. 2. The OAuth flow will start automatically
  114. 3. Authorize the app in your browser
  115. 4. Copy the returned OAuth token
  116. #### Step 4: Update Environment with Token
  117. ```bash
  118. # Stop the container (Ctrl+C)
  119. # Add the OAuth token to your .env file
  120. echo "OAUTH_ACCESS_TOKEN=your_oauth_token_here" >> .env
  121. # Restart with the token
  122. docker run -it --rm \
  123. -p 3000:3000 \
  124. --env-file .env \
  125. node:20-slim \
  126. npx @systemprompt/systemprompt-mcp-server
  127. ```
  128. Now you can use all Reddit tools with your authenticated session!
  129. ### Installation
  130. ```bash
  131. # Via npm
  132. npm install -g @systemprompt/systemprompt-mcp-server
  133. # Via npx (no installation)
  134. npx @systemprompt/systemprompt-mcp-server
  135. # Clone for development
  136. git clone https://github.com/systempromptio/systemprompt-mcp-server.git
  137. cd systemprompt-mcp-server
  138. npm install
  139. npm run build
  140. ```
  141. ### Configuration
  142. 1. **Create Reddit App**: [reddit.com/prefs/apps](https://reddit.com/prefs/apps)
  143. - Choose "script" type
  144. - Set redirect URI: `http://localhost:3000/oauth/reddit/callback`
  145. 2. **Set Environment Variables**:
  146. Create a `.env` file in the project root:
  147. ```bash
  148. # Required for Reddit API
  149. REDDIT_CLIENT_ID=your_reddit_client_id
  150. REDDIT_CLIENT_SECRET=your_reddit_client_secret
  151. JWT_SECRET=your_jwt_secret # Secret for JWT signing
  152. # Optional
  153. PORT=3000 # Server port (default: 3000)
  154. OAUTH_ISSUER=http://localhost:3000 # OAuth issuer URL
  155. REDIRECT_URL=http://localhost:3000/oauth/reddit/callback # OAuth redirect
  156. REDDIT_USER_AGENT=linux:systemprompt-mcp-reddit:v2.0.0 # Reddit user agent
  157. REDDIT_USERNAME=your_reddit_username # Your Reddit username (optional)
  158. LOG_LEVEL=debug # Logging level (debug, info, warn, error)
  159. ```
  160. **Note**: Environment variables are required for both local development and Docker deployment.
  161. ### Running the Server
  162. ```bash
  163. # Build the TypeScript code
  164. npm run build
  165. # Run the built server
  166. node build/index.js
  167. # Development with watch mode
  168. npm run watch
  169. # In another terminal:
  170. node build/index.js
  171. # With Docker
  172. npm run docker
  173. ```
  174. ## πŸ—οΈ Architecture
  175. This implementation follows clean architecture principles with clear separation between layers:
  176. ```
  177. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  178. β”‚ Client Application β”‚
  179. β”‚ (systemprompt.io) β”‚
  180. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  181. β”‚ MCP Protocol
  182. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  183. β”‚ MCP Server Layer β”‚
  184. β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
  185. β”‚ β”‚ OAuth 2.1 β”‚ β”‚ Session β”‚ β”‚ Notification β”‚ β”‚
  186. β”‚ β”‚ Handler β”‚ β”‚ Manager β”‚ β”‚ Manager β”‚ β”‚
  187. β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
  188. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  189. β”‚
  190. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  191. β”‚ Handler Layer β”‚
  192. β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
  193. β”‚ β”‚ Tools β”‚ β”‚ Resources β”‚ β”‚ Sampling β”‚ β”‚
  194. β”‚ β”‚ Handler β”‚ β”‚ Handler β”‚ β”‚ Handler β”‚ β”‚
  195. β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
  196. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  197. β”‚
  198. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  199. β”‚ Service Layer β”‚
  200. β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
  201. β”‚ β”‚ Reddit β”‚ β”‚ Auth β”‚ β”‚ Fetch β”‚ β”‚
  202. β”‚ β”‚ Service β”‚ β”‚ Service β”‚ β”‚ Service β”‚ β”‚
  203. β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
  204. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  205. ```
  206. ### Key Components
  207. - **`src/server.ts`**: Main HTTP server setup and Express configuration
  208. - **`src/server/`**: Core server infrastructure (MCP, OAuth, auth management)
  209. - **`src/handlers/`**: Request handlers for tools, prompts, resources, and sampling
  210. - **`src/services/`**: Business logic and Reddit API integration
  211. - **`src/constants/`**: Tool definitions, server configuration, and schemas
  212. - **`src/types/`**: TypeScript type definitions and interfaces
  213. ## πŸ” OAuth Implementation
  214. This server implements the complete [MCP OAuth 2.1 specification](https://spec.modelcontextprotocol.io/specification/2024-11-05/authentication/):
  215. ### OAuth Flow Steps
  216. 1. **Initial 401 Response** ([src/server/oauth.ts](src/server/oauth.ts))
  217. ```typescript
  218. WWW-Authenticate: Bearer realm="MCP Reddit Server"
  219. ```
  220. 2. **Resource Metadata** ([src/server/oauth.ts](src/server/oauth.ts))
  221. ```json
  222. {
  223. "authorization_server": "http://localhost:3000/.well-known/oauth"
  224. }
  225. ```
  226. 3. **Authorization Server Metadata** ([src/server/oauth.ts](src/server/oauth.ts))
  227. - Token endpoint configuration
  228. - PKCE support declaration
  229. - Grant types supported
  230. 4. **Authorization Request** ([src/server/oauth.ts](src/server/oauth.ts))
  231. - PKCE code challenge
  232. - State parameter for CSRF protection
  233. - Reddit OAuth redirect handling
  234. 5. **Reddit OAuth Callback** ([src/server/oauth.ts](src/server/oauth.ts))
  235. - Reddit authorization handling
  236. - Secure state validation
  237. 6. **Token Exchange** ([src/server/oauth.ts](src/server/oauth.ts))
  238. - PKCE verification
  239. - JWT token generation
  240. - Reddit credentials embedding
  241. 7. **Authenticated Requests** ([src/server/middleware.ts](src/server/middleware.ts))
  242. - JWT validation
  243. - Session management
  244. - Request context injection
  245. ### Security Features
  246. - **PKCE Implementation**: Prevents authorization code interception
  247. - **JWT Tokens**: Secure credential storage and transmission
  248. - **Session Isolation**: Each user has isolated Reddit credentials
  249. - **Automatic Cleanup**: Sessions expire after inactivity
  250. ## πŸ› οΈ Tool Reference
  251. ### Content Discovery Tools
  252. #### `search_reddit`
  253. Search across Reddit with filters ([src/handlers/tools/search-reddit.ts](src/handlers/tools/search-reddit.ts))
  254. ```typescript
  255. {
  256. "query": "typescript MCP",
  257. "subreddit": "programming", // Optional specific subreddit
  258. "sort": "relevance",
  259. "time": "week",
  260. "limit": 10
  261. }
  262. ```
  263. #### `get_post`
  264. Fetch a specific post with comments ([src/handlers/tools/get-post.ts](src/handlers/tools/get-post.ts))
  265. ```typescript
  266. {
  267. "id": "post_id_here" // Reddit post ID
  268. }
  269. ```
  270. #### `get_channel`
  271. Get subreddit posts ([src/handlers/tools/get-channel.ts](src/handlers/tools/get-channel.ts))
  272. ```typescript
  273. {
  274. "subreddit": "programming",
  275. "sort": "hot" // "hot", "new", or "controversial"
  276. }
  277. ```
  278. ### User Interaction Tools
  279. #### `get_notifications`
  280. Fetch user notifications and messages ([src/handlers/tools/get-notifications.ts](src/handlers/tools/get-notifications.ts))
  281. ```typescript
  282. {
  283. "filter": "unread", // "all", "unread", "messages", "comments", "mentions"
  284. "limit": 25,
  285. "markRead": false
  286. }
  287. ```
  288. #### `get_comment`
  289. Retrieve a specific comment ([src/handlers/tools/get-comment.ts](src/handlers/tools/get-comment.ts))
  290. ```typescript
  291. {
  292. "id": "comment_id_here",
  293. "includeThread": true // Include full comment thread
  294. }
  295. ```
  296. ### Example and Development Tools
  297. #### `elicitation_example`
  298. Demonstrates user input gathering ([src/handlers/tools/elicitation-example.ts](src/handlers/tools/elicitation-example.ts))
  299. ```typescript
  300. {
  301. "type": "input", // "input", "confirm", "choice"
  302. "prompt": "Enter your choice",
  303. "options": ["option1", "option2"] // For choice type
  304. }
  305. ```
  306. #### `sampling_example`
  307. Demonstrates AI-assisted content generation ([src/handlers/tools/sampling-example.ts](src/handlers/tools/sampling-example.ts))
  308. ```typescript
  309. {
  310. "prompt": "Generate a code example",
  311. "maxTokens": 1000,
  312. "temperature": 0.7
  313. }
  314. ```
  315. #### `structured_data_example`
  316. Demonstrates structured data handling ([src/handlers/tools/structured-data-example.ts](src/handlers/tools/structured-data-example.ts))
  317. ```typescript
  318. {
  319. "format": "json", // "json", "table", "markdown"
  320. "data": { "key": "value" }
  321. }
  322. ```
  323. #### `validation_example`
  324. Demonstrates input validation ([src/handlers/tools/validation-example.ts](src/handlers/tools/validation-example.ts))
  325. ```typescript
  326. {
  327. "test_string": "example",
  328. "test_number": 42,
  329. "test_enum": "option1"
  330. }
  331. ```
  332. #### `mcp_logging`
  333. Request server to log messages ([src/handlers/tools/logging.ts](src/handlers/tools/logging.ts))
  334. ```typescript
  335. {
  336. "level": "info", // "debug", "info", "warning", "error"
  337. "message": "Debug message",
  338. "data": { "additional": "context" }
  339. }
  340. ```
  341. ## 🎯 Advanced Features
  342. ### Sampling (AI-Assisted Content Generation)
  343. The sampling implementation ([src/handlers/sampling.ts](src/handlers/sampling.ts)) follows the complete MCP specification:
  344. ```typescript
  345. // 1. Client requests AI assistance
  346. await client.callTool("sampling_example", {
  347. prompt: "Analyze this subreddit and suggest actions",
  348. maxTokens: 1000,
  349. temperature: 0.7
  350. });
  351. // 2. Server initiates sampling for content generation
  352. const samplingRequest = {
  353. method: "sampling/createMessage",
  354. params: {
  355. messages: [{
  356. role: "user",
  357. content: {
  358. type: "text",
  359. text: "Analyze this subreddit and suggest actions"
  360. }
  361. }],
  362. maxTokens: 1000,
  363. temperature: 0.7,
  364. _meta: {
  365. callback: "suggest_action"
  366. }
  367. }
  368. };
  369. // 3. AI generates content
  370. // 4. Callback processes the response
  371. // 5. Client receives the final result
  372. ```
  373. ### Elicitation (Dynamic Input Gathering)
  374. Example implementation ([src/handlers/tools/elicitation-example.ts](src/handlers/tools/elicitation-example.ts)):
  375. ```typescript
  376. // Call the elicitation example tool
  377. await client.callTool("elicitation_example", {
  378. type: "input",
  379. prompt: "Enter post title",
  380. options: []
  381. });
  382. // The tool demonstrates different elicitation types:
  383. // - "input": Text input from user
  384. // - "confirm": Yes/no confirmation
  385. // - "choice": Multiple choice selection
  386. ```
  387. ### Progress Notifications
  388. Real-time updates during operations ([src/handlers/notifications.ts](src/handlers/notifications.ts)):
  389. ```typescript
  390. // Send notifications during long-running operations
  391. await sendProgressNotification("Processing request...", sessionId);
  392. await sendSamplingCompleteNotification("Analysis complete", sessionId);
  393. // Notifications are automatically sent to the MCP client
  394. // providing real-time feedback during tool execution
  395. ```
  396. ### Structured Data Validation
  397. All inputs use Zod schema validation ([src/handlers/tool-handlers.ts](src/handlers/tool-handlers.ts)):
  398. ```typescript
  399. // Example Zod schema for Reddit search
  400. const SearchRedditSchema = z.object({
  401. query: z.string().min(1).max(500).describe("Search query"),
  402. subreddit: z.string().optional().describe("Optional subreddit filter"),
  403. sort: z.enum(["relevance", "hot", "new", "top"]).default("relevance"),
  404. time: z.enum(["hour", "day", "week", "month", "year", "all"]).default("all"),
  405. limit: z.number().int().min(1).max(100).default(25)
  406. });
  407. // Validation is automatic and provides detailed error messages
  408. const args = SearchRedditSchema.parse(request.params.arguments);
  409. ```
  410. ## 🎨 Using as a Template
  411. This codebase is designed to be forked and adapted for other MCP implementations:
  412. ### Step 1: Fork and Clone
  413. ```bash
  414. git clone https://github.com/your-username/your-mcp-server.git
  415. cd your-mcp-server
  416. ```
  417. ### Step 2: Replace Service Layer
  418. Replace Reddit-specific services in `src/services/` with your API:
  419. ```typescript
  420. // src/services/your-api/your-service.ts
  421. export class YourAPIService {
  422. async fetchData(params: YourParams): Promise<YourData> {
  423. // Your API integration
  424. }
  425. }
  426. ```
  427. ### Step 3: Define New Tools
  428. Create tools in `src/handlers/tools/`:
  429. ```typescript
  430. // src/handlers/tools/your-tool.ts
  431. export const yourTool: ToolDefinition = {
  432. schema: {
  433. name: "your_tool",
  434. description: "What your tool does",
  435. inputSchema: {
  436. type: "object",
  437. properties: {
  438. // Your parameters
  439. }
  440. }
  441. },
  442. handler: async (params, context) => {
  443. // Tool implementation
  444. }
  445. };
  446. ```
  447. ### Step 4: Update Configuration
  448. Modify `src/constants/server/server-config.ts`:
  449. ```typescript
  450. export const serverConfig = {
  451. name: "your-mcp-server",
  452. version: "1.0.0",
  453. description: "Your MCP server description"
  454. };
  455. export const serverCapabilities = {
  456. tools: {},
  457. prompts: {},
  458. resources: {},
  459. sampling: {}
  460. };
  461. ```
  462. ## πŸ’» Development
  463. ### Prerequisites
  464. - Node.js 18+
  465. - npm or yarn
  466. - Reddit account and app credentials
  467. ### Development Commands
  468. ```bash
  469. # Install dependencies
  470. npm install
  471. # Build TypeScript
  472. npm run build
  473. # Watch mode for development
  474. npm run watch
  475. # Run tests (requires OAuth tokens - see below)
  476. npm run test
  477. # Run end-to-end tests
  478. npm run e2e
  479. # Build and run with Docker
  480. npm run docker
  481. ```
  482. ### Testing
  483. #### Testing with MCP Inspector
  484. The server is fully compatible with the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector), which provides a powerful interface for testing all MCP features:
  485. ```bash
  486. # Build the server first
  487. npm run build
  488. # Launch the inspector with the built server
  489. npx @modelcontextprotocol/inspector build/index.js
  490. ```
  491. This command will:
  492. 1. Build the TypeScript project
  493. 2. Open the MCP Inspector documentation in your browser
  494. 3. Launch the inspector connected to your local server
  495. #### Full Feature Compatibility
  496. The Reddit MCP server works perfectly with the MCP Inspector for:
  497. - **πŸ” OAuth Authentication**: Complete OAuth 2.1 flow with PKCE support
  498. - **πŸ› οΈ Tools**: All Reddit interaction tools (search, get posts, notifications, etc.)
  499. - **πŸ“š Prompts**: Dynamic prompt generation for content creation
  500. - **πŸ€– Sampling**: AI-assisted content generation with human-in-the-loop approval
  501. - **πŸ“‘ Notifications**: Real-time progress updates during operations
  502. - **βœ… Structured Data**: Full JSON Schema validation for inputs/outputs
  503. The inspector provides:
  504. - Interactive tool testing with parameter validation
  505. - OAuth flow visualization and debugging
  506. - Sampling request/response inspection
  507. - Real-time notification monitoring
  508. - Session management visibility
  509. #### Setting Up for Testing
  510. **Important**: To run tests that interact with Reddit, you need to complete the OAuth flow first:
  511. 1. **Start the server and open MCP Inspector**:
  512. ```bash
  513. # Build and start the server
  514. npm run build
  515. node build/index.js
  516. # In another terminal, open the MCP Inspector
  517. npx @modelcontextprotocol/inspector build/index.js
  518. ```
  519. 2. **Complete OAuth Authentication**:
  520. - The Inspector will prompt you to authenticate
  521. - Follow the OAuth flow to authorize with Reddit
  522. - After successful authentication, the server stores tokens
  523. 3. **Save OAuth Tokens for Testing**:
  524. - Once authenticated via Inspector, copy the generated tokens
  525. - Add them to your `.env` file for persistent testing:
  526. ```bash
  527. # Add these to your .env after completing OAuth
  528. REDDIT_ACCESS_TOKEN=your_access_token
  529. REDDIT_REFRESH_TOKEN=your_refresh_token
  530. ```
  531. #### Running Tests
  532. ```bash
  533. # Run all tests (requires OAuth tokens in .env)
  534. npm run test
  535. # Run end-to-end tests
  536. npm run e2e
  537. ```
  538. #### Testing with Docker
  539. ```bash
  540. # Build and run with Docker
  541. npm run docker
  542. # Run the server with npx in Docker
  543. docker run --rm -it \
  544. -p 3000:3000 \
  545. -e REDDIT_CLIENT_ID=your_id \
  546. -e REDDIT_CLIENT_SECRET=your_secret \
  547. -e JWT_SECRET=your_jwt_secret \
  548. node:18-alpine \
  549. npx @systemprompt/mcp-server
  550. ```
  551. #### Manual Testing
  552. ```bash
  553. # Test OAuth flow manually
  554. curl -X POST http://localhost:3000/mcp/v1/initialize \
  555. -H "Content-Type: application/json" \
  556. -d '{"protocolVersion": "2024-11-05", "capabilities": {}}'
  557. # The response will include auth details if tokens are needed
  558. ```
  559. ### Docker Development
  560. #### Quick Start with Docker
  561. ```bash
  562. # Build and run with docker-compose (recommended)
  563. npm run docker:build-and-run
  564. ```
  565. #### Manual Docker Commands
  566. ```bash
  567. # Build image
  568. docker build -t systemprompt-mcp-reddit .
  569. # Run with environment variables
  570. docker run -p 3001:3001 \
  571. -e REDDIT_CLIENT_ID=your_id \
  572. -e REDDIT_CLIENT_SECRET=your_secret \
  573. -e JWT_SECRET=your_jwt_secret \
  574. systemprompt-mcp-reddit
  575. ```
  576. #### Environment Variables for Docker
  577. Create a `.env` file in the project root with the following variables:
  578. ```bash
  579. # Required - Reddit OAuth Application Credentials
  580. REDDIT_CLIENT_ID=your_reddit_client_id
  581. REDDIT_CLIENT_SECRET=your_reddit_client_secret
  582. # Optional - Server Configuration
  583. MCP_PORT=3001 # Port for the MCP server (default: 3001)
  584. JWT_SECRET=your_jwt_secret # Secret for JWT signing (default: auto-generated)
  585. DEBUG=true # Enable debug logging (default: false)
  586. ```
  587. **Important**: The `docker:build-and-run` command requires these environment variables to be set either in a `.env` file or exported in your shell. Without proper Reddit credentials, the OAuth flow will not work.
  588. ## πŸ“ Code Structure
  589. ```
  590. systemprompt-mcp-reddit/
  591. β”œβ”€β”€ src/
  592. β”‚ β”œβ”€β”€ index.ts # Main entry point
  593. β”‚ β”œβ”€β”€ server.ts # HTTP server setup
  594. β”‚ β”œβ”€β”€ server/ # Server infrastructure
  595. β”‚ β”‚ β”œβ”€β”€ mcp.ts # MCP protocol handler with session management
  596. β”‚ β”‚ β”œβ”€β”€ oauth.ts # OAuth 2.1 implementation
  597. β”‚ β”‚ β”œβ”€β”€ middleware.ts # Express middleware (rate limiting, auth)
  598. β”‚ β”‚ β”œβ”€β”€ auth-store.ts # Authentication storage
  599. β”‚ β”‚ └── config.ts # Server configuration
  600. β”‚ β”œβ”€β”€ handlers/ # Request handlers
  601. β”‚ β”‚ β”œβ”€β”€ tool-handlers.ts # Tool execution and validation
  602. β”‚ β”‚ β”œβ”€β”€ prompt-handlers.ts # Prompt processing
  603. β”‚ β”‚ β”œβ”€β”€ resource-handlers.ts # Resource management
  604. β”‚ β”‚ β”œβ”€β”€ sampling.ts # AI sampling implementation
  605. β”‚ β”‚ β”œβ”€β”€ notifications.ts # Real-time notifications
  606. β”‚ β”‚ β”œβ”€β”€ callbacks/ # Sampling callback handlers
  607. β”‚ β”‚ └── tools/ # Individual tool implementations
  608. β”‚ β”œβ”€β”€ services/ # Business logic
  609. β”‚ β”‚ └── reddit/ # Reddit API integration
  610. β”‚ β”œβ”€β”€ constants/ # Configuration and definitions
  611. β”‚ β”‚ β”œβ”€β”€ tools.ts # Tool definitions
  612. β”‚ β”‚ β”œβ”€β”€ resources.ts # Resource definitions
  613. β”‚ β”‚ β”œβ”€β”€ sampling/ # Sampling prompt templates
  614. β”‚ β”‚ β”œβ”€β”€ server/ # Server configuration constants
  615. β”‚ β”‚ └── tool/ # Individual tool constants
  616. β”‚ β”œβ”€β”€ types/ # TypeScript definitions
  617. β”‚ β”‚ β”œβ”€β”€ reddit.ts # Reddit-specific types
  618. β”‚ β”‚ β”œβ”€β”€ config.ts # Configuration types
  619. β”‚ β”‚ β”œβ”€β”€ sampling.ts # Sampling types
  620. β”‚ β”‚ └── request-context.ts # Request context types
  621. β”‚ └── utils/ # Helper functions
  622. β”‚ β”œβ”€β”€ logger.ts # Logging utilities
  623. β”‚ β”œβ”€β”€ reddit-transformers.ts # Reddit data transformers
  624. β”‚ └── validation.ts # Validation utilities
  625. β”œβ”€β”€ scripts/ # Development and testing scripts
  626. β”œβ”€β”€ docker-compose.yml # Docker configuration
  627. β”œβ”€β”€ tsconfig.json # TypeScript configuration
  628. └── package.json # Project configuration
  629. ```
  630. ### Key Files
  631. - **[src/index.ts](src/index.ts)**: Application entry point
  632. - **[src/server.ts](src/server.ts)**: HTTP server setup and Express configuration
  633. - **[src/server/mcp.ts](src/server/mcp.ts)**: MCP protocol implementation with session management
  634. - **[src/server/oauth.ts](src/server/oauth.ts)**: Complete OAuth 2.1 flow
  635. - **[src/handlers/tool-handlers.ts](src/handlers/tool-handlers.ts)**: Tool execution with Zod validation
  636. - **[src/handlers/sampling.ts](src/handlers/sampling.ts)**: AI sampling implementation
  637. - **[src/services/reddit/reddit-service.ts](src/services/reddit/reddit-service.ts)**: Reddit API integration
  638. ## 🀝 Contributing
  639. We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
  640. ### Development Process
  641. 1. Fork the repository
  642. 2. Create a feature branch
  643. 3. Make your changes with tests
  644. 4. Submit a pull request
  645. ### Code Style
  646. - Use TypeScript for all code
  647. - Follow the existing patterns
  648. - Add JSDoc comments for public APIs
  649. - Include tests for new features
  650. ## πŸ”— Related Projects
  651. - **[Interactive Implementation Guide](https://systemprompt.io/mcp-server)**: Live testing and tutorial
  652. - **[MCP Specification](https://spec.modelcontextprotocol.io)**: Official MCP documentation
  653. - **[systemprompt.io Documentation](https://systemprompt.io/documentation)**: Platform documentation
  654. ## πŸ“„ License
  655. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  656. ## πŸ™ Acknowledgments
  657. - [Anthropic](https://anthropic.com) for the MCP specification
  658. - [Reddit](https://reddit.com) for their comprehensive API
  659. - The MCP community for feedback and contributions
  660. ---
  661. Built with ❀️ by the [systemprompt.io](https://systemprompt.io) team
  662. For support, join our [Discord](https://discord.com/invite/wkAbSuPWpr) or reach out on [Twitter](https://twitter.com/tyingshoelaces_)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.