obsidian-mcp/.specify/memory/constitution.md

<!--
=============================================================================
SYNC IMPACT REPORT
=============================================================================
Version: 0.0.0 → 1.0.0
Change Type: MAJOR (Initial constitution establishment)

Modified Principles:
  - N/A (Initial version)

Added Sections:
  - I. MCP Protocol Compliance (MANDATORY)
  - II. Manifest Integrity (MANDATORY)
  - III. Local Execution Security
  - IV. Defensive Programming (NON-NEGOTIABLE)
  - V. Structured Tool Responses
  - VI. Stdio Transport Standard
  - Security & Privacy Requirements
  - Quality Assurance Standards
  
Removed Sections:
  - N/A (Initial version)

Templates Requiring Updates:
  ✅ .specify/templates/spec-template.md - Verified alignment with MCPB requirements
  ✅ .specify/templates/plan-template.md - Constitution Check gates validated
  ✅ .specify/templates/tasks-template.md - Task categorization aligned
  
Follow-up TODOs:
  - Monitor MCPB spec updates (currently at manifest version 0.3)
  - Update constitution when UV runtime moves from experimental to stable
  - Add specific security audit requirements as ecosystem matures

Rationale for Version 1.0.0:
  This is the initial constitution for the MCPB project. Starting at 1.0.0
  to indicate a production-ready governance framework that establishes
  non-negotiable development principles for MCP Bundle creation.
=============================================================================
-->

# MCPB (MCP Bundle) Constitution

## Core Principles

### I. MCP Protocol Compliance (MANDATORY)

All MCP servers MUST implement the Model Context Protocol specification correctly:

- Stdio transport is the REQUIRED communication method
- All protocol messages MUST follow MCP JSON-RPC format
- Server MUST respond to `initialize`, `tools/list`, and tool invocation requests
- Protocol version MUST be declared and adhered to
- Server MUST handle shutdown/cleanup gracefully

**Rationale**: MCP protocol compliance ensures interoperability across all client
applications (Claude Desktop, other AI tools). Non-compliant servers break the
ecosystem trust model and create poor user experiences.

### II. Manifest Integrity (MANDATORY)

Every bundle MUST include a valid `manifest.json` conforming to MCPB specification:

- `manifest_version` MUST match current spec (currently `0.3`)
- All REQUIRED fields MUST be present: `name`, `version`, `description`, `author`, `server`
- Semantic versioning (semver) MUST be used for bundle versions
- `server.mcp_config` MUST provide complete, correct execution configuration
- Variable substitution (`${__dirname}`, `${user_config.*}`) MUST be used for portability
- User configuration schemas MUST validate correctly and handle all edge cases

**Rationale**: Manifest integrity is the contract between bundle and host application.
Invalid manifests cause installation failures, runtime errors, and security
vulnerabilities. The manifest is the single source of truth for bundle capabilities.

### III. Local Execution Security

Bundles run with local system privileges and MUST implement security defensively:

- NEVER trust user input—validate and sanitize all parameters
- File system access MUST be explicitly scoped via `user_config` (directory/file pickers)
- Sensitive data (API keys, tokens) MUST use `sensitive: true` in user_config
- External API calls MUST have timeout limits (no infinite waits)
- Error messages MUST NOT leak sensitive paths, credentials, or system information
- Privacy policies MUST be declared if connecting to external services

**Rationale**: MCP bundles execute locally with user privileges. Security flaws
can expose personal data, credentials, or enable privilege escalation. Users trust
bundles to respect their privacy and system security.

### IV. Defensive Programming (NON-NEGOTIABLE)

Code MUST anticipate failure modes and handle them gracefully:

- Every external call (file I/O, network, subprocess) MUST have error handling
- Timeouts MUST be set for all network operations and long-running tasks
- Input validation MUST happen before any processing (fail-fast principle)
- Clear, actionable error messages MUST be returned (not stack traces to users)
- Resource cleanup MUST occur even on error paths (use try/finally patterns)
- Logging MUST capture enough context for debugging without exposing secrets

**Rationale**: MCP bundles run in diverse environments (different OS versions,
network conditions, file systems). Defensive code prevents crashes, data loss,
and poor user experiences. Clear errors enable users to self-resolve issues.

