Skip to content

Protokoll CLI — 0.1.2

Choose a tag to compare

View all tags
@tobrien tobrien released this 15 Feb 21:41
· 0 commits to master since this release
v0.1.2
237df60
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Summary

This release (0.1.2) focuses on configuration management and MCP client plumbing, plus a large expansion of unit test coverage. The primary user-visible improvements are a formalized configuration interface and a stable client factory for creating a configured MCP client. There are also API signature changes you should be aware of if other code imports configuration or client-creation helpers from this package.

What's the main story

  • Introduce a clear configuration contract and loader (ProtokolConfig + loadConfig).
  • Introduce a small client-factory layer that caches loaded configuration and exposes utilities to set the config path and create a configured MCP client.
  • Harden the MCP client implementation (spawn/environment handling, connection lifecycle).
  • Add a substantial number of tests around commands, configuration, and client factory to improve reliability and guard behavior going forward.

Key changes (developer-facing)

  1. Configuration API

    • New ProtokolConfig interface (src/config.ts) defines the shape of configuration used by the CLI and client:
      • fields include mcpServerCommand, mcpServerArgs, inputDirectory, outputDirectory, contextDirectories, model/transcription/classify/compose model names, openaiApiKey, debug, verbose, etc.
    • loadConfig(overrides?: Partial, configPath?: string): Promise
      • Loads configuration either from a specified file path (YAML) or by using CardiganTime to search up the directory tree.
      • Merges defaults and overrides.
    • getConfigFileName(): returns the default config filename (protokoll-config.yaml).

  2. Client factory (src/client-factory.ts)

    • Exposes:
      • setConfigPath(path: string | undefined): set/clear a specific config file path and clear cached config.
      • getConfig(): returns cached config (loads via loadConfig if needed).
      • createConfiguredMCPClient(overrides?: Partial): creates an MCP client with values from the loaded configuration merged with any overrides.
    • Caches loaded configuration in-module, clears cache when setConfigPath is called.

  3. MCP client improvements (src/mcp-client.ts)

    • ProtokolMCPClient class:
      • Better handling of environment variables passed to spawned MCP server (copies process.env and adds WORKSPACE_ROOT / PROTOKOLL_CONFIG_DIR when provided).
      • Uses StdioClientTransport to spawn server with given command/args and env; manages lifecycle and cleanup robustly.
      • Client methods to call tools, list tools/resources/prompts and read resources; throws when not connected.
      • createMCPClient helper which constructs and connects a client instance.
    • Default server command/args defaults set in MCP client and configuration mapping.

  4. Tests

    • Large expansion of tests across the codebase (many new/expanded tests in tests/, including client-factory tests).
    • Tests assert caching behavior, path propagation, and that createConfiguredMCPClient merges overrides with config.

Problems solved

  • Provides a consistent, structured way to load and access configuration for the CLI and MCP client.
  • Simplifies creating an MCP client that is pre-configured from project configuration (reduces duplication).
  • Makes spawning the MCP server more robust by ensuring environment is passed correctly and resources are cleaned up.
  • Large test coverage reduces the risk of regressions for configuration and MCP client behavior.

Impact on users and developers

  • For users running the CLI, behavior should be unchanged except that configuration is now reliably discovered via CardiganTime and a specific config file path can be forced via setConfigPath (used internally by code or tests).
  • For developers who import the package programmatically:
    • New exports to consume: getConfig, setConfigPath, createConfiguredMCPClient, loadConfig, getConfigFileName.
    • You can now easily obtain a configured MCP client that uses your project config and workspace root.

Breaking changes and important considerations

  • Function and type/signature changes:

    • The configuration API has been formalized. loadConfig now expects/returns a ProtokolConfig and accepts an optional configPath parameter.
    • The package now exports setConfigPath(path: string | undefined), getConfig(), and createConfiguredMCPClient(overrides?: Partial). If your code previously relied on any older internal configuration API, you will need to update to these new names and signatures.
    • Review callers that previously loaded configuration directly — they should move to using getConfig() or loadConfig() with the new signature.

  • Module-level config caching:

    • getConfig caches the loaded configuration in-module. Call setConfigPath(...) to change the path and clear the cache, or otherwise ensure your callers call loadConfig explicitly when they require fresh reads.

  • Versioning note:

    • This release is 0.1.2. (Use exactly this version when referencing or publishing this release.)

Practical migration notes / examples

  • Creating a configured client:
    • Before: you may have created MCP client manually and passed command/args from your own lookup.
    • Now:
      • import { createConfiguredMCPClient } from 'protokoll-cli';
      • const client = await createConfiguredMCPClient({ serverCommand: 'my-override' });
  • Reading configuration:
    • import { getConfig, setConfigPath } from 'protokoll-cli';
    • setConfigPath('/path/to/protokoll-config.yaml'); // optional, clears cache
    • const cfg = await getConfig();

Miscellaneous

  • The release contains a large increase in unit test coverage which should make subsequent refactors safer.
  • No other breaking changes (such as removed command-line flags or removed public modules) were detected in this set of commits beyond the configuration/client API signature changes described above.

If you maintain downstream integrations, scan for any direct imports of previous configuration helpers and update them to use loadConfig/getConfig and the client-factory functions included in this release.

Assets 2
Loading