support generating json schema for tools

[christophsturm]

the mcp docs for tools contain this:
Best practices

When implementing tools:
...
Use detailed JSON Schema definitions for parameters
..

and the typescript sdk examples just dynamically create json schema from the zod types that the typescript examples use. it would be great if the kotlin sdk has something like this too, or an example how to do it. (the current example is very bare bones)

[morisil]

I'm the author of open source library providing this functionality:

https://github.com/xemantic/xemantic-ai-tool-schema

[christophsturm]

@morisil how can i use that with the kotlin mcp sdk? the json schema field is of type Input:

    @Serializable
    public data class Input(
        val properties: JsonObject = EmptyJsonObject,
        val required: List<String>? = null,
    ) {
        val type: String = "object"
    }

or are you suggesting to fork the sdk? also your claudine library seems to have some overlap with mcp in general, are you planning to make it mcp compatible?

[morisil]

As a quick workaround - add a function translating JsonSchema instance, as produced by my library, to the Input instance of this SDK Tool. Or even instantiate the whole Tool with description from annotated class, as I am doing in my antrhopic-sdk-kotlin:

https://github.com/xemantic/anthropic-sdk-kotlin#using-tools

A long term solution I would like to propose for this project - move my xemantic-ai-tool-schema under the umbrella of the mcp project, and use the JsonSchema class in the API. The argument for this is that such a JsonSchema can be used in several other SDKs, for other LLMs, avoiding boilerplate and translation layers.

[morisil]

Regarding Claudine, I want to keep Claudine1 as an educational project showing the simplest Unix-omnipotent agent on top of the anthropic-sdk-kotlin, with multiplatform compilation targets. Claudine2 I am developing at the moment (might have a different name), will utilize MCP to a great extent.

[morisil]

@christophsturm As a quick workaround you can use something like:

import com.xemantic.ai.tool.schema.ObjectSchema
import com.xemantic.ai.tool.schema.generator.jsonSchemaOf
import io.modelcontextprotocol.kotlin.sdk.Tool.Input
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.encodeToJsonElement
import kotlinx.serialization.json.jsonArray
import kotlinx.serialization.json.jsonObject
import kotlinx.serialization.json.jsonPrimitive

public fun ObjectSchema.toMdcToolInput(): Input =
    Json.encodeToJsonElement(this).jsonObject.run {
        Input(
            properties = get("properties")!!.jsonObject,
            required = get("required")?.jsonArray?.map {
                it.jsonPrimitive.content
            }
        )
    }

public inline fun <reified T> Any.mdcToolInput(): Input =
    (jsonSchemaOf<T>() as ObjectSchema).toMdcToolInput()

Here is a test case:

import com.xemantic.kotlin.test.be
import com.xemantic.kotlin.test.have
import com.xemantic.kotlin.test.should
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive
import kotlin.test.Test

class ObjectSchemaToMdcToolInputTest {

    @Serializable
    private data class Foo(
        val bar: String
    )

    @Test
    fun `Should convert class to MDC Tool Input`() {
        val input = mdcToolInput<Foo>()
        println(input)
        input should {
            have(properties.size == 1)
            properties["bar"] should {
                be<JsonObject>()
                have(size == 1)
                get("type") should {
                    be<JsonPrimitive>()
                    have(content == "string")
                }
            }
            have(required == listOf("bar"))
        }
    }

}

I will package it as a separate library for the time being. Should appear soon here:

https://github.com/xemantic/xemantic-ai-tool-schema-mdc

[morisil]

On a side note, I believe there is a major issue associated with how Tool.Input class is currently defined. It does not cover definitions property, therefore only single object level schemas can be expressed. It is not enough even for my basic use cases, where LLM is calling my tool with properties of type Vector2.

[morisil]

Ok, the project is there, and v0.1 released to maven central:

dependencies {
    implementation("com.xemantic.ai:xemantic-ai-tool-schema-mdc:0.1")
}

[christophsturm]

On a side note, I believe there is a major issue associated with how Tool.Input class is currently defined. It does not cover definitions property, therefore only single object level schemas can be expressed. It is not enough even for my basic use cases, where LLM is calling my tool with properties of type Vector2.

maybe file a separate issue for that with an example?

[ssuukk]

Locally I have some code that generates proper JSON schema directly from class, like:

@Serializable
class Prop (
    @SchemaDescription("The city and state, e.g. San Francisco, CA")
    val location: String,

    @SchemaDescription("The temperature unit to use. Infer this from the users location.")
    val format: TempType,

    @SchemaDescription("The number of days to forecast")
    @SerialName("num_days")
    val nunDays: Int
)

Then you call

buildParametersSchema(Prop.serializer()))

And get JsonObject that contains this:

{
    "type": "object",
    "properties": {
        "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
        },
        "format": {
            "type": "string",
            "enum": [
                "celsius",
                "fahrenheit"
            ],
            "description": "The temperature unit to use. Infer this from the users location."
        },
        "num_days": {
            "type": "integer",
            "description": "The number of days to forecast"
        }
    },
    "required": [
        "location",
        "format",
        "num_days"
    ]
}

[upeter]

Ok, the project is there, and v0.1 released to maven central:

dependencies {
    implementation("com.xemantic.ai:xemantic-ai-tool-schema-mdc:0.1")
}

Though I think xemantic is a great solution for data class to schema conversion, I see something similar popping up in koog:

https://docs.koog.ai/structured-data/

val weatherForecastStructure = JsonStructuredData.createJsonStructure<WeatherForecast>(
    schemaGenerator = BasicJsonSchemaGenerator.Default,
    examples = exampleForecasts
)

t would be great to have an official, common approach for Kotlin Serialization–based schema generation, regardless of the library used—I have no strong preference.

In Spring (spring-ai), schema generation is fully abstracted, which makes it much simpler and more intuitive. Since it’s Jackson-based, you never have to deal with raw JsonObject; you just define data classes and the schema is generated automatically. I believe this is the right level of abstraction for Kotlin as well.