Merge pull request #63 from OpenAF/codex/add-handlebars-template-flag-to-ojobmcp.yaml

MCP: add templated tool descriptions and tool name prefixing for HTTP/STDIO servers

Author: nmaguiar

.package.yaml

@@ -37,7 +37,7 @@ name: oJob-common
 main: ''
 mainJob: ''
 license: Apache 2.0
-version: '20260228'
+version: '20260309'
 dependencies:
   openaf: '>=20251115'
 files:
@@ -83,7 +83,7 @@ filesHash:
   oJobHBS.yaml: ab15b0efd31f95ee770c77dace146035e0781661
   oJobHTTPd.yaml: ca7b876513bf380be043528adc972c9974394486
   oJobIO.yaml: 8108313099abf9d1115a3d428b68a203b8d5c2e2
-  oJobMCP.yaml: 65340bcd98481e228cd638e55f588132254c8ac6
+  oJobMCP.yaml: 107a8c48850c1e33888b1b636b100e256bd4a7bc
   oJobManager.yaml: 5ad9ecf276bbee8b6503d0e3b40b007f2724507d
   oJobNet.yaml: 4413085d38724249587f6a790d7e1952a4d9c138
   oJobOPack.yaml: b4e78c90de2a72bfe1bca21e2143de4715431e87

oJobMCP.yaml

@@ -18,6 +18,8 @@ jobs:
         uri        : uri
         usestream  : usestream
         debug      : debug
+        tplDesc    : tplDesc
+        toolPrefix : toolPrefix
         fnsMeta    : fnsMeta
         fns        : fns
   help    :
@@ -31,6 +33,10 @@ jobs:
       desc: (Boolean) If true, returns responses as HTTP SSE stream events.
     - name: debug
       desc: (Boolean) If true, debug messages will be logged.
+    - name: tplDesc
+      desc: (Boolean) If true, all tool description fields in fnsMeta are evaluated as handlebars templates with the current oJob args.
+    - name: toolPrefix
+      desc: (String) If defined, prefixes exposed MCP tool names without changing fns/fnsMeta key mapping.
     - name: fnsMeta
       desc: (Map) Metadata for the functions available in the MCP server.
     - name: fns
@@ -42,11 +48,32 @@ jobs:
       uri        : isString.default("/mcp")
       usestream  : toBoolean.isBoolean.default(false)
       debug      : toBoolean.isBoolean.default(false)
+      tplDesc    : toBoolean.isBoolean.default(false)
+      toolPrefix : isString.default("")
       fnsMeta    : isMap.default({})
       fns        : isMap.default({})
   deps    :
   - HTTP Start Server
   exec    : | #js
+    var _applyTemplate = (meta, allStrings) => {
+      if (!args.tplDesc) return meta
+      var _walk = obj => {
+        if (isString(obj) && allStrings) return $t(obj, args)
+        if (isArray(obj)) return obj.map(_walk)
+        if (isMap(obj)) {
+          Object.keys(obj).forEach(k => {
+            if (isString(obj[k]) && (allStrings || k == "description")) {
+              obj[k] = $t(obj[k], args)
+            } else {
+              obj[k] = _walk(obj[k])
+            }
+          })
+        }
+        return obj
+      }
+      return _walk(meta)
+    }
+
     // Ensures default server info and capabilities
     args.description = merge({
       protocolVersion: "2024-11-05",
@@ -64,9 +91,35 @@ jobs:
           }
       }
     }, args.description)
+    args.description = _applyTemplate(clone(args.description), true)
 
     fns = {}
 
