@customer-support-success/pylon-mcp-server 1.5.2

package/.env.example

@@ -0,0 +1,5 @@
+# Pylon MCP Server Environment Variables
+
+# Pylon API Token (required)
+# Generate this token in your Pylon dashboard
+PYLON_API_TOKEN=your_pylon_api_token_here

package/.eslintrc.cjs

@@ -0,0 +1,29 @@
+module.exports = {
+  root: true,
+  env: {
+    es2022: true,
+    node: true,
+  },
+  parser: '@typescript-eslint/parser',
+  plugins: ['@typescript-eslint', 'vitest'],
+  extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
+  rules: {
+    'no-console': 'off',
+    '@typescript-eslint/no-explicit-any': 'off',
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    'vitest/no-focused-tests': 'error',
+    'vitest/no-identical-title': 'error',
+    'vitest/expect-expect': 'warn',
+  },
+  ignorePatterns: ['dist', '**/*.d.ts'],
+  overrides: [
+    {
+      files: ['tests/**/*.{ts,tsx}'],
+      env: { node: true },
+      rules: {
+        'no-console': 'off',
+        '@typescript-eslint/no-unused-vars': 'off',
+      },
+    },
+  ],
+};

package/.prettierrc.json

@@ -0,0 +1,6 @@
+{
+  "singleQuote": true,
+  "semi": true,
+  "trailingComma": "es5",
+  "printWidth": 100
+}

package/CHANGELOG.md

@@ -0,0 +1,137 @@
+# Changelog
+
+All notable changes to the Pylon MCP Server will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.4.0] - 2025-12-24
+
+### Changed
+
+- Clarified tool guidance for issue lookups: when given a ticket/issue number, use `pylon_get_issue` first; reserve message-history tools for when conversation bodies are needed.
+- Improved tool input schema descriptions to accept user-provided ticket numbers directly without extra lookup steps.
+
+### Added
+
+- Tests asserting the updated tool descriptions and guidance.
+
+## [1.2.0] - 2024-12-05
+
+### Added
+
+- **Attachment Support** - Full support for file attachments in Pylon
+  - New `PylonAttachment` interface with id, name, url, and description fields
+  - Updated `PylonMessage` interface to include optional `attachments` array
+  - New tool: `pylon_get_attachment` - Get details of a specific attachment by ID
+  - New tool: `pylon_create_attachment_from_url` - Create attachment from a URL
+  - New method: `PylonClient.getAttachment(attachmentId)` - Fetch attachment metadata
+  - New method: `PylonClient.createAttachment(file, description?)` - Upload file as attachment
+  - New method: `PylonClient.createAttachmentFromUrl(fileUrl, description?)` - Create from URL
+  - Messages now properly include attachment information when present
+
+- **Comprehensive Test Coverage** - Professional testing infrastructure
+  - Added Vitest testing framework with 17 passing unit tests
+  - Test coverage for all attachment methods (6 tests)
+  - Test coverage for core functionality: users, issues, contacts, messages (11 tests)
+  - Test scripts: `npm test`, `npm run test:watch`, `npm run test:ui`, `npm run test:coverage`
+  - Automated testing for error handling (404, network errors)
+  - Mock-based testing for fast, reliable test execution
+  - Full TypeScript support in tests
+
+### Changed
+
+- Tool count increased from 24+ to **26+ tools**
+- Enhanced message handling to support attachments
+- Improved documentation with testing section in README and CLAUDE.md
+
+### Improved
+
+- Better code quality with automated test validation
+- Regression prevention through comprehensive test suite
+- Developer experience with watch mode and interactive test UI
+- Documentation now includes testing instructions and coverage details
+
+## [1.1.0] - 2024-12-04
+
+### Added
+
+- **New Tool: `pylon_get_issue_with_messages`** - Get a complete issue with all messages in a single efficient call
+  - Combines issue details and message history into one API call
+  - Uses `Promise.all()` for parallel fetching to improve performance
+  - Returns structured JSON with both `issue` and `messages` properties
+  - More efficient than calling `pylon_get_issue` and `pylon_get_issue_messages` separately
+
+### Changed
+
+- **All MCP responses now return valid JSON** - Improved consistency across all tools
+  - `pylon_snooze_issue` now returns JSON object with `success`, `message`, `issue_id`, and `snoozed_until`
+  - `pylon_delete_webhook` now returns JSON object with `success`, `message`, and `webhook_id`
+  - Previously these returned plain text strings
+  - All 30 tool handlers now guarantee JSON output for better parseability
+
+### Improved
+
+- Enhanced documentation with new tool examples
+- Updated tool count from 23+ to 24+ tools
+- Better response structure for operation confirmations
+
+## [1.0.0] - 2024-12-03
+
+### Added
+
+- Initial release of Pylon MCP Server
+- 23 comprehensive tools covering Pylon API functionality:
+  - User Management (`pylon_get_me`, `pylon_get_users`, `pylon_search_users`)
+  - Contact Management (`pylon_get_contacts`, `pylon_create_contact`, `pylon_search_contacts`)
+  - Issue Management (`pylon_get_issues`, `pylon_create_issue`, `pylon_get_issue`, `pylon_update_issue`, `pylon_snooze_issue`, `pylon_search_issues`)
+  - Message Management (`pylon_get_issue_messages`, `pylon_create_issue_message`)
+  - Knowledge Base (`pylon_get_knowledge_bases`, `pylon_get_knowledge_base_articles`, `pylon_create_knowledge_base_article`)
+  - Team Management (`pylon_get_teams`, `pylon_get_team`, `pylon_create_team`)
+  - Account Management (`pylon_get_accounts`, `pylon_get_account`)
+  - Tag Management (`pylon_get_tags`, `pylon_create_tag`)
+  - Ticket Forms (`pylon_get_ticket_forms`, `pylon_create_ticket_form`)
+  - Webhook Management (`pylon_get_webhooks`, `pylon_create_webhook`, `pylon_delete_webhook`)
+- TypeScript implementation with full type safety
+- Axios-based HTTP client for Pylon API
+- MCP SDK integration for Augment Code and Claude Desktop
+- Smithery deployment configuration
+- Comprehensive documentation and examples
+- GCP Artifact Registry publishing support
+- Security audit and compliance documentation
+
+### Security
+
+- No hardcoded secrets or API tokens
+- Environment variable-based authentication
+- HTTPS-only API communication
+- Zero dependency vulnerabilities
+- SOC-2 and GDPR compliance considerations
+
+---
+
+## Release Notes Format
+
+### Added
+
+New features and capabilities
+
+### Changed
+
+Changes to existing functionality
+
+### Deprecated
+
+Features that will be removed in future versions
+
+### Removed
+
+Features that have been removed
+
+### Fixed
+
+Bug fixes
+
+### Security
+
+Security improvements and vulnerability fixes

