Documentation Standards Skill

Context

This skill applies when:

•Writing or updating README files
•Documenting APIs, functions, or MCP tools
•Creating architecture or design documentation
•Adding JSDoc comments to TypeScript code
•Creating diagrams for system architecture or flows
•Documenting security policies and compliance
•Writing user guides or integration tutorials
•Creating contribution guidelines

Rules

•Document Security Context: All security-related code must reference ISMS policies in documentation
•Use JSDoc for Public APIs: All exported functions, classes, and interfaces must have JSDoc comments
•Include Type Information: JSDoc comments must include @param and @returns with TypeScript types
•Provide Examples: All public APIs must include code examples showing correct usage
•Document Exceptions: Use @throws to document all possible exceptions and error conditions
•Use Mermaid for Diagrams: Create flowcharts, sequence diagrams, and architecture diagrams using Mermaid
•Keep READMEs Current: Update README.md when adding features, changing setup, or modifying architecture
•Write for Beginners: Assume readers are unfamiliar with the codebase - explain context and rationale
•Link to External Docs: Reference official documentation for MCP protocol, European Parliament APIs, and standards
•Document Decisions: Use Architecture Decision Records (ADRs) for significant technical decisions
•Security First: Document threat models, security controls, and compliance requirements
•Show Anti-Patterns: Include examples of incorrect usage to prevent common mistakes
•Maintain Changelog: Keep CHANGELOG.md updated following Keep a Changelog format
•Version Documentation: Clearly state which version of the code the documentation applies to
•Accessibility: Use semantic markdown, descriptive link text, and alt text for images

Examples

✅ Good Pattern: Comprehensive JSDoc for MCP Tool

typescript

/**
 * Searches European Parliament documents by keyword and filters.
 * 
 * This function implements the MCP protocol search tool with comprehensive
 * security controls as required by Hack23 ISMS Policy AC-001 (Access Control Policy).
 * 
 * Security Controls:
 * - Input validation and sanitization to prevent injection attacks
 * - Rate limiting to prevent abuse (100 requests per 15 minutes)
 * - Audit logging of all search queries
 * - Data classification enforcement per European Parliament guidelines
 * 
 * Compliance: ISO 27001:2022 A.5.15, NIST CSF PR.AC-1, CIS Control 6.3
 * 
 * @param query - Search parameters
 * @param query.keywords - Search keywords (max 200 chars, alphanumeric + spaces)
 * @param query.documentType - Filter by document type (e.g., "REPORT", "RESOLUTION")
 * @param query.dateFrom - Start date for document filtering (ISO 8601 format)
 * @param query.dateTo - End date for document filtering (ISO 8601 format)
 * @param query.limit - Maximum results to return (1-100, default: 20)
 * @param options - Optional search options
 * @param options.language - Preferred language code (e.g., "en", "fr", "de")
 * @param options.sortBy - Sort field ("date", "relevance", "title")
 * 
 * @returns Search results with document metadata
 * 
 * @throws {ValidationError} When query parameters are invalid
 * @throws {RateLimitError} When rate limit is exceeded
 * @throws {AuthorizationError} When access is denied
 * @throws {ExternalAPIError} When European Parliament API is unavailable
 * 
 * @example
 * ```typescript
 * // Basic search
 * const results = await searchDocuments({
 *   keywords: 'climate change',
 *   limit: 10
 * });
 * console.log(`Found ${results.total} documents`);
 * 
 * // Advanced search with filters
 * const filtered = await searchDocuments(
 *   {
 *     keywords: 'digital markets',
 *     documentType: 'REPORT',
 *     dateFrom: '2024-01-01',
 *     dateTo: '2024-12-31'
 *   },
 *   {
 *     language: 'en',
 *     sortBy: 'date'
 *   }
 * );
 * 
 * // Error handling
 * try {
 *   const results = await searchDocuments({ keywords: 'test' });
 * } catch (error) {
 *   if (error instanceof RateLimitError) {
 *     console.error('Rate limit exceeded, retry after:', error.retryAfter);
 *   }
 * }
 * ```
 * 
 * @see {@link https://github.com/Hack23/ISMS-PUBLIC/blob/main/policies/AC-001.md | Access Control Policy}
 * @see {@link https://data.europarl.europa.eu/api/docs | European Parliament API Documentation}
 * @since 1.0.0
 * @public
 */
export async function searchDocuments(
  query: SearchQuery,
  options?: SearchOptions
): Promise<SearchResult> {
  // Implementation
}

✅ Good Pattern: README with Security Context

markdown

# European Parliament MCP Server

> Model Context Protocol server providing access to European Parliament open data