+    var _applyTemplateToDescriptions = meta => _applyTemplate(meta, false)
+
+    var _prefixToolName = n => (isString(args.toolPrefix) && args.toolPrefix.length > 0 ? args.toolPrefix + n : n)
+    var _resolveToolName = n => {
+      if (isString(args.toolPrefix) && args.toolPrefix.length > 0 && isString(n) && n.startsWith(args.toolPrefix)) {
+        return n.substring(args.toolPrefix.length)
+      }
+      return n
+    }
+    var _toToolMeta = f => {
+      var _meta
+      if (isDef(args.fnsMeta[f])) {
+        _meta = _applyTemplateToDescriptions(clone(args.fnsMeta[f]))
+      } else {
+        _meta = {
+          name       : f,
+          description: f,
+          inputSchema: {}
+        }
+      }
+      if (!isMap(_meta)) _meta = { name: f, description: String(_meta), inputSchema: {} }
+      _meta.name = _prefixToolName(f)
+      return _meta
+    }
+
     if (args.usestream) {
       fns[args.uri] = req => {
         try {
@@ -84,10 +137,11 @@ jobs:
               "tools/call"               : params => {
                   if (args.debug) log(`tools/call -- ${af.toCSLON(params)}`)
                   var _res
-                  if (isDef(args.fns[params.name])) {
+                  var _toolName = _resolveToolName(params.name)
+                  if (isDef(args.fns[_toolName])) {
                     try {
-                      if (isString(args.fns[params.name])) {
-                        _res = $job(args.fns[params.name], merge({ _httprequest: req }, params.arguments || params.input || {}))
+                      if (isString(args.fns[_toolName])) {
+                        _res = $job(args.fns[_toolName], merge({ _httprequest: req }, params.arguments || params.input || {}))
                         if (isMap(_res)) {
                           delete _res.objId
                           delete _res.execid
@@ -106,7 +160,7 @@ jobs:
                           }
                         }
                       } else {
-                        throw "Function not found: " + params.name
+                        throw "Function not found: " + _toolName
                       }
                     } catch(e) {
                       logErr(`Error executing tool '${params.name}': ${e.message}`)
@@ -155,17 +209,7 @@ jobs:
               },
               "tools/list": params => {
                   if (args.debug) log(`tools/list -- ${af.toCSLON(params)}`)
-                  var _fnsMeta = Object.keys(args.fns).map(f => {
-                    if (isDef(args.fnsMeta[f])) {
-                      return clone(args.fnsMeta[f])
-                    } else {
-                      return {
-                        name       : f,
-                        description: f,
-                        inputSchema: {}
-                      }
-                    }
-                  })
+                  var _fnsMeta = Object.keys(args.fns).map(f => _toToolMeta(f))
                   return {
                       tools: _fnsMeta
                   }
@@ -256,10 +300,11 @@ jobs:
             "tools/call"               : params => {
                 if (args.debug) log(`tools/call -- ${af.toCSLON(params)}`)
                 var _res
-                if (isDef(args.fns[params.name])) {
+                var _toolName = _resolveToolName(params.name)
+                if (isDef(args.fns[_toolName])) {
                   try {
-                    if (isString(args.fns[params.name])) {
-                      _res = $job(args.fns[params.name], merge({ _httprequest: req }, params.arguments || params.input || {}))
+                    if (isString(args.fns[_toolName])) {
+                      _res = $job(args.fns[_toolName], merge({ _httprequest: req }, params.arguments || params.input || {}))
                       if (isMap(_res)) {
                         delete _res.objId
                         delete _res.execid
@@ -278,7 +323,7 @@ jobs:
                         }
                       }
                     } else {
-                      throw "Function not found: " + params.name
+                      throw "Function not found: " + _toolName
                     }
                   } catch(e) {
                     logErr(`Error executing tool '${params.name}': ${e.message}`)
@@ -327,17 +372,7 @@ jobs:
             },
             "tools/list": params => {
                 if (args.debug) log(`tools/list -- ${af.toCSLON(params)}`)
-                var _fnsMeta = Object.keys(args.fns).map(f => {
-                  if (isDef(args.fnsMeta[f])) {
-                    return clone(args.fnsMeta[f])
-                  } else {
-                    return {
-                      name       : f,
-                      description: f,
-                      inputSchema: {}
-                    }
-                  }
-                })
+                var _fnsMeta = Object.keys(args.fns).map(f => _toToolMeta(f))
                 return {
                     tools: _fnsMeta
                 }
@@ -366,6 +401,8 @@ jobs:
       keyArg: description
       args  :
         debug      : debug
+        tplDesc    : tplDesc
+        toolPrefix : toolPrefix
         fnsMeta    : fnsMeta
         fns        : fns
   help    :
@@ -375,15 +412,40 @@ jobs:
       desc: (String) If defined it will create a ndjson file with the provided name.
     - name: fnsMeta
       desc: (Map) Metadata for the functions available in the MCP server stdio.
+    - name: tplDesc
+      desc: (Boolean) If true, all tool description fields in fnsMeta are evaluated as handlebars templates with the current oJob args.
+    - name: toolPrefix
+      desc: (String) If defined, prefixes exposed MCP tool names without changing fns/fnsMeta key mapping.
     - name: fns
       desc: (Map) Functions to be executed when called from the MCP server stdio.
   check   :
     in: 
       description: isMap.default(__)
       debug      : isString.default(__)
+      tplDesc    : toBoolean.isBoolean.default(false)
+      toolPrefix : isString.default("")
       fnsMeta    : isMap.default({})
       fns        : isMap.default({})
   exec    : | #js
+    var _applyTemplate = (meta, allStrings) => {
+      if (!args.tplDesc) return meta
+      var _walk = obj => {
+        if (isString(obj) && allStrings) return $t(obj, args)
+        if (isArray(obj)) return obj.map(_walk)
+        if (isMap(obj)) {
+          Object.keys(obj).forEach(k => {
+            if (isString(obj[k]) && (allStrings || k == "description")) {
+              obj[k] = $t(obj[k], args)
+            } else {
+              obj[k] = _walk(obj[k])
+            }
+          })
+        }
+        return obj
+      }
+      return _walk(meta)
+    }
+
     // Ensures default server info and capabilities
     args.description = merge({
       protocolVersion: "2024-11-05",
@@ -401,11 +463,39 @@ jobs:
           }
       }
     }, args.description)
+    args.description = _applyTemplate(clone(args.description), true)
 
     var fs = {}
-    Object.keys(args.fns).map(f => {
-      fs[f] = function(params) {
-        var _r = $job(args.fns[f], params)
+    var _applyTemplateToDescriptions = meta => _applyTemplate(meta, false)
+
+    var _prefixToolName = n => (isString(args.toolPrefix) && args.toolPrefix.length > 0 ? args.toolPrefix + n : n)
+    var _resolveToolName = n => {
+      if (isString(args.toolPrefix) && args.toolPrefix.length > 0 && isString(n) && n.startsWith(args.toolPrefix)) {
+        return n.substring(args.toolPrefix.length)
+      }
+      return n
+    }
+    var _toToolMeta = f => {
+      var _meta
+      if (isDef(args.fnsMeta[f])) {
+        _meta = _applyTemplateToDescriptions(clone(args.fnsMeta[f]))
+      } else {
+        _meta = {
+          name       : f,
+          description: f,
+          inputSchema: {}
+        }
+      }
+      if (!isMap(_meta)) _meta = { name: f, description: String(_meta), inputSchema: {} }
+      _meta.name = _prefixToolName(f)
+      return _meta
+    }
+
+    Object.keys(args.fns).forEach(f => {
+      var _toolName = _prefixToolName(f)
+      fs[_toolName] = function(params) {
+        var _jobName = _resolveToolName(_toolName)
+        var _r = $job(args.fns[_jobName], params)
         if (isMap(_r)) {
           delete _r.objId
           delete _r.execid
@@ -420,7 +510,7 @@ jobs:
       }
     })
 
-    ow.server.mcpStdio(args.description, Object.values(args.fnsMeta), 
+    ow.server.mcpStdio(args.description, Object.keys(args.fns).map(f => _toToolMeta(f)), 
       fs,
       (type, msg) => {
       if (args.debug) {