package/CLAUDE.md

@@ -0,0 +1,187 @@
+# Claude Development Guide
+
+This document provides context for Claude when working on the Pylon MCP Server project.
+
+## Project Overview
+
+This is an MCP (Model Context Protocol) server that provides comprehensive integration with the Pylon API. Pylon is a customer support and helpdesk platform, and this server exposes 26+ tools covering all major API functionality.
+
+## Architecture
+
+- **Language**: TypeScript with Node.js runtime
+- **MCP Framework**: `@modelcontextprotocol/sdk`
+- **HTTP Client**: Axios for API communication
+- **Build System**: TypeScript compiler
+- **Deployment**: Smithery platform
+
+## Key Files
+
+- `src/pylon-client.ts` - Pylon API client with authentication and all endpoint methods
+- `src/index.ts` - MCP server implementation with tool definitions and handlers
+- `smithery.yaml` - Smithery deployment configuration
+- `package.json` - Dependencies and build scripts
+
+## API Coverage
+
+The server implements comprehensive Pylon API coverage:
+
+### Authentication
+
+- Base URL: `https://api.usepylon.com`
+- Authentication: Bearer JWT tokens
+- Environment variable: `PYLON_API_TOKEN`
+
+### Implemented Endpoints
+
+**User Management** (`/me`, `/users`, `/users/search`)
+**Contact Management** (`/contacts`, `/contacts/search`)
+**Issue Management** (`/issues`, `/issues/search`, `/issues/{id}`, `/issues/{id}/snooze`, `/issues/{id}/messages`)
+**Knowledge Base** (`/knowledge-bases`, `/knowledge-bases/{id}/articles`)
+**Team Management** (`/teams`, `/teams/{id}`)
+**Account Management** (`/accounts`, `/accounts/{id}`)
+**Tag Management** (`/tags`)
+**Ticket Forms** (`/ticket-forms`)
+**Webhook Management** (`/webhooks`)
+**Attachment Management** (`/attachments`, `/attachments/{id}`)
+
+## Development Commands
+
+```bash
+npm install          # Install dependencies
+npm run build        # Build TypeScript
+npm run dev         # Run in development mode
+npm start           # Run built version
+```
+
+## Testing
+
+### Unit Tests
+
+The project includes comprehensive unit test coverage using Vitest:
+
+```bash
+npm test              # Run all tests
+npm run test:watch    # Watch mode
+npm run test:ui       # Interactive UI
+npm run test:coverage # Coverage report
+```
+
+**Test Files:**
+
+- `tests/pylon-client.attachments.test.ts` - Attachment API tests (6 tests)
+- `tests/pylon-client.core.test.ts` - Core functionality tests (11 tests)
+
+**Coverage:**
+
+- ✅ All attachment methods (get, create from URL, file upload)
+- ✅ User management (get, search)
+- ✅ Issue management (CRUD operations, filtering)
+- ✅ Contact management (get, search, create)
+- ✅ Message management (with attachments)
+- ✅ Error handling (404, network errors)
+
+### Integration Testing
+
+To test the MCP server with a real client:
+
+1. Build the project: `npm run build`
+2. Configure in your preferred client:
+   - **Augment Code**: Use Easy MCP feature in VS Code or JetBrains
+   - **Claude Desktop**: Add to MCP settings configuration
+3. Use natural language to test tools:
+   - "Get my Pylon user info" → `pylon_get_me`
+   - "Show recent issues" → `pylon_get_issues`
+   - "Search for contacts" → `pylon_search_contacts`
+
+## Deployment
+
+### Local Development
+
+- Requires `PYLON_API_TOKEN` environment variable
+- Can be configured in:
+  - **Augment Code**: Easy MCP feature (VS Code/JetBrains)
+  - **Claude Desktop**: MCP settings configuration
+- Use built `dist/index.js` as entrypoint
+- Can run with `npx pylon-mcp-server` after publishing to npm
+
+### Smithery Production
+
+- Uses `smithery.yaml` configuration
+- Automatic dependency installation and build
+- Environment variable configuration through Smithery UI
+
+## Code Patterns
+
+### Adding New API Endpoints
+
+1. **Add interface** in `pylon-client.ts`:
+
+   ```typescript
+   export interface PylonNewResource {
+     id: string;
+     name: string;
+   }
+   ```
+
+2. **Add client method** in `PylonClient` class:
+
+   ```typescript
+   async getNewResources(): Promise<PylonNewResource[]> {
+     const response = await this.client.get('/new-resources');
+     return response.data;
+   }
+   ```
+
+3. **Add MCP tool** in `tools` array:
+
+   ```typescript
+   {
+     name: 'pylon_get_new_resources',
+     description: 'Get new resources from Pylon',
+     inputSchema: {
+       type: 'object',
+       properties: {},
+     },
+   }
+   ```
+
+4. **Add handler** in switch statement:
+
+   ```typescript
+   case 'pylon_get_new_resources': {
+     const resources = await pylonClient.getNewResources();
+     return {
+       content: [{ type: 'text', text: JSON.stringify(resources, null, 2) }],
+     };
+   }
+   ```
+
+5. **Update smithery.yaml** tools list
+
+## Error Handling
+
+- All API calls are wrapped in try/catch
+- Axios errors are converted to MCP error responses
+- Required parameters are validated before API calls
+- Type assertions used for request arguments (`args as any`)
+
+## Security
+
+- API tokens stored in environment variables
+- Sensitive files excluded in `.gitignore`
+- No secrets committed to repository
+
+## Common Issues
+
+1. **TypeScript errors**: Use type assertions (`as any`) for MCP arguments
+2. **Missing parameters**: Validate required fields before API calls
+3. **Authentication**: Ensure `PYLON_API_TOKEN` is properly set
+4. **Build failures**: Check TypeScript configuration and imports
+
+## Future Enhancements
+
+- Add response type validation
+- Implement proper TypeScript types for all API responses
+- Add retry logic for failed API calls
+- Implement rate limiting
+- Add comprehensive error codes mapping

