Contributing

## Bug Report Template

**Description**
A clear description of what the bug is.

**Steps to Reproduce**

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

**Expected Behavior**
What you expected to happen.

**Actual Behavior**
What actually happened.

**Environment**

- OS: [e.g. macOS 12.0]
- Node.js: [e.g. 18.17.0]
- Pcnaid MCP Hub Version: [e.g. 1.2.3]
- Browser: [e.g. Chrome 91.0]

**Additional Context**
Any other context about the problem.

# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/mcphub.git
cd mcphub

# 2. Add upstream remote
git remote add upstream https://github.com/PcnaidInc/Pcnaid-MCP-Hub.git

# 3. Install dependencies
pnpm install

# 4. Set up environment
cp .env.example .env.development

# 5. Start development environment
docker-compose -f docker-compose.dev.yml up -d
pnpm run migrate
pnpm run seed

# 6. Start development server
pnpm run dev

# Features
git checkout -b feature/smart-routing-improvements
git checkout -b feature/user-authentication

# Bug fixes
git checkout -b fix/server-startup-error
git checkout -b fix/memory-leak-in-cache

# Documentation
git checkout -b docs/api-reference-update
git checkout -b docs/deployment-guide

# Refactoring
git checkout -b refactor/auth-service-cleanup
git checkout -b refactor/database-queries

# Check code style
pnpm run lint

# Fix automatically fixable issues
pnpm run lint:fix

# Format code
pnpm run format

# Type check
pnpm run type-check

// ✅ Good: Use proper types
interface MCPServerConfig {
  name: string;
  command: string;
  args: string[];
  env?: Record<string, string>;
}

// ✅ Good: Use async/await
async function startServer(config: MCPServerConfig): Promise<void> {
  try {
    await mcpService.start(config);
  } catch (error) {
    logger.error('Failed to start server', { error, config });
    throw error;
  }
}

// ❌ Bad: Using any type
function processData(data: any): any {
  return data.something();
}

// ❌ Bad: Not handling errors
async function riskyOperation(): Promise<void> {
  await dangerousFunction(); // Could throw
}

// ✅ Good: Functional components with proper typing
interface ServerCardProps {
  server: MCPServer;
  onStart: (serverId: string) => void;
  onStop: (serverId: string) => void;
}

const ServerCard: React.FC<ServerCardProps> = ({ server, onStart, onStop }) => {
  const handleStart = useCallback(() => {
    onStart(server.id);
  }, [server.id, onStart]);

  return (
    <Card data-testid={`server-card-${server.id}`}>
      <CardHeader>
        <CardTitle>{server.name}</CardTitle>
        <Badge variant={server.status === 'running' ? 'success' : 'secondary'}>
          {server.status}
        </Badge>
      </CardHeader>
      <CardContent>
        <p>{server.description}</p>
      </CardContent>
      <CardActions>
        {server.status === 'stopped' ? (
          <Button onClick={handleStart}>Start</Button>
        ) : (
          <Button onClick={() => onStop(server.id)}>Stop</Button>
        )}
      </CardActions>
    </Card>
  );
};

// src/services/__tests__/mcpService.test.ts
import { MCPService } from '../mcpService';
import { mockLogger, mockDatabase } from '../../__mocks__';

describe('MCPService', () => {
  let service: MCPService;

  beforeEach(() => {
    service = new MCPService(mockLogger, mockDatabase);
  });

  describe('startServer', () => {
    it('should start a server successfully', async () => {
      const config = {
        name: 'test-server',
        command: 'node',
        args: ['server.js'],
      };

      await service.startServer(config);

      expect(service.getServerStatus('test-server')).toBe('running');
    });

    it('should handle server startup failures', async () => {
      const invalidConfig = {
        name: 'invalid-server',
        command: 'invalid-command',
        args: [],
      };

      await expect(service.startServer(invalidConfig)).rejects.toThrow(
        'Failed to start server: Command not found',
      );
    });
  });
});

