mcp-server/protocol.c

Go to the documentation of this file.

#include "mcp.h"
#include <ascii-chat/stats/runtime.h>
#include <ascii-chat/util/time.h>
#include <ascii-chat/version.h>
#include <ascii-chat/audio/audio.h>
#include <ascii-chat/video/webcam/webcam.h>
#include <string.h>
 
static yyjson_mut_doc *envelope(yyjson_val *id) {
  yyjson_mut_doc *d = yyjson_mut_doc_new(NULL);
  yyjson_mut_val *root = yyjson_mut_obj(d);
  yyjson_mut_doc_set_root(d, root);
  yyjson_mut_obj_add_str(d, root, "jsonrpc", "2.0");
  yyjson_mut_obj_add_val(d, root, "id", id ? yyjson_val_mut_copy(d, id) : yyjson_mut_null(d));
  return d;
}
yyjson_mut_doc *mcp_error(yyjson_val *id, int code, const char *message) {
  ASCII_OTEL_SCOPE(MCP_PROTOCOL_ERROR);
  ASCII_OTEL_ATTR_INT("rpc.jsonrpc.error_code", code);
  stats_counter_add(stats_runtime_scope(), STATS_COUNTER_MCP_REJECTED, 1);
  ascii_otel_error("MCP protocol request rejected");
  yyjson_mut_doc *d = envelope(id);
  yyjson_mut_val *e = yyjson_mut_obj(d);
  yyjson_mut_obj_add_int(d, e, "code", code);
  yyjson_mut_obj_add_strcpy(d, e, "message", message);
  yyjson_mut_obj_add_val(d, yyjson_mut_doc_get_root(d), "error", e);
  return d;
}
static yyjson_mut_doc *tool_result(yyjson_val *id, const http_renderer_process_result_t *r) {
  yyjson_mut_doc *d = envelope(id);
  yyjson_mut_val *root = yyjson_mut_doc_get_root(d), *result = yyjson_mut_obj(d), *content = yyjson_mut_arr(d),
                 *item = yyjson_mut_obj(d);
  yyjson_mut_obj_add_str(d, item, "type", "text");
  const char *text = r->error[0] ? r->error : r->text && r->text[0] ? r->text : r->output_path;
  yyjson_mut_obj_add_strcpy(d, item, "text", text ? text : "");
  yyjson_mut_arr_add_val(content, item);
  yyjson_mut_obj_add_val(d, result, "content", content);
  yyjson_mut_obj_add_bool(d, result, "isError", r->error[0] != 0);
  if (!r->error[0]) {
    yyjson_mut_val *data = yyjson_mut_obj(d), *files = yyjson_mut_arr(d), *frames = yyjson_mut_arr(d);
    yyjson_mut_obj_add_strcpy(d, data, "ascii", r->text ? r->text : "");
    yyjson_mut_obj_add_uint(d, data, "elapsed_ms", r->elapsed_ms);
    for (size_t i = 0; i < r->frame_count; ++i) {
      const http_render_frame_t *source = &r->frames[i];
      yyjson_mut_val *frame = yyjson_mut_obj(d);
      if (source->text) {
        yyjson_mut_obj_add_str(d, frame, "type", "text");
        yyjson_mut_obj_add_strcpy(d, frame, "text", source->text);
      } else {
        yyjson_mut_obj_add_str(d, frame, "type", "file");
        yyjson_mut_obj_add_strcpy(d, frame, "path", source->path);
      }
      yyjson_mut_obj_add_uint(d, frame, "timestamp_ms", source->timestamp_ms);
      yyjson_mut_arr_add_val(frames, frame);
    }
    if (r->output_path[0]) {
      yyjson_mut_arr_add_strcpy(d, files, r->output_path);
      yyjson_mut_val *frame = yyjson_mut_obj(d);
      yyjson_mut_obj_add_str(d, frame, "type", "file");
      yyjson_mut_obj_add_strcpy(d, frame, "path", r->output_path);
      yyjson_mut_arr_add_val(frames, frame);
    }
    yyjson_mut_obj_add_val(d, data, "saved_files", files);
    yyjson_mut_obj_add_val(d, data, "frames", frames);
    yyjson_mut_obj_add_val(d, result, "structuredContent", data);
  }
  yyjson_mut_obj_add_val(d, root, "result", result);
  return d;
}
 