package/GCP_SETUP.md

@@ -0,0 +1,174 @@
+# GCP Artifact Registry Setup Guide
+
+This document explains how the Pylon MCP Server is published to and used from Google Cloud Platform's Artifact Registry.
+
+## What Was Set Up
+
+1. **GCP Artifact Registry Repository**
+   - Repository name: `npm-packages`
+   - Location: `us-central1`
+   - Format: npm
+   - Project: `customer-support-success`
+
+2. **Package Configuration**
+   - Package name: `@customer-support-success/pylon-mcp-server`
+   - Published to: `https://us-central1-npm.pkg.dev/customer-support-success/npm-packages/`
+   - Version: 1.0.0
+
+## For Users: Installing and Using the Package
+
+### Prerequisites
+
+You need to have `gcloud` CLI installed and authenticated:
+
+```bash
+# Install gcloud CLI (if not already installed)
+# Visit: https://cloud.google.com/sdk/docs/install
+
+# Authenticate
+gcloud auth application-default login
+```
+
+### Using with npx (Recommended)
+
+```bash
+# Run directly with npx
+npx --registry=https://us-central1-npm.pkg.dev/customer-support-success/npm-packages/ @customer-support-success/pylon-mcp-server
+```
+
+### Installing Globally
+
+```bash
+npm install -g --registry=https://us-central1-npm.pkg.dev/customer-support-success/npm-packages/ @customer-support-success/pylon-mcp-server
+```
+
+### Using with Augment Code
+
+Add this to your Augment Code MCP configuration:
+
+```json
+{
+  "pylon": {
+    "command": "npx",
+    "args": [
+      "--registry=https://us-central1-npm.pkg.dev/customer-support-success/npm-packages/",
+      "@customer-support-success/pylon-mcp-server"
+    ],
+    "env": {
+      "PYLON_API_TOKEN": "your_pylon_api_token_here"
+    }
+  }
+}
+```
+
+### Using with Claude Desktop
+
+Add this to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pylon": {
+      "command": "npx",
+      "args": [
+        "--registry=https://us-central1-npm.pkg.dev/customer-support-success/npm-packages/",
+        "@customer-support-success/pylon-mcp-server"
+      ],
+      "env": {
+        "PYLON_API_TOKEN": "your_pylon_api_token_here"
+      }
+    }
+  }
+}
+```
+
+## For Maintainers: Publishing Updates
+
+### Prerequisites
+
+1. GCP authentication with publish permissions
+2. Local repository cloned and up to date
+
+### Publishing a New Version
+
+1. **Update the version** in `package.json`:
+
+   ```bash
+   npm version patch  # or minor, or major
+   ```
+
+2. **Publish (CI is preferred)**:
+   - CI/CD: push a tag `vX.Y.Z` and let `release.yml` build/test/publish using `GCP_CREDENTIALS` (service account key) and a short-lived access token via `gcloud auth print-access-token`.
+   - Local/manual (maintainers only):
+
+     ```bash
+     npm run build
+     export ARTIFACT_REGISTRY_TOKEN=$(gcloud auth application-default print-access-token)
+     npm publish --registry=https://us-central1-npm.pkg.dev/customer-support-success/npm-packages/
+     ```
+
+### Verifying the Publication
+
+```bash
+# List packages in the registry
+gcloud artifacts packages list \
+  --repository=npm-packages \
+  --location=us-central1 \
+  --project=customer-support-success
+
+# View package details
+gcloud artifacts versions list \
+  --package=@customer-support-success/pylon-mcp-server \
+  --repository=npm-packages \
+  --location=us-central1 \
+  --project=customer-support-success
+```
+
+## Troubleshooting
+
+### Authentication Issues
+
+If you get authentication errors:
+
+```bash
+# Re-authenticate
+gcloud auth application-default login
+
+# Verify authentication
+gcloud auth application-default print-access-token
+```
+
+### Registry Not Found
+
+Make sure you're using the correct registry URL:
+
+```
+https://us-central1-npm.pkg.dev/customer-support-success/npm-packages/
+```
+
+### Permission Denied
+
+Ensure your GCP account has the `Artifact Registry Writer` role:
+
+```bash
+gcloud artifacts repositories add-iam-policy-binding npm-packages \
+  --location=us-central1 \
+  --member=user:your-email@example.com \
+  --role=roles/artifactregistry.writer
+```
+
+## Files Created/Modified
+
+- `.npmrc` - npm configuration for GCP Artifact Registry
+- `package.json` - Updated with scoped name and publishConfig
+- `.npmignore` - Controls which files are published
+- `publish.sh` - Helper script for publishing
+- `GCP_SETUP.md` - This documentation file
+
+## Benefits of Using GCP Artifact Registry
+
+1. **Private Package Hosting** - Keep your package private within your organization
+2. **Access Control** - Use GCP IAM for fine-grained permissions
+3. **Integration** - Works seamlessly with other GCP services
+4. **Reliability** - Enterprise-grade infrastructure
+5. **Cost-Effective** - Free tier available, pay only for storage and egress

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pylon MCP Server
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.