mcp-code/project-structure.json

{
  "project_name": "MCP-Nostr",
  "description": "A bridge between the Model Context Protocol (MCP) and the Nostr network, enabling AI language models to publish content to Nostr and interact with the Nostr ecosystem.",
  "directory_structure": {
    "commands/": "Contains command-line interface (CLI) command definitions using 'commander'. Each file represents a command or a group of related commands (e.g., `find-snippets.ts`, `wot.ts`). These commands are entry points for user interaction.",
    "lib/": "Houses core libraries and reusable modules. Organized by functionality for better modularity and reduced code duplication. Subdirectories include:",
    "lib/cache/": "In-memory caching mechanisms for performance optimization. Currently used for 'snippets' and 'wallets' to avoid redundant network requests.",
    "lib/converters/": "Modules responsible for data conversion between different formats. Includes converters for 'snippets' and 'users', handling data transformation to and from Nostr events and internal data structures.",
    "lib/nostr/": "Nostr-specific logic and utilities. Contains modules for interacting with Nostr, such as 'snippets' management and utility functions for Nostr events and data.",
    "lib/types/": "TypeScript type definitions shared across the project, ensuring type safety and consistency.",
    "lib/utils/": "General utility functions, like logging, used throughout the application.",
    "logic/": "Implements the core business logic of the application. Each file typically represents a specific use case or feature, often corresponding to MCP commands or CLI actions (e.g., `create-pubkey.ts`, `publish-code-snippet.ts`). This layer orchestrates interactions between libraries and external services.",
    "migrations/": "Database migration scripts for schema management using Bun SQLite. Ensures database schema evolution is tracked and applied consistently.",
    "tests/": "Unit tests for specific functionalities. Currently includes tests for 'metadata-parser'.",
    "utils/": "Utility functions that are specific to the top-level application, potentially acting as wrappers or adapters around 'lib/utils'. Currently redirects to `lib/utils/log.ts`.",
    "root_level/": "Files at the project root define the application's entry point, configuration, database setup, and dependencies. Includes configuration files, package management, and the main application index."
  },
  "modules": {
    "cli_commands": "Responsible for defining and parsing command-line arguments using the 'commander' library. Acts as the user interface for interacting with the application via the terminal. Located in `commands/`.",
    "mcp_server": "Implements the Model Context Protocol server using `@modelcontextprotocol/sdk`. Enables the application to act as an MCP tool, receiving commands and sending responses in MCP format. Defined in `commands/mcp.ts` and logic functions in `logic/`.",
    "nostr_interaction": "Handles all interactions with the Nostr network using `@nostr-dev-kit/ndk`. Includes publishing events, fetching data, and managing subscriptions. Modules are located in `lib/nostr/` and are used throughout the application.",
    "data_conversion": "Provides modules to convert data between different formats, such as Nostr events to internal data structures and vice versa. Ensures data consistency across different layers of the application. Implemented in `lib/converters/`.",
    "data_caching": "Implements in-memory caching to improve performance by reducing redundant data fetching. Currently used for snippets and wallets. Found in `lib/cache/`.",
    "database_management": "Sets up and manages the SQLite database using Bun SQLite. Includes migration management for schema evolution and data persistence. Files are located in `db.ts` and `migrations/`.",
    "configuration_management": "Handles application configuration, including reading from and writing to a configuration file. Manages API keys, relay lists, and user settings. Implemented in `config.ts` and `wizard.ts` for setup.",
    "web_of_trust": "Implements Web of Trust functionality to manage social connections and reputation. Logic related to WoT is in `wot.ts` and data storage in the database.",
    "user_management": "Manages user profiles, identities, and authentication. Includes user creation, profile management, and key handling. Logic is spread across `config.ts`, `users.ts`, and command logic in `logic/`."
  },
  "key_components": {
    "cli": "The command-line interface, built using 'commander', provides users with direct access to application functionalities via terminal commands. Commands are defined in `commands/` and delegate logic to other modules.",
    "mcp_server_integration": "The application integrates as an MCP server, allowing AI agents and other MCP-compatible tools to interact with it. This integration is primarily managed in `commands/mcp.ts` and logic functions in `logic/`.",
    "nostr_ndk_integration": "NDK (@nostr-dev-kit/ndk) is the core library for interacting with the Nostr network. It handles event signing, publishing, subscription, and data retrieval. Integration is throughout the codebase, especially in `lib/nostr/` and `logic/`.",
    "sqlite_database": "Bun SQLite is used for local data persistence, storing user profiles, Web of Trust data, and potentially other application-specific data. Database setup and migrations are handled in `db.ts` and `migrations/`.",
    "configuration_file": "`~/.mcp-nostr.json` stores application configuration, including user credentials, relay lists, and enabled MCP commands. Configuration is managed by `config.ts` and set up via `wizard.ts`.",
    "wizard_setup": "The `wizard.ts` module provides an interactive command-line wizard for first-time setup, guiding users through configuration and authentication setup."
  },
  "modularity_and_separation_of_concerns": "The codebase is designed with a strong emphasis on modularity and separation of concerns. This is achieved through:",
  "modularity_principles": [
    "Directory-based Module Organization: Functionality is grouped into directories based on domain (e.g., 'commands', 'lib', 'logic', 'migrations').",
    "Library Modules ('lib/'): Reusable components are placed in 'lib/' to promote code reuse and reduce duplication. Subdirectories within 'lib/' further categorize functionality (e.g., 'cache', 'converters', 'nostr', 'utils').",
    "Logic Layer ('logic/'): Business logic is separated from command handling and data access, making the code more maintainable and testable.",
    "Command Layer ('commands/'): CLI command definitions are isolated, focusing on parsing user input and delegating actions to the logic layer.",
    "Data Conversion Modules ('lib/converters/'): Data transformation logic is encapsulated in converter modules, separating data representation concerns.",
    "Configuration Modules ('config.ts', 'wizard.ts'): Configuration management is handled by dedicated modules, isolating configuration loading, saving, and setup processes."
  ],
  "technology_stack": [
    "Bun.js": "JavaScript runtime environment",
    "TypeScript": "Programming language",
    "Model Context Protocol (MCP)": "Protocol for AI tool interaction",
    "Nostr": "Decentralized social network protocol",
    "@nostr-dev-kit/ndk": "Nostr Development Kit for JavaScript",
    "@nostr-dev-kit/ndk-wallet": "NDK Wallet library for NIP-60 integration",
    "@modelcontextprotocol/sdk": "MCP SDK for JavaScript",
    "commander": "Node.js library for command-line interfaces",
    "inquirer": "Node.js library for interactive command-line prompts",
    "Bun SQLite": "SQLite database binding for Bun.js"
  ]
}