mcp-server-lib.el NEWS -- history of user-visible changes

* Changes in mcp-server-lib 0.4.0 (unreleased)

** Breaking Changes

*** `initialize' serverInfo now reports the server's own name and version
    Previously the `initialize' result's `serverInfo' was hardcoded to
    the library's name and, incorrectly, to the MCP protocol version
    (e.g. "2025-03-26") as the server version.  Per the MCP spec
    `serverInfo' describes the server implementation, so its name and
    version are now supplied by the consuming server at registration and
    reported as-is, while `protocolVersion' continues to report the MCP
    protocol version.

*** `mcp-server-lib-name' is obsolete
    The server name is now supplied per server via `:name'.

** New Features

*** `mcp-server-lib-register-server' gained `:name' and `:version'
    Both optional.  `:name' sets `serverInfo.name' and defaults to the
    server `:id'.  `:version' sets `serverInfo.version' (the server's
    own version, distinct from the protocol version) and defaults to the
    new constant `mcp-server-lib-default-server-version' ("1.0.0").

*** `mcp-server-lib-server-registered-p' predicate
    New function: returns non-nil when a server record has been
    registered under a given server-id via
    `mcp-server-lib-register-server'.

*** `mcp-server-lib-installed-script-path' function
    New function: returns the path where `mcp-server-lib-install' places
    `emacs-mcp-stdio.sh' (under `mcp-server-lib-install-directory').

** Bug Fixes

*** `mcp-server-lib-show-metrics' tables now have column headers
    Each table in the metrics buffer is preceded by a header line
    naming its columns.

** ERT Test Helpers

*** `mcp-server-lib-ert-assert-initialize-result' gained `:name'/`:version'
    They assert `serverInfo.name'/`serverInfo.version'; they default to
    `mcp-server-lib-ert-server-id' and the new constant
    `mcp-server-lib-ert-default-version' respectively.

*** `mcp-server-lib-ert-with-server' gained `:name'/`:version'
    It now also registers a minimal server under
    `mcp-server-lib-ert-server-id' when none is registered, so the
    `initialize' handshake reports a serverInfo; an already-registered
    server is left untouched.

* Changes in mcp-server-lib 0.3.0 (2026-05-30)

** New Features

*** Bundled server registration via `mcp-server-lib-register-server'
    New single-entry function for registering an MCP server's tools,
    resources, and metadata in one call.  Accepts `:id',
    `:instructions', `:tools', and `:resources'; validates atomically
    (all-or-nothing) and ref-counts entries that overlap with prior
    calls.  See the function's docstring for the full contract.

*** Bulk unregistration via `mcp-server-lib-unregister-server'
    New function: tears down every tool, resource, resource template,
    and per-server metadata record registered under a server-id in a
    single call:

    (mcp-server-lib-unregister-server "my-server")

    Symmetric counterpart to `mcp-server-lib-register-server'.  See
    that function's docstring for ref-count semantics.

*** Per-server `instructions' field in initialize response
    `mcp-server-lib-register-server' accepts `:instructions', a string
    emitted in the MCP `initialize' result per the protocol spec.  See
    the function's docstring for details.

    For servers introducing instructions and using
    `mcp-server-lib-ert-with-server' (or
    `mcp-server-lib-ert-assert-initialize-result') for testing, pass
    `:instructions STR' to the helper so it asserts the field equals
    STR.  These helpers now assert by default that the `instructions'
    field is absent from the initialize result.

** Deprecations

*** Individual register / unregister functions
    The following functions are now obsolete in favor of the bundled
    `mcp-server-lib-register-server' /
    `mcp-server-lib-unregister-server' form:

    - `mcp-server-lib-register-tool'
    - `mcp-server-lib-register-resource'
    - `mcp-server-lib-unregister-tool'
    - `mcp-server-lib-unregister-resource'

    The migration is per-fixture, not per-call: there is no per-key
    replacement for `mcp-server-lib-unregister-tool' or
    `mcp-server-lib-unregister-resource'.  Pair each bundled
    `mcp-server-lib-register-server' with one
    `mcp-server-lib-unregister-server', which decrements the
    reference count of every tool, resource, and template under
    the matching server-id (regardless of which register API
    created them) plus the per-server metadata record.

    The deprecated functions continue to work; references to them
    produce byte-compile warnings pointing at the new bundled API.

** Bug Fixes

*** Strict validation of register-server inputs
    `mcp-server-lib-register-server' and the (now obsolete) individual
    register-tool / register-resource wrappers reject:
    - unknown property keys at any level (top-level register-server
      keys and tool/resource spec keys alike);
    - duplicate property keys at any level (e.g. `:description'
      repeated within one tool spec);
    - non-string values for string-typed fields (`:id', `:description',
      `:title', `:name', `:mime-type', resource URI, and `:server-id'
      on the obsolete `register-tool' / `register-resource' wrappers);
    - non-boolean values for `:read-only';
    - odd-length property lists (e.g. a trailing key with no value);
    - improper (dotted) lists where a proper list is required
      (top-level `:tools' and `:resources', plus tool and resource
      spec property lists).

    Allowed keys are `:id', `:instructions', `:tools', `:resources' at
    the top level; `:id', `:description', `:title', `:read-only' for
    tools; and `:name', `:description', `:mime-type' for resources.

    For the obsolete wrappers this is stricter than 0.2.0, which
    silently ignored unknown property keys.

*** Fixed `initialize' response emitting `null' for empty capabilities
    A server with no registered tools, resources, or templates used to
    emit `"capabilities":null' in the `initialize' response.  The MCP
    2025-03-26 schema requires `capabilities' to be a JSON object; the
    response now emits `"capabilities":{}' in the empty case (and the
    populated case is unchanged).  Spec-conformant clients that
    validate against the JSON Schema would previously reject the
    response.

