README.md•9.7 kB
# JP's MCP Collection
JP's personal collection of [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) modules that provides a set of utility functions for Claude and other AI assistants. Built using the MCP SDK, this server exposes tools for system operations, Google services integration, and AI-powered text processing.
## Overview
MCPs are built using the MCP SDK and exposes a set of tools that can be used by AI assistants to interact with:
- System command execution
- File system operations
- Google Sheets integration
- Google Tasks management
- OpenAI chat completion and grammar checking
- Dynamic prompt loading from markdown files
## Features
### System Operations
- Command Execution: Run shell commands on the system with proper error handling and safety checks
### File System Operations
- Move Files to Trash: Safely delete files by moving them to the system trash
- Read Images: Read image files and return base64-encoded content with metadata
### Google Sheets Integration
- List Sheets: Get available sheets in the configured spreadsheet
- Read Sheet Content: Read data from specific ranges with pagination support
- Update Sheets: Modify cell values in spreadsheets
- Delete Rows: Remove specific rows from sheets
- Get Sheet Properties: Retrieve metadata about sheet structure
- Conditional Formatting: Add row-based conditional formatting rules
### Google Tasks Management
- Task Lists: Create, update, delete, and list task lists
- Tasks: Full CRUD operations for tasks including creation, updates, completion, and deletion
- Subtasks: Create hierarchical task structures
- Task Properties: Manage due dates, notes, and task status
### AI-Powered Text Processing
- Chat Completion: Send prompts to OpenAI's GPT models with customizable parameters
- Grammar Checking: Improve text grammar and clarity using AI
### Dynamic Prompt Management
- Automatic Prompt Loading: Loads prompts from markdown files at server startup
- Flexible Configuration: Configure prompt directory via environment variables
- Smart Naming: Auto-generate prompt names from filenames when not specified in frontmatter
- Frontmatter Support: Parse markdown frontmatter for prompt metadata
## Usage
The server runs using Deno and can be started in development mode:
```bash
# Run in development mode
npm run dev
# Run with the MCP inspector for debugging
npm run monitor
# Format code
npm run format
```
## Project Organization
### Directory Structure
```
jp-mcps/
├── package.json # Project configuration and dependencies
├── README.md # Documentation
├── .env.example # Environment variables template
├── prompts/ # Default directory for dynamic prompts
└── src/ # Source code
├── modules/ # Modular MCP tool implementations
│ ├── command/ # System command execution
│ │ ├── functions/
│ │ │ ├── run-command.ts
│ │ │ └── index.ts
│ │ ├── registerCommand.ts
│ │ └── index.ts
│ ├── dynamic-prompts/ # Dynamic prompt loading
│ │ ├── functions/
│ │ │ ├── load-prompts.ts
│ │ │ └── index.ts
│ │ ├── utils/
│ │ │ ├── to-snake-case.ts
│ │ │ └── index.ts
│ │ ├── registerDynamicPrompts.ts
│ │ └── index.ts
│ ├── filesystem/ # File system operations
│ │ ├── functions/
│ │ │ ├── move-file-to-trash.ts
│ │ │ ├── read-image.ts
│ │ │ └── index.ts
│ │ ├── registerFilesystem.ts
│ │ └── index.ts
│ ├── hello/ # Reference implementation module
│ ├── openai/ # OpenAI API integration
│ │ ├── functions/
│ │ │ ├── chat-completion.ts
│ │ │ ├── check-grammar.ts
│ │ │ └── index.ts
│ │ ├── registerOpenAI.ts
│ │ └── index.ts
│ ├── sheets/ # Google Sheets API integration
│ │ ├── functions/
│ │ │ ├── list-sheets.ts
│ │ │ ├── list-sheet-content.ts
│ │ │ ├── update-sheet.ts
│ │ │ ├── delete-row.ts
│ │ │ ├── get-sheet-properties.ts
│ │ │ ├── add-row-conditional-formatting.ts
│ │ │ └── index.ts
│ │ ├── registerGoogleSheets.ts
│ │ ├── utils.ts
│ │ └── index.ts
│ └── tasks/ # Google Tasks API integration
│ ├── functions/
│ │ ├── list-task-lists.ts
│ │ ├── create-task-list.ts
│ │ ├── update-task-list.ts
│ │ ├── delete-task-list.ts
│ │ ├── list-tasks.ts
│ │ ├── create-task.ts
│ │ ├── update-task.ts
│ │ ├── complete-task.ts
│ │ ├── delete-task.ts
│ │ ├── create-subtask.ts
│ │ └── index.ts
│ ├── registerGoogleTasks.ts
│ ├── client.ts
│ └── index.ts
└── index.ts # Main entry point
```
### Code Organization
The JP MCPs project follows a modular architecture designed for maintainability and extensibility:
1. Main Entry Point: `src/index.ts` initializes the MCP server and registers all available tools.
2. Modular Functions: Each capability is encapsulated in its own module within the `modules` directory with standardized patterns:
- Each module has a `functions/` directory containing individual function implementations
- Functions are named in kebab-case for consistency
- Each function file includes its Zod input schema alongside the implementation
- Modules export their functions and corresponding schema definitions for type safety
- Each function follows a consistent error handling pattern
3. MCP Tool Registration: Tools are registered in module-specific register files using the `server.tool()` method which takes:
- A tool name (used by Claude to invoke the function)
- A schema definition (using Zod for runtime type validation)
- An async handler function implementing the tool's logic
4. Response Formatting: Each function formats its responses consistently as an object with `content` property containing text output.
5. Error Handling: Comprehensive error handling with a TypeScript-safe approach using a utility function `getErrorMessage()` that properly handles both Error objects and unknown error types.
### Design Patterns
JP MCPs employs several key design patterns:
- Facade Pattern: Each module presents a simplified interface to complex subsystems (APIs, filesystem, etc.)
- Function-based Organization: Clean separation of concerns with focused functions for each operation
- Schema Validation: All inputs are validated using Zod schemas before processing
- Consistent Error Handling: Try/catch blocks with standardized error responses
- Type Safety: Heavy use of TypeScript and `zod.infer` for type definitions
## Dependencies
- `@modelcontextprotocol/sdk`: Core MCP SDK for building MCP servers
- `@googleapis/sheets`: Google Sheets API client
- `@googleapis/tasks`: Google Tasks API client
- `google-auth-library`: Authentication for Google services
- `gray-matter`: Markdown frontmatter parsing for dynamic prompts
- `openai`: OpenAI API client for chat completion and text processing
- `execa`: Process execution for running system commands
- `trash`: Safe file deletion by moving to system trash
- `zod`: Schema validation and type safety
## Environment Variables
The following environment variables need to be configured:
- `OPENAI_API_KEY`: Your OpenAI API key for chat completion and grammar checking
- `GOOGLE_CLIENT_ID`: Google OAuth client ID for Tasks API
- `GOOGLE_CLIENT_SECRET`: Google OAuth client secret for Tasks API
- `GOOGLE_REDIRECT_URI`: Google OAuth redirect URI for Tasks API
- `GOOGLE_REFRESH_TOKEN`: Google OAuth refresh token for Tasks API
- `PROMPTS_DIRECTORY`: Directory path containing markdown prompt files (defaults to "./prompts")
### Dynamic Prompts Setup
Create markdown files in your prompts directory with frontmatter:
```markdown
---
name: my_prompt
description: Description of what this prompt does
---
Your prompt content here...
```
Naming Rules:
- If `name` is provided in frontmatter, it will be used as-is
- If `name` is missing, the filename (without .md) will be converted to snake_case
- If `description` is missing, it defaults to an empty string
Example:
- File: `Code Review.md` → Prompt name: `code_review`
- File: `generate-tests.md` → Prompt name: `generate_tests`
## Integration
JP MCPs is designed to be used as a tool provider for AI assistants like Claude through the Model Context Protocol, which allows the assistant to invoke functions defined in this server.
## Security Notes
- Command execution includes safety checks for potentially dangerous operations
- File operations are limited to safe actions (move to trash, read images)
- All API calls are properly authenticated and use official client libraries
- Input validation is performed using Zod schemas before any operations
- Dynamic prompts are loaded from configurable directories to avoid hardcoded paths