[![CI/CD](https://github.com/Hack23/European-Parliament-MCP-Server/workflows/CI/badge.svg)](https://github.com/Hack23/European-Parliament-MCP-Server/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)
[![Coverage](https://img.shields.io/codecov/c/github/Hack23/European-Parliament-MCP-Server)](https://codecov.io/gh/Hack23/European-Parliament-MCP-Server)

## 🔒 Security & Compliance

This project implements security controls aligned with [Hack23 AB's ISMS](https://github.com/Hack23/ISMS-PUBLIC):

- **ISO 27001:2022** - Information security management
- **NIST CSF 2.0** - Cybersecurity framework
- **CIS Controls v8.1** - Security best practices
- **OWASP API Security Top 10** - API security

For detailed security information, see [SECURITY.md](SECURITY.md).

## 🚀 Quick Start

### Prerequisites

- Node.js 20.x or later
- npm 10.x or later
- MCP-compatible client (Claude Desktop, VS Code with MCP extension)

### Installation

\`\`\`bash
# Clone repository
git clone https://github.com/Hack23/European-Parliament-MCP-Server.git
cd European-Parliament-MCP-Server

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test
\`\`\`

### Configuration

Create a configuration file for your MCP client:

\`\`\`json
{
  "mcpServers": {
    "european-parliament": {
      "command": "node",
      "args": ["path/to/build/index.js"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}
\`\`\`

## 📦 Available Scripts

| Script | Description | ISMS Policy |
|--------|-------------|-------------|
| `npm run build` | Production build | SC-001 |
| `npm run dev` | Development mode with watch | - |
| `npm run lint` | Run ESLint | SC-002 |
| `npm test` | Run unit tests | SC-002 |
| `npm run test:integration` | Run integration tests | SC-002 |
| `npm run coverage` | Generate coverage report | SC-002 |
| `npm audit` | Check dependencies for vulnerabilities | SC-003 |

## 🏗️ Architecture

\`\`\`mermaid
graph TB
    A[MCP Client] -->|Request| B[MCP Server]
    B -->|Parse| C[Request Handler]
    C -->|Validate| D[Input Validator]
    D -->|Query| E[European Parliament API]
    E -->|Response| F[Data Transformer]
    F -->|Format| G[MCP Response]
    G -->|Return| A
    
    C -->|Log| H[Audit Logger]
    C -->|Check| I[Rate Limiter]
    
    style B fill:#4A90E2
    style D fill:#E8A631
    style H fill:#50C878
    style I fill:#E85D75
\`\`\`

## 🔧 MCP Tools

### search_documents
Search European Parliament documents by keywords and filters.

\`\`\`typescript
const result = await client.callTool('search_documents', {
  keywords: 'climate change',
  documentType: 'REPORT',
  limit: 10
});
\`\`\`

### get_document
Retrieve a specific document by ID.

\`\`\`typescript
const document = await client.callTool('get_document', {
  documentId: 'EP-1234567'
});
\`\`\`

See [API Documentation](docs/API.md) for complete tool reference.

## 🧪 Testing

We maintain 80%+ code coverage with three testing layers:

1. **Unit Tests** (Vitest) - Individual function testing
2. **Integration Tests** (Vitest) - API integration testing
3. **E2E Tests** - Full MCP protocol flow testing

\`\`\`bash
# Run all tests with coverage
npm run coverage

# Run specific test file
npm test -- search.test.ts

# Run tests in watch mode
npm test -- --watch
\`\`\`

## 📊 Code Quality

| Metric | Target | Current |
|--------|--------|---------|
| Code Coverage | ≥ 80% | 85% |
| TypeScript Strict | ✅ Enabled | ✅ |
| Security Headers | ✅ All | ✅ |
| API Response Time | < 500ms | 350ms |

## 🔐 Security

### Reporting Vulnerabilities

See [SECURITY.md](SECURITY.md) for vulnerability reporting process.

### Security Features

- ✅ Input validation and sanitization
- ✅ Rate limiting (100 requests per 15 minutes)
- ✅ Audit logging for all operations
- ✅ Dependency scanning (npm audit)
- ✅ License compliance checking

## 📝 License

MIT License - see [LICENSE.md](LICENSE.md) file for details.

## 🤝 Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.

## 📚 Documentation

- [API Reference](docs/API.md)
- [MCP Protocol Guide](docs/MCP_PROTOCOL.md)
- [Architecture Decision Records](docs/adr/)
- [Security Documentation](SECURITY.md)

✅ Good Pattern: Mermaid Diagram for MCP Flow

markdown

## MCP Request Flow

\`\`\`mermaid
sequenceDiagram
    participant C as MCP Client
    participant S as MCP Server
    participant V as Validator
    participant A as EP API
    participant L as Logger
    
    C->>S: search_documents request
    S->>V: Validate input
    
    alt Invalid Input
        V-->>S: ValidationError
        S-->>C: Error response
    else Valid Input
        V-->>S: Validated query
        S->>A: HTTP GET /documents
        A-->>S: JSON response
        S->>L: Log request
        S-->>C: MCP response
    end
    
    Note over L: ISMS Policy AC-001<br/>Audit logging
    Note over A: Rate limit: 100/15min
\`\`\`

✅ Good Pattern: Architecture Decision Record

markdown

# ADR-001: Use MCP Protocol for European Parliament Data Access

## Status
Accepted

## Context
We need to provide structured access to European Parliament open data for AI applications. Options considered:
1. REST API wrapper
2. GraphQL API
3. Model Context Protocol (MCP) server

## Decision
We will use MCP protocol to expose European Parliament data.

## Rationale

### Pros
- **AI-First Design**: MCP is designed specifically for AI assistants
- **Standardization**: Industry-standard protocol (Anthropic, et al.)
- **Type Safety**: Built-in schema validation and TypeScript support
- **Extensibility**: Easy to add new tools and capabilities
- **Security**: Built-in authentication and rate limiting support

### Cons
- **Newer Protocol**: Less established than REST/GraphQL
- **Limited Tooling**: Fewer debugging tools available
- **Client Support**: Requires MCP-compatible clients

## Security Implications
- MCP protocol provides structured security boundaries
- Input validation enforced by protocol schema
- ISMS Policy SC-001 (Secure Configuration) compliance maintained
- Rate limiting prevents abuse per ISMS Policy AC-002

## Consequences
- Developers must learn MCP protocol patterns
- Testing strategy includes MCP-specific integration tests
- Documentation must cover both MCP concepts and European Parliament APIs
- Client applications must support MCP protocol

## References
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [European Parliament Open Data](https://data.europarl.europa.eu/)
- [ISMS Policy SC-001](https://github.com/Hack23/ISMS-PUBLIC/blob/main/policies/SC-001.md)

## Date
2025-01-08

## Author
Development Team

❌ Bad Pattern: Missing Context

typescript

/**
 * Searches documents
 * @param query Search query
 * @returns Results
 */
function search(query: any): any {
  // No security context, no examples, poor types
}

❌ Bad Pattern: No Examples

typescript

/**
 * Complex European Parliament API query with multiple parameters
 * and edge cases, but no examples showing how to use it.
 */
export async function queryParliamentaryDocuments(
  keywords: string,
  documentTypes: string[],
  dateRange: DateRange,
  pagination: PaginationOptions,
  filters: DocumentFilters
): Promise<QueryResult> {
  // Complex implementation without usage examples
}

❌ Bad Pattern: Outdated README

markdown

# European Parliament MCP Server

Run `npm start` to start. <!-- Wrong command! -->

## Features
- Document search <!-- Actually implemented -->
- Member voting records <!-- Not implemented yet -->
- Real-time plenary sessions <!-- Removed 6 months ago -->

❌ Bad Pattern: No Security Documentation

typescript

// Bad: Security-critical code without ISMS reference
export function validateApiKey(key: string): boolean {
  // Implements API key validation, but no documentation about
  // which ISMS policy it implements or compliance mapping
  return checkKey(key);
}

References

Documentation Standards

•Google Developer Documentation Style Guide
•Write the Docs
•JSDoc
•TypeDoc

Diagram Tools

Markdown

Architecture

•Architecture Decision Records (ADR)
•C4 Model

MCP Protocol

•Model Context Protocol
•MCP Specification

Remember

•Security Context: Always reference ISMS policies in security-related documentation
•Code Examples: Every public API needs working code examples
•Keep Current: Documentation should be updated with code changes
•Mermaid Diagrams: Use Mermaid for visual documentation - it's version-controlled and maintainable
•JSDoc Everything: All exported functions, classes, and interfaces need JSDoc
•Write for Beginners: Assume readers are new to the codebase
•Link to Policies: Reference external ISMS policies and compliance frameworks
•Show Anti-Patterns: Document what NOT to do to prevent mistakes
•Accessibility: Use semantic markdown and descriptive text
•ADRs for Decisions: Document significant architectural decisions
•Changelog: Maintain CHANGELOG.md following Keep a Changelog format
•Version Docs: Clearly state which version documentation applies to
•Examples Over Words: Show don't tell - code examples are more valuable than prose
•Test Documentation: Verify code examples actually work
•MCP Protocol: Document MCP-specific patterns and tool schemas
•European Parliament Context: Reference official EP API documentation