### V. Structured Tool Responses

All MCP tool calls MUST return well-structured, consistent responses:

- Response schema MUST be documented (consider `outputSchema` in manifest)
- JSON responses MUST be valid and follow declared schema
- Error responses MUST use consistent structure with error codes/messages
- Large outputs MUST be truncated/paginated appropriately
- Tool descriptions MUST accurately reflect behavior and parameters
- `inputSchema` MUST validate all parameters with clear constraints

**Rationale**: Structured responses enable AI models to reliably parse and act
on tool results. Inconsistent or malformed responses cause model confusion,
incorrect actions, and poor user experiences. Clear schemas are self-documenting.

### VI. Stdio Transport Standard

MCP communication MUST use stdio transport correctly:

- Server MUST read JSON-RPC messages from stdin line-by-line
- Server MUST write JSON-RPC responses to stdout (one per line)
- Debug/log messages MUST go to stderr (NEVER to stdout)
- Server MUST NOT use stdin/stdout for any non-MCP communication
- Server MUST handle stdin EOF gracefully (indicates shutdown)
- Buffering MUST be disabled or flushed immediately after each message

**Rationale**: Stdio transport is the MCP standard. Mixing logs with responses,
buffering issues, or improper EOF handling breaks protocol communication and
causes silent failures that are extremely difficult to debug.

## Security & Privacy Requirements

### Data Protection

- User data MUST remain local unless explicitly connecting to documented external services
- Credentials MUST use OS credential storage when possible (not plain text files)
- File access MUST be limited to user-configured directories (no global file system access)
- Temporary files MUST be cleaned up and MUST NOT contain sensitive data
- Network connections MUST use HTTPS/TLS for external services

### Transparency

- External service connections MUST be declared in `privacy_policies` field
- User configuration MUST clearly explain what data is accessed/transmitted
- Tool descriptions MUST be honest about actions performed
- Bundle permissions MUST be minimal (principle of least privilege)

## Quality Assurance Standards

### Testing Requirements

- All tools MUST have test cases validating correct responses
- Error handling MUST be tested (invalid inputs, network failures, missing files)
- Manifest MUST be validated with `mcpb pack` before release
- Bundle MUST be tested on all declared platforms in `compatibility.platforms`
- Integration testing with host application MUST be performed

### Documentation Standards

- README MUST explain what the bundle does and configuration requirements
- User-facing configuration options MUST have clear descriptions
- Setup instructions MUST be complete (prerequisites, installation, first use)
- Troubleshooting guide MUST address common error scenarios
- Examples MUST be provided for all tools

### Code Quality

- Prefer Node.js over Python (Node.js ships with Claude Desktop)
- Bundle all dependencies (no reliance on user-installed packages except runtimes)
- Use clear variable/function names (code readability matters for auditing)
- Comments MUST explain WHY, not WHAT (code should be self-documenting)
- Follow language-specific best practices and linting standards

## Governance

This constitution establishes non-negotiable standards for MCPB development. All
contributions, features, and changes MUST comply with these principles.

### Amendment Process

- Constitution changes require explicit documentation of rationale
- Version bumps follow semantic versioning:
  - **MAJOR**: Removing/redefining core principles (backward incompatible)
  - **MINOR**: Adding new principles or expanding guidance
  - **PATCH**: Clarifications, examples, wording improvements
- Amendments MUST update all dependent templates (spec, plan, tasks)
- Sync Impact Report MUST be included at top of constitution file

### Compliance Review

- All design documents MUST include Constitution Check section (see plan-template.md)
- Violations of principles MUST be justified with specific need and documented alternatives
- Code reviews MUST verify adherence to defensive programming and security principles
- Manifest changes MUST be validated against current MCPB specification
- Release checklist MUST verify testing on all supported platforms

### Living Document

- Monitor MCPB specification updates at https://github.com/anthropics/mcpb
- Update constitution when MCP protocol evolves
- Incorporate ecosystem best practices as they emerge
- Review and refine principles based on real-world bundle development experience

**Version**: 1.0.0 | **Ratified**: 2026-03-22 | **Last Amended**: 2026-03-22