feat(pose-lib): apply_pose_masked MCP tool

src/MCPServer.cpp

@@ -611,7 +611,8 @@
         {QStringLiteral("delete_pose"), &MCPServer::toolDeletePose},
         {QStringLiteral("mirror_pose"), &MCPServer::toolMirrorPose},
         {QStringLiteral("save_pose_library"), &MCPServer::toolSavePoseLibrary},
-        {QStringLiteral("load_pose_library"), &MCPServer::toolLoadPoseLibrary}
+        {QStringLiteral("load_pose_library"), &MCPServer::toolLoadPoseLibrary},
+        {QStringLiteral("apply_pose_masked"), &MCPServer::toolApplyPoseMasked}
     };
     return handlers;
 }
@@ -4701,6 +4702,45 @@
         QString::fromUtf8(QJsonDocument(content).toJson(QJsonDocument::Indented)));
 }
 
+QJsonObject MCPServer::toolApplyPoseMasked(const QJsonObject &args)
+{
+    SentryReporter::addBreadcrumb("ai.tool_call", "apply_pose_masked");
+    const QString name = args.value("name").toString();
+    if (name.isEmpty())
+        return makeErrorResult("Error: missing required 'name' argument");
+    if (!args.contains("bones"))
+        return makeErrorResult("Error: missing required 'bones' argument");
+    const QJsonValue bonesV = args.value("bones");
+    if (!bonesV.isArray())
+        return makeErrorResult("Error: 'bones' must be an array of bone-name strings");
+
+    // Strict-parse: every entry must be a string. A non-string slot
+    // would silently degrade to empty (toString returns "") and the
+    // mask would match unintended bones.
+    QStringList boneNames;
+    const QJsonArray arr = bonesV.toArray();
+    for (int i = 0; i < arr.size(); ++i) {
+        if (!arr[i].isString())
+            return makeErrorResult(
+                QString("Error: 'bones'[%1] must be a string").arg(i));
+        boneNames << arr[i].toString();
+    }
+
+    auto* lib = PoseLibrary::instance();
+    if (!lib->applyPoseMaskedForSelection(name, boneNames))
+        return makeErrorResult(
+            QString("Error: failed to apply pose '%1' masked "
+                    "(no selection, no skeleton, or pose not found)")
+                .arg(name));
+
+    QJsonObject content;
+    content["ok"] = true;
+    content["name"] = name;
+    content["bone_count"] = boneNames.size();
+    return makeSuccessResult(
+        QString::fromUtf8(QJsonDocument(content).toJson(QJsonDocument::Indented)));
+}
+
 QJsonArray MCPServer::buildToolsList()
 {
     QJsonArray tools;
@@ -6008,6 +6048,26 @@
         );
     }
 
+    // apply_pose_masked
+    {
+        QJsonObject props;
+        props["name"] = QJsonObject{{"type", "string"}, {"description", "Pose name (use list_poses to enumerate)."}};
+        props["bones"] = QJsonObject{{"type", "array"},  {"description", "Bone names to apply. Bones NOT in this list keep their current TRS. Empty list = no-op (returns success but touches no bones)."}};
+        QJsonArray required;
+        required.append("name");
+        required.append("bones");
+        appendTool(
+            "apply_pose_masked",
+            "Apply a saved pose to ONLY the listed bones. Use case: "
+            "snap to a facial expression without disturbing the "
+            "current body pose, or apply an arm gesture without "
+            "re-posing legs. Bones in the list but missing from the "
+            "skeleton (LOD change) are skipped silently.",
+            props,
+            required
+        );
+    }
+
     // bake_vat
     {
         QJsonObject props;

src/MCPServer.h

@@ -261,6 +261,12 @@ private slots:
     /// in memory. Args: `path`.
     QJsonObject toolLoadPoseLibrary(const QJsonObject &args);
 
+    /// Pose-lib D5: apply a saved pose only to a subset of bones.
+    /// Args: `name` (pose), `bones` (JSON array of bone-name
+    /// strings). Use case: facial expression without disturbing
+    /// the body pose.
+    QJsonObject toolApplyPoseMasked(const QJsonObject &args);
+
     // Animation
     struct NodeAnimation {
         Ogre::SceneNode* node;

src/MCPServer_test.cpp

@@ -7334,3 +7334,41 @@ TEST_F(MCPServerTest, LoadPoseLibrary_MissingFileRejected)
     QJsonObject r = server->callTool("load_pose_library", args);
     EXPECT_TRUE(isError(r));
 }
+
+TEST_F(MCPServerTest, ApplyPoseMasked_MissingNameRejected)
+{
+    QJsonObject args;
+    args["bones"] = QJsonArray{"Spine"};
+    QJsonObject r = server->callTool("apply_pose_masked", args);
+    EXPECT_TRUE(isError(r));
+    EXPECT_TRUE(getResultText(r).contains("name"));
+}
+
+TEST_F(MCPServerTest, ApplyPoseMasked_MissingBonesRejected)
+{
+    QJsonObject args;
+    args["name"] = "MCP_AnyPose";
+    QJsonObject r = server->callTool("apply_pose_masked", args);
+    EXPECT_TRUE(isError(r));
+    EXPECT_TRUE(getResultText(r).contains("bones"));
+}
+
+TEST_F(MCPServerTest, ApplyPoseMasked_NonArrayBonesRejected)
+{
+    QJsonObject args;
+    args["name"] = "MCP_AnyPose";
+    args["bones"] = "not an array";
+    QJsonObject r = server->callTool("apply_pose_masked", args);
+    EXPECT_TRUE(isError(r));
+    EXPECT_TRUE(getResultText(r).contains("bones"));
+}
+
+TEST_F(MCPServerTest, ApplyPoseMasked_NonStringBoneRejected)
+{
+    QJsonObject args;
+    args["name"] = "MCP_AnyPose";
+    args["bones"] = QJsonArray{"OK", 42};  // int instead of string
+    QJsonObject r = server->callTool("apply_pose_masked", args);
+    EXPECT_TRUE(isError(r));
+    EXPECT_TRUE(getResultText(r).contains("bones"));
+}

src/PoseLibrary.cpp

@@ -522,6 +522,17 @@
     return applyPose(ents.first(), name);
 }
 
+bool PoseLibrary::applyPoseMaskedForSelection(const QString& name,
+                                              const QStringList& boneNames)
+{
+    auto* sel = SelectionSet::getSingleton();
+    if (!sel) return false;
+    auto ents = sel->getResolvedEntities();
+    if (ents.isEmpty()) return false;
+    QSet<QString> mask(boneNames.cbegin(), boneNames.cend());
+    return applyPoseMasked(ents.first(), name, mask);
+}
+
 bool PoseLibrary::deletePoseForSelection(const QString& name)
 {
     auto* sel = SelectionSet::getSingleton();

src/PoseLibrary.h

@@ -171,6 +171,12 @@ class PoseLibrary : public QObject
     /// "Pose Library" subgroup.
     Q_INVOKABLE bool savePoseForSelection(const QString& name);
     Q_INVOKABLE bool applyPoseForSelection(const QString& name);
+
+    /// Selection wrapper for D5 apply-with-mask. `boneNames` is a
+    /// QML/MCP-friendly QStringList; internally converted to QSet
+    /// for the underlying `applyPoseMasked` call.
+    Q_INVOKABLE bool applyPoseMaskedForSelection(const QString& name,
+                                                  const QStringList& boneNames);
     Q_INVOKABLE bool deletePoseForSelection(const QString& name);
     Q_INVOKABLE bool mirrorPoseForSelection(const QString& srcName,
                                              const QString& dstName);