*** Use portable shebang in emacs-mcp-stdio.sh
    Changed the shebang from ~#!/bin/bash~ to ~#!/usr/bin/env bash~ so the
    stdio shim runs on systems where bash is not installed at ~/bin/bash~
    (NixOS, Alpine, some BSDs, minimal containers). All platforms that
    previously worked continue to work since ~/usr/bin/env~ is a POSIX
    standard location.

*** Fixed non-ASCII tool parameters arriving as unibyte strings
    When tool parameters containing non-ASCII characters (e.g. UTF-8) were
    received via the stdio transport, base64 decoding produced unibyte strings.
    This caused string= comparisons against multibyte Emacs strings to fail.
    The library now decodes incoming JSON strings to multibyte before parsing,
    fixing non-ASCII parameter handling for all transports.

*** Fixed M-x mcp-server-lib-show-metrics not displaying its buffer
    `mcp-server-lib-show-metrics' built the *MCP metrics* report but did
    not pop it up; the command now displays the buffer.

** API Changes

*** ERT helper signature changes
    Downstream test code using the ERT helpers may need adjustment:

    - `mcp-server-lib-ert-assert-initialize-result' gained `&key
      :instructions'.  Existing three-positional-argument calls
      `(... result tools resources)' continue to work without change;
      the new keyword is optional.

    - `mcp-server-lib-ert-with-server' now rejects unknown keywords
      at the head of BODY at macro-expansion time.  Previously, the
      macro used `&allow-other-keys' and silently ignored typo
      keywords (e.g. `:tols' instead of `:tools'), which could mask
      misspelled assertions.  Tests that pass an unknown keyword will
      now error; fix the typo to migrate.

* Changes in mcp-server-lib 0.2.0 (2025-11-03)

** New Features
*** Multi-server support
    Multiple MCP servers can now run in the same Emacs daemon with complete
    isolation of tools and resources. Add the optional :server-id parameter to
    registration functions:

    (mcp-server-lib-register-tool handler
      :id "tool-name"
      :description "..."
      :server-id "my-server")

    The stdio script automatically derives server-id from the init function name
    (stripping the -mcp-enable suffix), or you can specify it explicitly with
    --server-id=name.

    Backward compatible: omitting :server-id uses the default server "default".

*** New command to inspect MCP server setup
    M-x mcp-server-lib-describe-setup shows all registered tools, resources,
    and resource templates along with their properties, handler functions, and
    usage statistics.

*** Multi-parameter tool support
    Tools can now accept multiple parameters. Parameters are validated -
    missing required parameters or unexpected parameters will return
    appropriate JSON-RPC errors.

*** Optional parameter support
    Tool schemas and invocation now correctly handle Elisp &optional parameters.
    Parameters declared with &optional are marked as optional in the JSON schema
    and can be omitted when calling the tool (passed as nil to the handler).
    Previously all parameters were incorrectly marked as required and validated
    as required at runtime, regardless of their optionality in the function
    signature.

*** Enhanced testing support for MCP servers
    The library now provides testing utilities through the mcp-server-lib-ert
    module for dependent packages.

*** Resource error handling with custom error codes
    Resource handlers can now signal specific JSON-RPC error codes using
    mcp-server-lib-resource-signal-error to provide meaningful error
    information to MCP clients.

** Bug Fixes
*** Fixed MCP Parameters parser for multi-line descriptions
    The parser now correctly handles multi-line parameter descriptions that
    contain hyphens (e.g., "org-id://"). Previously, hyphens in continuation
    lines were incorrectly treated as new parameter definitions. The parser
    now uses indentation to distinguish parameters (2-4 spaces) from
    continuation lines (6+ spaces).

*** Enforced tool handler return type validation
    Tool handlers must now return strings or nil. Previously, handlers could
    return any Elisp value which would be serialized, violating the MCP protocol.
    This is a breaking change for tools that returned non-string values.
    See https://github.com/laurynas-biveinis/mcp-server-lib.el/issues/4

*** Fixed resources/list endpoint to match MCP specification
    resources/list now correctly returns only direct resources,
    while templates are returned via the separate resources/templates/list
    endpoint as required by the protocol.

** API Changes
*** Made mcp-server-lib-name a public constant

*** Added public constants for JSON-RPC error codes
    - mcp-server-lib-jsonrpc-error-parse (-32700)
    - mcp-server-lib-jsonrpc-error-invalid-request (-32600)
    - mcp-server-lib-jsonrpc-error-method-not-found (-32601)
    - mcp-server-lib-jsonrpc-error-invalid-params (-32602)
    - mcp-server-lib-jsonrpc-error-internal (-32603)

*** Added ERT testing utilities
    - mcp-server-lib-ert-with-server
    - mcp-server-lib-ert-verify-resource-read
    - mcp-server-lib-ert-check-error-object
    - mcp-server-lib-ert-get-resource-list
    - mcp-server-lib-ert-get-success-result
    - mcp-server-lib-ert-verify-req-success
    - mcp-server-lib-ert-with-metrics-tracking
    - mcp-server-lib-ert-assert-initialize-result
    - mcp-server-lib-ert-get-initialize-result
    - mcp-server-lib-ert-server-id (dynamic variable for test server context)

*** Added resource error signaling API
    - mcp-server-lib-resource-signal-error for signaling custom error codes

* Changes in mcp-server-lib 0.1.0 (2025-07-22)

** Initial release
*** Core MCP server functionality
*** Tool registration and invocation
*** Resource registration (static and templates with {variable} syntax)
*** JSON-RPC communication
*** Stdio transport support via emacs-mcp-stdio.sh
*** Metrics collection and reporting
*** Basic testing utilities