// src/__tests__/integration/server-api.test.ts
import request from 'supertest';
import { app } from '../../app';
import { setupTestDatabase, teardownTestDatabase } from '../helpers/database';

describe('Server API Integration', () => {
  beforeAll(async () => {
    await setupTestDatabase();
  });

  afterAll(async () => {
    await teardownTestDatabase();
  });

  describe('POST /api/servers', () => {
    it('should create a new server', async () => {
      const serverData = {
        name: 'test-server',
        command: 'node',
        args: ['server.js'],
        group: 'development',
      };

      const response = await request(app).post('/api/servers').send(serverData).expect(201);

      expect(response.body).toMatchObject({
        name: 'test-server',
        status: 'stopped',
        group: 'development',
      });
    });
  });
});

// tests/e2e/server-management.spec.ts
import { test, expect } from '@playwright/test';

test.describe('Server Management', () => {
  test('should create and manage MCP servers', async ({ page }) => {
    await page.goto('/dashboard');

    // Create new server
    await page.click('[data-testid="add-server-button"]');
    await page.fill('[data-testid="server-name-input"]', 'test-server');
    await page.fill('[data-testid="server-command-input"]', 'node server.js');
    await page.click('[data-testid="save-server-button"]');

    // Verify server appears in list
    await expect(page.locator('[data-testid="server-list"]')).toContainText('test-server');

    // Start the server
    await page.click('[data-testid="start-server-test-server"]');

    // Verify server is running
    await expect(page.locator('[data-testid="server-status-test-server"]')).toContainText(
      'running',
    );
  });
});

# Format: <type>[optional scope]: <description>

# Features
git commit -m "feat(auth): add JWT token refresh functionality"
git commit -m "feat(ui): implement server status dashboard"

# Bug fixes
git commit -m "fix(api): resolve memory leak in server manager"
git commit -m "fix(db): handle connection timeout gracefully"

# Documentation
git commit -m "docs(api): add examples for server endpoints"
git commit -m "docs(readme): update installation instructions"

# Refactoring
git commit -m "refactor(services): extract auth logic into separate module"

# Tests
git commit -m "test(api): add integration tests for server management"

# Chores
git commit -m "chore(deps): update dependencies to latest versions"

# 1. Sync with upstream
git fetch upstream
git checkout main
git merge upstream/main

# 2. Rebase your feature branch
git checkout feature/your-feature
git rebase main

# 3. Run all checks
pnpm run lint
pnpm run type-check
pnpm run test
pnpm run build

# 4. Update documentation if needed
# 5. Add/update tests for your changes

## Description

Brief description of the changes and motivation.

## Type of Change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing

- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] E2E tests pass (if applicable)
- [ ] Manual testing completed

## Documentation

- [ ] Code is self-documenting
- [ ] API documentation updated
- [ ] User documentation updated
- [ ] README updated (if needed)

## Checklist

- [ ] My code follows the project's style guidelines
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes

## Screenshots (if applicable)

Add screenshots to help explain your changes.

## Additional Notes

Any additional information that reviewers should know.

# Clear and reinstall dependencies
rm -rf node_modules pnpm-lock.yaml
pnpm install

# Clear build cache
rm -rf dist/
pnpm run build

# Run tests with verbose output
pnpm run test -- --verbose

# Run specific test file
pnpm test src/services/mcpService.test.ts

# Debug tests
pnpm run test:debug

# Reset database
pnpm run db:reset

# Run migrations
pnpm run migrate

# Seed development data
pnpm run seed

# 1. Create release branch
git checkout -b release/v1.2.0

# 2. Update version
npm version 1.2.0 --no-git-tag-version

# 3. Update changelog
# Edit CHANGELOG.md

# 4. Commit changes
git add .
git commit -m "chore(release): prepare v1.2.0"

# 5. Create PR for review
# 6. After merge, tag release
git tag v1.2.0
git push origin v1.2.0