Smart Prompts

You run a Smart Prompts MCP Server that fetches prompts directly from GitHub repositories, organizes them, and makes them available to an MCP client. It supports intelligent discovery, workflow composition, usage analytics, and real-time updates so you can build, search, and execute prompts efficiently within your MCP ecosystem.

How to use

Connect an MCP client to your local MCP server instance to start discovering, composing, and using prompts. The server exposes a local runtime that you run on your machine. You will provide your GitHub details so prompts can be discovered from your repositories, and then you can search, view, and assemble prompts into workflows.

Recommended usage pattern:

• Start the local MCP server process from your development environment.
• Set up the required environment variables to access your GitHub prompts.
• Use your MCP client to search for prompts by keywords, categories, or tags.
• View individual prompts and, if needed, compose multiple prompts into a single workflow for execution.
• If you work with private repositories, ensure your GitHub token has the right scopes.

How to install

# Step 1: Clone the repository
git clone https://github.com/jezweb/smart-prompts-mcp.git
cd smart-prompts-mcp

# Step 2: Install dependencies
npm install

# Step 3: Build the project
npm run build

# Step 4: Verify installation
./verify-install.sh

Step-by-step prerequisites you need before install:
- Node.js 18+ installed
- npm or yarn package manager
- Git installed and configured
- GitHub account for accessing prompt repositories
- GitHub Personal Access Token for private repos or to avoid rate limits.

Configuration and startup notes

Provide GitHub access details and optional cache controls through environment variables. The server can fetch prompts from a GitHub repository, optionally using a specific branch and subdirectory.

Example environment configuration used by the local MCP client setup:

• GITHUB_OWNER: your GitHub username or organization
• GITHUB_REPO: repository containing prompts
• GITHUB_BRANCH: branch to use (default: main)
• GITHUB_PATH: subdirectory path inside the repository (optional)
• GITHUB_TOKEN: personal access token with appropriate scopes
• CACHE_TTL: cache time-to-live in milliseconds
• CACHE_REFRESH_INTERVAL: auto-refresh interval in milliseconds
• ENABLE_SEMANTIC_SEARCH: enable advanced search features
• ENABLE_PROMPT_COMPOSITION: enable prompt composition features
• ENABLE_USAGE_TRACKING: enable usage analytics

Advanced client configuration examples

If you use Claude Desktop on macOS, point the MCP client at the local server with the required environment variables so the client can access prompts.

Example for Claude Desktop configuration (paths shown as placeholders):

• command: node
• args: ["/absolute/path/to/smart-prompts-mcp/dist/index.js"]
• env: GITHUB_OWNER, GITHUB_REPO, GITHUB_TOKEN

Troubleshooting and tips

Common issues include missing or invalid GitHub tokens, rate limits, or misconfigured repository paths. Ensure your GITHUB_TOKEN is set correctly in the environment and that the repository path and branch exist.

If you run into connectivity or startup issues, verify that required environment variables are present and the server process is running with the correct node runtime.

Prompt organization and best practices

Organize prompts in a GitHub repository with clear folder structure and descriptive file names. Use consistent frontmatter and naming conventions so the MCP server can discover and parse prompts reliably.

Testing and development

You can run the server’s test suite to ensure reliability and observe performance benchmarks. Use the provided npm scripts to run tests, watch for changes, generate coverage, and verify installation.

Available tools

search_prompts

Search by keyword, category, or tags to find prompts across the repository

list_prompt_categories

Browse categories with counts to understand available prompts

get_prompt

Retrieve the full content of a specific prompt by name

create_github_prompt

Create new prompts directly in GitHub from the MCP interface

compose_prompts

Combine multiple prompts into a workflow or composite prompt

prompts_help

Get contextual help and guidance for using prompts

check_github_status

Verify GitHub connection and repository accessibility