code.mcp

Agent-facing MCP tool surface.

code.mcp exposes foundation maintenance actions as MCP tools, including code management, test execution, documentation helpers, Maven helpers, JVM namespace helpers, and hara.lang probes.

1 Motivation

Agents need structured operations instead of ad hoc shell commands. The MCP layer packages safe, named capabilities around the existing code.*, jvm.*, and hara.* toolchains.

2 Internal usage

code.mcp.server/default-instructions advertises code-manage, code-test, hara-lang, and code-maven capabilities. Individual tool namespaces wrap the same functions that maintainers can run from the REPL or Leiningen.

3 Walkthrough

3.1 Basic connectivity tools

Every MCP server exposes small tools for health checks. echo-fn and ping-fn return simple responses and are useful when wiring up a new client.

echo returns the input text

(basic/echo-fn nil {:text "hello"})
=> {:content [{:type "text" :text "hello"}]
    :isError false}

ping returns a ping response

(basic/ping-fn nil nil)
=> {:content [{:type "text" :text "ping"}]
    :isError false}

3.2 Server setup

default-tools lists the tools advertised by the server, and default-instructions tells clients which project tools to prefer.

default tools include expected names

(->> (server/default-tools)
     (map :name)
     set)
=> #{"echo" "ping"
     "clj-eval" "code-test" "code-manage" "jvm-namespace"
     "lang-emit-as" "hara.lang-list" "hara.lang-modules"
     "code-doc-init" "code-doc-deploy" "code-doc-publish"
     "code-maven"
     "form-heal-list-edits" "form-heal-get-dsl-deps" "form-heal-refactor-directory"}

instructions advertise project-specific tools

[(re-find #"code-test" (server/default-instructions))
 (re-find #"code-manage" (server/default-instructions))]
=> ["code-test" "code-manage"]

3.3 Tool responses

common/response wraps raw results in the MCP text-content shape, and error-response builds an error payload.

wrap a result in MCP content format

(common/response {:result 42})
=> {:content [{:type "text" :text "{:result 42}\n"}]
    :isError false}

wrap an error message

(common/error-response "something went wrong")
=> {:content [{:type "text" :text "something went wrong"}]
    :isError true}

3.4 End-to-end: create a server instance

create-server assembles the configured server without starting network transport. It is useful for inspecting the advertised tool set in tests.

create a server map

(let [s (server/create-server)]
  [(contains? s :provider)
   (contains? s :server)
   (contains? s :tool-specs)])
=> [true true true]