verint.com/obsidian-mcp
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

feat: implement Obsidian MCP Bundle MVP (Phase 1-3)

Browse Source 
- Complete project setup with TypeScript, Jest, MCPB manifest
- Implement foundational infrastructure (CLI executor, logger, error handler)
- Add 9 file operation tools for User Story 1
- Full MCP protocol compliance with stdio transport
- Input validation and sanitization for security
- Comprehensive error handling with actionable messages
- Constitutional compliance: all 6 principles satisfied

MVP includes:
- obsidian_create_note, read, append, prepend, delete, move, rename, open, file_info
- Zod validation schemas for all parameters
- 30s timeout configuration with per-command overrides
- Stderr-only logging with sanitized output
- Graceful shutdown handling

Build: ✅ 0 errors, 0 vulnerabilities
Tasks: 48/167 complete (MVP milestone)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Peter Morton
2026-03-22 11:21:38 -05:00
parent e9e0112240
commit 622b28e42c
35 changed files with 5139 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

227
.specify/memory/constitution.md
View File

@@ -1,50 +1,207 @@
# [PROJECT_NAME] Constitution
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
<!--
=============================================================================
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
### [PRINCIPLE_1_NAME]
<!-- Example: I. Library-First -->
[PRINCIPLE_1_DESCRIPTION]
<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
### I. MCP Protocol Compliance (MANDATORY)
### [PRINCIPLE_2_NAME]
<!-- Example: II. CLI Interface -->
[PRINCIPLE_2_DESCRIPTION]
<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
All MCP servers MUST implement the Model Context Protocol specification correctly:
### [PRINCIPLE_3_NAME]
<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
[PRINCIPLE_3_DESCRIPTION]
<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
- 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
### [PRINCIPLE_4_NAME]
<!-- Example: IV. Integration Testing -->
[PRINCIPLE_4_DESCRIPTION]
<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
**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.
### [PRINCIPLE_5_NAME]
<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
[PRINCIPLE_5_DESCRIPTION]
<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
### II. Manifest Integrity (MANDATORY)
## [SECTION_2_NAME]
<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
Every bundle MUST include a valid `manifest.json` conforming to MCPB specification:
[SECTION_2_CONTENT]
<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
- `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
## [SECTION_3_NAME]
<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
**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.
[SECTION_3_CONTENT]
<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
### 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
<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
[GOVERNANCE_RULES]
<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
This constitution establishes non-negotiable standards for MCPB development. All
contributions, features, and changes MUST comply with these principles.
**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
### 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