// Enumerate through the same platform APIs as the CLI, without opening capture streams.
static yyjson_mut_doc *device_list_result(yyjson_val *id, yyjson_val *arguments) {
  if (arguments && (!yyjson_is_obj(arguments) || yyjson_obj_size(arguments)))
    return mcp_error(id, -32602, "device_list accepts no arguments");
  yyjson_mut_doc *d = envelope(id);
  yyjson_mut_val *result = yyjson_mut_obj(d), *data = yyjson_mut_obj(d), *video = yyjson_mut_arr(d),
                 *audio = yyjson_mut_arr(d), *errors = yyjson_mut_arr(d);
  webcam_device_info_t *cameras = NULL;
  audio_device_info_t *microphones = NULL;
  unsigned camera_count = 0, microphone_count = 0;
  int default_video = -1, default_audio = -1;
  asciichat_error_t err = webcam_list_devices(&cameras, &camera_count);
  if (err != ASCIICHAT_OK) {
    asciichat_error_context_t context;
    yyjson_mut_arr_add_strcpy(d, errors, HAS_ERRNO(&context) ? context.context_message : "Cannot enumerate webcams");
  } else {
    for (unsigned i = 0; i < camera_count; ++i) {
      yyjson_mut_val *device = yyjson_mut_obj(d);
      bool is_default = cameras[i].index == 0;
      if (is_default)
        default_video = (int)cameras[i].index;
      yyjson_mut_obj_add_uint(d, device, "index", cameras[i].index);
      yyjson_mut_obj_add_strcpy(d, device, "name", cameras[i].name);
      yyjson_mut_obj_add_bool(d, device, "is_default", is_default);
      yyjson_mut_arr_add_val(video, device);
    }
  }
  webcam_free_device_list(cameras);
  err = audio_list_input_devices(&microphones, &microphone_count);
  if (err != ASCIICHAT_OK) {
    asciichat_error_context_t context;
    yyjson_mut_arr_add_strcpy(d, errors,
                              HAS_ERRNO(&context) ? context.context_message : "Cannot enumerate microphones");
  } else {
    for (unsigned i = 0; i < microphone_count; ++i) {
      yyjson_mut_val *device = yyjson_mut_obj(d);
      if (microphones[i].is_default_input)
        default_audio = microphones[i].index;
      yyjson_mut_obj_add_int(d, device, "index", microphones[i].index);
      yyjson_mut_obj_add_strcpy(d, device, "name", microphones[i].name);
      yyjson_mut_obj_add_bool(d, device, "is_default", microphones[i].is_default_input);
      yyjson_mut_arr_add_val(audio, device);
    }
  }
  audio_free_device_list(microphones);
  yyjson_mut_obj_add_val(d, data, "video_devices", video);
  yyjson_mut_obj_add_val(d, data, "audio_devices", audio);
  yyjson_mut_obj_add_val(d, data, "default_video_device",
                         default_video < 0 ? yyjson_mut_null(d) : yyjson_mut_int(d, default_video));
  yyjson_mut_obj_add_val(d, data, "default_audio_device",
                         default_audio < 0 ? yyjson_mut_null(d) : yyjson_mut_int(d, default_audio));
  yyjson_mut_obj_add_val(d, data, "errors", errors);
  yyjson_mut_val *content = yyjson_mut_arr(d), *item = yyjson_mut_obj(d);
  char *text = yyjson_mut_val_write(data, 0, NULL);
  yyjson_mut_obj_add_str(d, item, "type", "text");
  yyjson_mut_obj_add_strcpy(d, item, "text", text ? text : "Cannot serialize device list");
  free(text);
  yyjson_mut_arr_add_val(content, item);
  yyjson_mut_obj_add_val(d, result, "content", content);
  yyjson_mut_obj_add_bool(d, result, "isError", yyjson_mut_arr_size(errors) != 0);
  yyjson_mut_obj_add_val(d, result, "structuredContent", data);
  yyjson_mut_obj_add_val(d, yyjson_mut_doc_get_root(d), "result", result);
  return d;
}
static void run_job(void *arg, atomic_t *cancelled) {
  mcp_job_t *job = arg;
  ASCII_OTEL_SCOPE_PARENT(MCP_RENDER, &job->telemetry_parent);
  static const char *const tools[] = {"render_file", "render_url", "render_webcam", "render_visualization"};
  ASCII_OTEL_ATTR_STRING("mcp.tool", tools[job->tool]);
  ASCII_OTEL_ATTR_STRING("mcp.transport", job->server->policy.hosted ? "http" : "stdio");
  stats_counter_add(stats_runtime_scope(), STATS_COUNTER_MCP_RENDERS, 1);
  http_renderer_process_result_t result;
  uint64_t render_started = time_get_ns();
  log_info("MCP render started");
  if (job->request.output_type == HTTP_RENDER_OUTPUT_TEXT &&
      (job->request.source_path[0] || job->request.source_url[0])) {
    http_render_request_t shared_request;
    http_render_request_init(&shared_request);
    shared_request.source.type = job->request.source_url[0] ? HTTP_RENDER_SOURCE_URL : HTTP_RENDER_SOURCE_FILE;
    if (job->request.source_url[0])
      SAFE_STRNCPY(shared_request.source.url, job->request.source_url, sizeof(shared_request.source.url));
    else
      SAFE_STRNCPY(shared_request.source.path, job->request.source_path, sizeof(shared_request.source.path));
    shared_request.options = job->request.options;
    http_render_result_t shared_result = {0};
    const char *shared_source = job->request.source_url[0] ? job->request.source_url : job->request.source_path;
    asciichat_error_t shared_error =
        http_renderer_render_file(shared_source, &shared_request, &shared_result, cancelled);
    memset(&result, 0, sizeof(result));
    result.elapsed_ms = shared_result.elapsed_ms;
    if (shared_error == ASCIICHAT_OK) {
      result.text = shared_result.ascii;
      result.length = shared_result.ascii_length;
      shared_result.ascii = NULL;
    } else {
      SAFE_STRNCPY(result.error, asciichat_error_string(shared_error), sizeof(result.error));
    }
    http_render_result_destroy(&shared_result);
  } else {
    http_renderer_process(&job->request, cancelled, &result);
  }
  stats_duration_record(stats_runtime_scope(), STATS_DURATION_MCP_RENDER, time_get_ns() - render_started);
  stats_counter_add(stats_runtime_scope(), STATS_COUNTER_MCP_OUTPUT_BYTES, result.length);
  ASCII_OTEL_ATTR_INT("mcp.output.bytes", (int64_t)result.length);
  if (result.error[0]) {
    stats_counter_add(stats_runtime_scope(), STATS_COUNTER_MCP_RENDER_FAILURES, 1);
    const char *failure = result.timed_out ? "timeout" : atomic_load_bool(cancelled) ? "cancelled" : "render";
    ASCII_OTEL_ATTR_STRING("error.type", failure);
    if (result.timed_out)
      stats_counter_add(stats_runtime_scope(), STATS_COUNTER_MCP_TIMEOUTS, 1);
    else if (atomic_load_bool(cancelled))
      stats_counter_add(stats_runtime_scope(), STATS_COUNTER_MCP_CANCELLED, 1);
    SET_ERRNO(ERROR_FILE_OPERATION, "MCP render failed: %s", result.error);
    log_error("MCP render failed: %s", result.error);
  } else
    log_info("MCP render completed in %llu ms", (unsigned long long)result.elapsed_ms);
  if (!result.error[0] && result.output_path[0])
    stats_counter_add(stats_runtime_scope(), STATS_COUNTER_MCP_SAVED_FILES, 1);
  job->response = tool_result(mcp_get(yyjson_doc_get_root(job->message), "id"), &result);
  http_renderer_process_result_destroy(&result);
  mcp_request_destroy(&job->request);
  if (!job->server->policy.hosted) {
    mcp_stdio_send(job->server, job->response);
    yyjson_mut_doc_free(job->response);
    job->response = NULL;
  }
  if (job->server->policy.hosted) {
    // The HTTP wakeup runs on the server loop and must observe completion.
    atomic_store_bool(&job->renderer_job.done, true);
    mcp_http_wake(job->server);
  }
}
void mcp_jobs_reap(mcp_server_t *s, bool all) {
  for (unsigned i = 0; i < s->policy.max_jobs; ++i) {
    mcp_job_t *j = &s->jobs[i];
    if (!j->renderer_job.started ||
        (!all && (!http_renderer_job_is_done(&j->renderer_job) || (s->policy.hosted && j->connection))))
      continue;
    http_renderer_job_join(&j->renderer_job);
    yyjson_doc_free(j->message);
    if (j->response)
      yyjson_mut_doc_free(j->response);
    memset(j, 0, sizeof(*j));
  }
}
static bool same_id(yyjson_val *a, yyjson_val *b) {
  return a && b &&
         ((yyjson_is_str(a) && yyjson_is_str(b) && yyjson_get_len(a) == yyjson_get_len(b) &&
           !strcmp(yyjson_get_str(a), yyjson_get_str(b))) ||
          (yyjson_is_int(a) && yyjson_is_int(b) && yyjson_get_sint(a) == yyjson_get_sint(b)));
}
yyjson_mut_doc *mcp_dispatch(mcp_server_t *s, yyjson_doc *message, void *connection, const char *session_id,
                             bool *pending) {
  ASCII_OTEL_SCOPE(MCP_REQUEST);
  ASCII_OTEL_ATTR_STRING("rpc.system", "jsonrpc");
  ASCII_OTEL_ATTR_STRING("mcp.transport", s->policy.hosted ? "http" : "stdio");
  stats_counter_add(stats_runtime_scope(), STATS_COUNTER_MCP_REQUESTS, 1);
  *pending = false;
  yyjson_val *root = yyjson_doc_get_root(message), *id = mcp_get(root, "id"), *method = mcp_get(root, "method"),
             *version = mcp_get(root, "jsonrpc");
  if (!yyjson_is_obj(root) || !yyjson_is_str(version) || strcmp(yyjson_get_str(version), "2.0") ||
      !yyjson_is_str(method) || strlen(yyjson_get_str(method)) != yyjson_get_len(method) ||
      (id && !yyjson_is_str(id) && !yyjson_is_int(id)))
    return mcp_error(id, -32600, "Invalid JSON-RPC request");
  const char *name = yyjson_get_str(method);
  static const char *const methods[] = {
      "initialize", "ping", "tools/list", "tools/call", "notifications/initialized", "notifications/cancelled"};
  const char *method_name = "unknown";
  for (size_t i = 0; i < sizeof(methods) / sizeof(methods[0]); i++)
    if (!strcmp(name, methods[i]))
      method_name = methods[i];
  ASCII_OTEL_ATTR_STRING("rpc.method", method_name);
  yyjson_val *params = mcp_get(root, "params");
  if (params && !yyjson_is_obj(params))
    return id ? mcp_error(id, -32602, "params must be an object") : NULL;
  if (!id) {
    if (!strcmp(name, "notifications/initialized"))
      s->initialized = true;
    if (!strcmp(name, "notifications/cancelled")) {
      yyjson_val *cancel = mcp_get(params, "requestId");
      for (unsigned i = 0; i < s->policy.max_jobs; ++i)
        if (s->jobs[i].renderer_job.started &&
            (!s->policy.hosted || (session_id && *session_id && !strcmp(s->jobs[i].session_id, session_id)) ||
             ((!session_id || !*session_id) && s->jobs[i].connection == connection)) &&
            same_id(cancel, mcp_get(yyjson_doc_get_root(s->jobs[i].message), "id")))
          http_renderer_job_cancel(&s->jobs[i].renderer_job);
    }
    return NULL;
  }
  yyjson_mut_doc *d = envelope(id);
  yyjson_mut_val *result = yyjson_mut_obj(d);
  yyjson_mut_obj_add_val(d, yyjson_mut_doc_get_root(d), "result", result);
  if (!strcmp(name, "initialize")) {
    yyjson_val *requested = mcp_get(params, "protocolVersion");
    const char *v = yyjson_get_str(requested);
    if (!v || (strcmp(v, "2025-11-25") && strcmp(v, "2025-06-18") && strcmp(v, "2025-03-26")))
      v = "2025-11-25";
    yyjson_mut_obj_add_strcpy(d, result, "protocolVersion", v);
    yyjson_mut_val *caps = yyjson_mut_obj(d), *info = yyjson_mut_obj(d);
    yyjson_mut_obj_add_val(d, caps, "tools", yyjson_mut_obj(d));
    yyjson_mut_obj_add_val(d, result, "capabilities", caps);
    yyjson_mut_obj_add_str(d, info, "name", "ascii-chat");
    yyjson_mut_obj_add_str(d, info, "version", ASCII_CHAT_VERSION_FULL);
    yyjson_mut_obj_add_val(d, result, "serverInfo", info);
    const char *instructions =
        s->policy.restricted && s->policy.hosted
            ? "Render uploaded bytes or HTTP(S) media URLs as ASCII art. The hosted server cannot access your webcam "
              "or "
              "local filesystem. Rendered files are returned as temporary download links with UTC expiration "
              "timestamps; "
              "links expire after 30 minutes. Use output_format to select the file format, snapshot-delay to set clip "
              "duration, and options.audio=true to include source audio."
            : "Render media as ASCII art. Uploaded bytes must be base64 encoded by the client. snapshot-delay measures "
              "capture duration after the first rendered frame; use seek for media timestamps. output_path saves ASCII "
              "art "
              "as an image/video and never replaces an existing file.";
    yyjson_mut_obj_add_str(d, result, "instructions", instructions);
    return d;
  }
  if (!strcmp(name, "ping"))
    return d;
  if (!strcmp(name, "tools/list")) {
    yyjson_mut_obj_add_val(d, result, "tools", mcp_tools_schema(d, &s->policy));
    return d;
  }
  yyjson_mut_doc_free(d);
  if (strcmp(name, "tools/call"))
    return mcp_error(id, -32601, "Method not found");
  const char *tool = yyjson_get_str(mcp_get(params, "name"));
  if (tool && yyjson_get_len(mcp_get(params, "name")) == sizeof("device_list") - 1 && !strcmp(tool, "device_list")) {
    if (s->policy.restricted)
      return mcp_error(id, -32602, "Unknown tool");
    ASCII_OTEL_ATTR_STRING("mcp.tool", "device_list");
    return device_list_result(id, mcp_get(params, "arguments"));
  }
  const char *names[] = {"render_file", "render_url", "render_webcam", "render_visualization"};
  int kind = -1;
  for (int i = 0; i < 4; ++i)
    if (tool && strlen(tool) == yyjson_get_len(mcp_get(params, "name")) && !strcmp(tool, names[i]))
      kind = i;
  if (kind < 0 || (s->policy.restricted && kind == MCP_WEBCAM))
    return mcp_error(id, -32602, "Unknown tool");
  mcp_jobs_reap(s, false);
  mcp_job_t *j = NULL;
  for (unsigned i = 0; i < s->policy.max_jobs; ++i)
    if (!s->jobs[i].renderer_job.started) {
      j = &s->jobs[i];
      break;
    }
  if (!j) {
    char message[128];
    safe_snprintf(message, sizeof(message), "Server busy; at most %u render%s may run concurrently", s->policy.max_jobs,
                  s->policy.max_jobs == 1 ? "" : "s");
    return mcp_error(id, -32000, message);
  }
  yyjson_val *arguments = mcp_get(params, "arguments");
  yyjson_doc *empty = NULL;
  if (!arguments) {
    empty = yyjson_read("{}", 2, 0);
    arguments = yyjson_doc_get_root(empty);
  }
  asciichat_error_t err = mcp_request_parse(&s->policy, (mcp_tool_t)kind, arguments, &j->request);
  if (empty)
    yyjson_doc_free(empty);
  if (err != ASCIICHAT_OK) {
    stats_counter_add(stats_runtime_scope(), STATS_COUNTER_MCP_REJECTED, 1);
    ASCII_OTEL_ATTR_STRING("error.type", "invalid_arguments");
    asciichat_error_context_t ctx;
    http_renderer_process_result_t fail = {0};
    SAFE_STRNCPY(fail.error, HAS_ERRNO(&ctx) ? ctx.context_message : "Invalid render request", sizeof(fail.error));
    mcp_request_destroy(&j->request);
    return tool_result(id, &fail);
  }
  // Copy before returning to the transport, which owns and frees the input document.
  size_t len;
  char *copy = yyjson_write(message, 0, &len);
  j->message = yyjson_read(copy, len, 0);
  free(copy);
  j->tool = (mcp_tool_t)kind;
  j->telemetry_parent = ascii_otel_context();
  j->server = s;
  j->connection = connection;
  if (session_id)
    SAFE_STRNCPY(j->session_id, session_id, sizeof(j->session_id));
  if (http_renderer_job_start(&j->renderer_job, "mcp-render", run_job, j) != ASCIICHAT_OK) {
    mcp_request_destroy(&j->request);
    yyjson_doc_free(j->message);
    memset(j, 0, sizeof(*j));
    return mcp_error(id, -32603, "Cannot create render worker");
  }
  *pending = true;
  return NULL;
}